Tutorial: Send Invoices

This page describes the steps necessary for sending invoices via Peppol using the SalesInvoice endpoint.

Prerequisite

• You have registered a hook with the topic InvoiceSent or *Sent. If not, go to hooks.
• The buyer supports Invoices as receiver capability.

Step 1: Preflight

Get the advised receiver partyId using the the SalesInvoice/queryRecipientParty.

In this example, let's use '0106:12345678', '0190:0000000412345678000' and '9944:NL123456789B01' as identifiers of the receiver, and your own partyId as the sender. If you don't know your own partyId, use the GET api/v1/me/party. For the sake of this example, we will use '0106:12345678' as sender. When calling the API with these values, we will check the delivery options for every partyId and return the best one to use.

In return we get our endpointId:

{
  "channel": "peppol",
  "description": "default send via peppol delivery",
  "id": "NL:KVK:12345678"
}

It is possible that none of the identifers can be used to delivery an invoice. In that case you will receive an error:

{
  "helpLink": "https://psb.econnect.eu/endpoints/v1/SalesInvoice.html#query-recipient-party",
  "message": "PartyId 'NL:OINO:0000000412345678000' not found in Peppol.",
  "code": "API404",
  "requestId": "41cd5529904be94d941137068c1c3fa1",
  "dateTime": "2024-04-13T15:46:29.4878393+00:00"
}

Read more about the queryRecipientParty

Step 2: Send the invoice

Now we need to send the document to the receiver's endpointId. Reference on how the document should be structured can be found here. Use the SalesInvoice/Send call to send the document. Please take note of the returned reference Id, since we are going to use that later on.

result:

{
  "id": "5618b40a-822d-4e74-8894-b489617dbaa4"
}

Step 3: Receive hooks

Using Webhooks

Make sure you are subscribed to the relevant webhook. In this example, we are going to use a mailhook.

Example hook body:

{
  "id": "1",
  "name": "mail hook",
  "action": "mailto:example@econnect.eu",
  "topics": [
    "InvoiceReceived",
    "InvoiceReceivedError",
    "InvoiceSent",
    "InvoiceSentError",
    "InvoiceSentRetry",
    "HookSent",
    "HookSentError",
    "HookSentRetry"
  ],
  "isActive": true,
  "createdOn": "0001-01-01T00:00:00+00:00",
  "changedOn": null
}

When sending the document has succeeded, you will receive an email/webhook that looks something like the InvoiceSent message below. You can verify that the document has been successfully send by comparing the documentId with the reference Id we saw earlier. It is also possible the invoice went into retry for various reasons or it was not possible to sent the invoice, then you will receive an email/webhook with the topic InvoiceSentRetry or InvoiceSentError.

More information about Retry or Error

When an AccessPoint is not reachable, we will retry the document for a maximum of 8 times, for every retry you will receive an InvoiceSentRetry webhook. After the fifth time, the InvoiceSentError will be sent and the document has reached the end status.

The retries are spread out over multiple hours, so it is possible the last status will be sent around 35 hours after the invoice has been posted for send.

There are multiple causes for an InvoiceSentErrors and the most common ones are:

• "Invalid payload. [BR-CL-10]-Any identifier identification scheme identifier MUST be coded using one of the ISO 6523 ICD list."
• "No valid delivery options. PartyId 'NL:KVK:xxxxxx' not found in Peppol."
• Send 'Invoice' failed. Attempt: 8 of 8. [SEND04] AS4 receiver access point did not return HTTP status code 2xx or 5xx.

The first error means there is a validation error on the document that is being sent. When an invalid document is being send, you will get an API400 on the Send API. Most of the errors can be found on Peppol BIS Billing 3.0 (opens new window).

The second error is when a Send is done before querying the recipient, it is possible you will receive an error because the receiver cannot be found in Peppol and therefore the document cannot be send.

The third error will be posted when the invoice cannot be delivered after the last InvoiceSentRetry.

For more information regarding webhooks, please look at the hooks page.

Using API calls

Call SalesInvoice/status in order to see if the document has been sent successfully. This is not the preferred method, please use the webhooks method as much as possible.

Example response:

[
  {
    "id": "46f68e6f-b05f-4531-8ec7-fc23a23f5cee",
    "name": "Initializing",
    "description": "Request received.",
    "createdOn": "2020-06-15T09:18:50.9699485+00:00"
  },
  {
    "id": "5e98e800-6d80-4640-a857-bb5715a8cfcc",
    "name": "DeterminingRoute",
    "description": "Successfully determined destination for party '0106:12345678' and document 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.simplerinvoicing.org:si:si-ubl:ver1.2::2.1'.",
    "createdOn": "2020-06-15T09:18:51.2563944+00:00"
  },
  {
    "id": "d04a4648-3995-4bbc-bed6-ead3a98a5870",
    "name": "Executing",
    "description": "'Invoice' successfully sent: '0d0167cb-72f1-4656-801b-17ff3a6ddb59@econnect.eu'.",
    "createdOn": "2020-06-15T09:18:51.7877889+00:00"
  },
  {
    "id": "b21f56c4-8ba8-4479-8b02-49eb6e6ae451",
    "name": "Finished",
    "description": "Process finished.",
    "createdOn": "2020-06-15T09:18:51.7914789+00:00"
  }
]