Sales Invoice v1-beta

The /salesInvoice endpoints are used to send sales invoices.

Query recipient party

When a receiver has multiple ids registered in Peppol or other networks, and you're unsure which id to use, or if you want to make sure the id you're sending to is registered in the Peppol network, you can use the POST /api/v1-beta/{partyId}/salesInvoice/queryRecipientParty endpoint. The {partyId} specified in the route should be the sender's partyId. The request body accepts either an array of partyIds or an object containing partyIds with optional metaAttributes, in JSON. The response will contain the recipient party that should be used as endpointId in the sales invoice, as well as the delivery channel.

The query parameter ?preferredDocumentTypeId can be used if a specific documentTypeId is preferred. Specifying a preferred documentTypeId will make sure the documentTypeId is prioritized in the lookup.

Request formats

Array (partyIds only):

[
  "0106:12345678"
]

Object (partyIds with optional metaAttributes):

{
  "partyIds": [
    "0106:12345678"
  ],
  "metaAttributes": {
    "AdditionalProp1": "string",
    "AdditionalProp2": "string",
    "AdditionalProp3": "string"
  }
}

The optional metaAttributes can be used to pass additional context to the lookup. For example, they can be referenced in hook filters to select a specific delivery channel.

Additionally, the API can return other available delivery options (channels), which can be used to override the recommended option if issues arise, such as an invalid channel. The query parameter ?includeOptions can be used to retreive the optional channels. By default the options are not included in the response.

Example reponse:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery",
  "message": "possible error message in case of an issue",
  "options": [
    {
      "channel": "peppol",
      "description": "default send via peppol delivery",
      "identifiers": [
        {
          "partyId": {
            "text": "NL:KVK:12345678",
            "value": "12345678",
            "schemeAuthority": "iso6523-actorid-upis",
            "schemeIdText": "NL:KVK",
            "schemeIdNumber": "0106"
          },
          "message": "possible error message in case of an issue",
          "isValid": true
        }
      ]
    }
  ]
}

In case there are no valid delivery options are found, a 404 response will be returned with optional delivery options.

Example reponse:

{
  "helpLink": "https://psb.econnect.eu/endpoints/v1-beta/SalesInvoice.html#query-recipient-party",
  "message": "Not found.",
  "code": "API404",
  "requestId": "1418f2a91fcba0c3e143ce41181efe46",
  "dateTime": "2025-09-19T09:41:46.2622423+00:00",
  "options": [
    {
      "channel": "peppol",
      "description": "default send via peppol delivery",
      "identifiers": [
        {
          "partyId": {
            "text": "NL:KVK:12345678",
            "value": "12345678",
            "schemeAuthority": "iso6523-actorid-upis",
            "schemeIdText": "NL:KVK",
            "schemeIdNumber": "0106"
          },
          "message": "possible error message in case of an issue",
          "isValid": true
        }
      ]
    }
  ]
}

Response

As the seller, you can report a status on an invoice you previously sent using the POST /api/v1-beta/{partyId}/salesInvoice/{documentId}/response endpoint. The {partyId} in the route is your own (seller) partyId, and {documentId} is the documentId returned when the sales invoice was sent.

Where the buyer-side Invoice Response reports how a received invoice is being processed, this endpoint lets the sender report back on an invoice that has already left the door. Its primary use case is reporting lifecycle statuses for Continuous Transaction Controls (CTC) regulations, such as "Encaissée"/212 (paid/cashed).

Request body

Field	Required	Description
status	yes	The status code, e.g. AP for accepted, RE for rejected, or a lifecycle code such as 212.
reasons	no	A clarification of the status, keyed by status clarification reason code.
actions	no	The expectation towards the counterparty, keyed by status clarification action code.
attributes	no	Additional free-form attributes. Typically used to carry lifecycle information such as effectiveDateTime and amounts.
note	no	A free-text note with comments or instructions that apply to the whole response.

Lifecycle status example

Report that a previously sent invoice has been partially paid:

{
  "status": "212",
  "attributes": {
    "effectiveDateTime": "2026-07-27T12:00:00+00:00",
    "amounts": [
      { "typeCode": "MEN", "amount": "1000.00", "vatPercentage": "20.00" },
      { "typeCode": "MEN", "amount": "200.00", "vatPercentage": "5.50", "currency": "EUR" },
      { "typeCode": "RAP", "amount": "500" }
    ]
  },
  "note": "Invoice partially paid."
}

A single status can carry multiple amounts, for example the amount that was cashed together with the amount that is still outstanding. Each entry in amounts has the following fields:

Field	Required	Description
typeCode	no	The amount type code describing what the amount represents.
amount	yes	The amount. Positive = payment received, negative = reversal.
vatPercentage	no	The VAT percentage that applies to this amount. Is mandatory when typeCode is MEN.
currency	no	The currency of this amount. Defaults to EUR.

Commercial status example

{
  "status": "RE",
  "reasons": {
    "REF": "Purchase order number is invalid. The format should be POnnnnnn."
  },
  "actions": {
    "NIN": "Please send a new invoice."
  },
  "note": "Invoice rejected due to validation errors."
}

A successful call returns 200 OK with the documentId of the created response document:

{
  "id": "e12b19a3-30ed-4c26-b712-5112f6b24ceb"
}

If no sales invoice is known for the given {documentId}, a 404 Not Found is returned.