Sign in

v1

latestOpenAPI 3.1.02026-08-04103211436.0 KB
Operations

Create operation

Creates an operation (invoice/bill) with an optional customId; if omitted, Embat auto-generates one. Sending an operation whose customId already exists updates it, except when the existing operation already has a payment recorded against it in Embat: in that case the request has no effect on most fields — only dueDate and/or paymentDate are applied, and only when the operation's current status is pending or overdue; any other field in the payload is silently discarded. An operation with amount equal to 0 is silently discarded and not created. While an operation belongs to an invoice group (remittance), resending it through this endpoint leaves it unchanged (200 is still returned): its status is managed by the remittance that groups it — see the tag description for the remittance flow.

post/operations/{companyId}

Path parameters

companyIdstring required

Request body

status'paymentOrder' | 'cancel' | 'paid' | 'payment_in_progress' | 'overdue' | 'pending' | 'shipped'
paymentDatestring date-time nullable

Date the operation is expected to be (or was) paid. Only the calendar date is meaningful; the time component is not preserved as sent.

chargeAccountstring nullable

IBAN of your own bank account the operation is charged to.

contactAccountstring nullable

IBAN of the counterparty's (contact's) bank account.

issuanceDatestring date-time required

Issuance date of the operation's source document. Only the calendar date is meaningful; the time component is not preserved as sent. If dueDate is omitted, it defaults to this date, and paymentDate in turn defaults to dueDate.

dueDatestring date-time required

Due date of the operation. Only the calendar date is meaningful; the time component is not preserved as sent. On creation, unless status is explicitly set to paid, cancel or payment_in_progress, the operation's status is computed from this date: pending if it is today or later, overdue otherwise.

accountingCodestring nullable

Accounting account code the operation is posted to.

accountingNamestring nullable

Accounting account name the operation is posted to.

operationsCustomIdsstring[] nullable

Custom IDs of other operations grouped under this one, to represent an invoice group or remittance (typically combined with documentType set to invoiceGroup). Takes effect on POST (create or upsert): each referenced operation is marked paid, its pendingAmount/pendingAccountingAmount set to 0 and its payment date set to this operation's paymentDate. Resending the remittance without some previously grouped operations releases them: they return to pending with their full pending amount. Sending this field on a PATCH update has no effect.

conceptstring required

Free-text description of the operation.

amountnumber required

Total amount of the operation, in currency.

accountingAmountnumber nullable

Amount of the operation expressed in the company accounting currency. If omitted, it defaults to amount (and accountingCurrency is reset to currency). Note: whenever the resulting accountingCurrency equals currency, this value is forced to amount, even if you explicitly sent a different value.

pendingAmountnumber nullable

Amount still pending settlement, in currency. Defaults to amount when omitted.

pendingAccountingAmountnumber nullable

Amount still pending settlement, expressed in the accounting currency. If omitted, it is derived proportionally from pendingAmount and accountingAmount; it is 0 when amount or accountingAmount is 0.

currency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTC' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNH' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EEK' | 'EGP' | 'ERN' | 'ETB' | 'ETH' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTC' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWG' | 'ZWL' required
accountingCurrency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTC' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNH' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EEK' | 'EGP' | 'ERN' | 'ETB' | 'ETH' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTC' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWG' | 'ZWL'
exchangeRatenumber nullable

Exchange rate applied between currency and accountingCurrency. If omitted, it is derived from amount/accountingAmount (1.0 when accountingAmount is 0). Note: whenever amount equals accountingAmount, the value is forced to 1.0, even if you explicitly sent a different one; out-of-range or non-finite values are also silently reset to 1.0.

paymentMethodstring nullable

Payment method associated with the operation (e.g. bank-transaction, promissory-note).

additionalInfoobject nullable

Free-form key/value metadata to attach to the operation.

invoiceGroupDocumentIdstring nullable

Identifier of the invoice group this operation belongs to, if any.

syncboolean

Marks the operation as synchronized on your side.

documentIdstring nullable

Identifier of the source document (e.g. invoice number).

externalReferencestring nullable

Free-form reference to this operation in an external system.

customIdstring nullable

Your own unique ID for the operation. If omitted, Embat auto-generates one.

documentType'invoice' | 'other' | 'note' | 'invoiceGroup' | 'confirming' | 'deposit' | 'factoring' | 'tax' | 'amortizationQuote' | 'amortizationInterest' | 'amortizationTax' | 'refund' | 'paymentDocument' | 'cheque' | 'deliveryNote' | 'purchaseOrder' | 'employeeExpense'
generatedFrom'erp' | 'external'

Example request

{
  "concept": "Invoice #2024-001",
  "amount": 1250.5,
  "accountingAmount": 1250.5,
  "pendingAmount": 1250.5,
  "pendingAccountingAmount": 1250.5,
  "exchangeRate": 1,
  "paymentMethod": "bank-transaction",
  "contact": {
    "tradeName": "Acme Supplies",
    "legalName": "Acme Supplies S.L.",
    "taxId": "B12345678",
    "contact": {
      "phone": "+34600000000",
      "email": "billing@acme-supplies.com",
      "name": "John",
      "surname": "Doe"
    },
    "address": {
      "postalCode": "28001",
      "address": "Calle Mayor 10, 3B",
      "province": "Madrid",
      "city": "Madrid",
      "country": "Spain"
    },
    "accounts": [
      {
        "swift": "BBVAESMMXXX",
        "iban": "ES9121000418450200051332"
      }
    ],
    "paymentsAccounts": [
      {
        "details": {
          "iban": "ES9121000418450200051332",
          "bic": "BBVAESMMXXX",
          "swift": "BBVAESMMXXX",
          "accountNumber": "123456789",
          "routingNumber": "021000021",
          "sortCode": "040004",
          "institutionNumber": "001",
          "transitNumber": "12345",
          "bsb": "062-000"
        }
      }
    ],
    "accountingCode": "4300001",
    "paymentMethod": "bank-transaction",
    "paymentTerms": 30,
    "attributes": [
      {
        "customId": "cost-center",
        "value": "Marketing",
        "valueCustomId": "marketing"
      }
    ],
    "customId": "erp-contact-001"
  },
  "attributes": [
    {
      "customId": "cost-center",
      "value": "Marketing",
      "valueCustomId": "marketing"
    }
  ],
  "customId": "invoice-2024-001"
}

Response

Successful Response

idstring required

Embat resource ID

customIdstring required

Client-provided custom ID