Skip to main content

Overview

Each document has a state that shows where it is in its life. Two endpoints give the events behind that state:
  • GET /api/documents/{document_id}/timeline gives all events: creation, each transmission, and each response from the receiver. See Get the timeline.
  • GET /api/documents/{document_id}/lifecycle gives only the status events after creation, each with a canonical status. See Get the lifecycle events.
Use this page to find out why a document is FAILED or to see if the buyer accepted an invoice.

Document states

A document has one of five states: DRAFT, TRANSIT, SENT, FAILED and RECEIVED. The state field of the document contains the value. An outbound document uses the first four states. An inbound document is TRANSIT while e-invoice.be processes it. Then it is RECEIVED, or FAILED when its processing failed.

Outbound flow

Inbound flow

See Webhooks for the payload of each event.

Retry behaviour

For a production company, the API makes a maximum of 3 attempts to deliver the document to the access point of the receiver, with 5 seconds between the attempts. If the last attempt fails, the document goes to FAILED. If the API cannot prepare the document for transmission, the document goes to FAILED with no attempt. Thus a document can be FAILED some seconds after the send request. The API does not try again later. To try again, send the document again: see Read a failed transmission.

State rules

  • Send. POST /api/documents/{document_id}/send is permitted only for a document in the state DRAFT or FAILED. For other states the API returns 405 Method Not Allowed.
  • Delete. DELETE /api/documents/{document_id} is permitted only for a document in the state DRAFT or FAILED. For other states the API returns 400 Bad Request with the detail Document is not in draft state.
  • Update. There is no endpoint that changes the content of a draft. Delete the draft and create a new document.
See List, filter and manage documents for the related procedures.

Get the timeline

The timeline endpoint returns all events of one document in chronological order.
string
required
The ID of the document.
The response for an invoice that a production company sent, and that the buyer accepted:
For a sandbox company, the timeline of an outbound document contains only the document_created event. The email delivery makes no transmission record, and Peppol responses are not delivered to sandbox companies. Read the state of the document to see the result of the send.

Response fields

string
required
The ID of the document.
array
required
The events, sorted by timestamp from oldest to newest.
The API returns 404 Not Found when the document does not exist in your company. With the command-line tool, peppol document timeline <document-id> shows the same events. See peppol CLI.

Timeline events

Read a failed transmission

Each send request that reaches the transmission step makes one transmission record, and thus one event in the timeline. The API sets the event type of these records as follows:
  • Each record before the newest one is send_failed.
  • The newest record is send_success when the document is SENT, send_attempted when the document is TRANSIT, and send_failed in all other cases.
A document that failed two times and was then delivered shows two send_failed events and one send_success event. The timeline does not show each automatic attempt. The maximum of 3 attempts in one send request (see Retry behaviour) gives one event. If the preparation of the document fails before the transmission step, the document goes to FAILED and the timeline gets no send event for that request.
1

Confirm the state

Call GET /api/documents/{document_id} and make sure that state is FAILED. You also get the document.sent.failed webhook event when the transmission fails.
2

Read the timeline

Find the send_failed events. Examine details.receiver_peppol_id to make sure that the document went to the correct participant.
3

Check the receiver

Use Look up Peppol participants to make sure that the receiver is registered on Peppol and can receive the document type.
4

Send again

Call POST /api/documents/{document_id}/send again. Give the Peppol IDs as query parameters if the routing was incorrect. The document goes back to TRANSIT and the timeline gets a new event.
The timeline does not contain the cause of a failed transmission. If the cause is not clear after these steps, contact support and give the document ID.

Peppol responses

After a successful transmission, the receiver can return two types of response. The API attaches each response to the original document and shows it in the timeline. Companies that you register through e-invoice.be are registered on Peppol as receivers of the two response types. No configuration is necessary.
Responses are optional in Peppol. Many receivers send no Message Level Response and no Invoice Response. A timeline without response events does not mean that the buyer rejected or ignored the invoice.

Response codes

details.response_code contains one of these codes (UNCL4343 subset for Peppol BIS Invoice Response 3.0).

Status reason codes

details.status_reason_code gives the reason for the status (OpenPeppol OPStatusReason code list). details.status_reason contains the free text of the sender, if there is one.

Get the lifecycle events

GET /api/documents/{document_id}/lifecycle returns the status events of a document after its creation. Each event has a canonical_status: one status vocabulary for all sources. The event also keeps the original code of the source in native_code. Use this endpoint when you need one status value and do not want to interpret each Peppol code.
string
required
The ID of the document.
cURL
The response for the invoice of the timeline example:
The API returns 404 Not Found with "detail": "Document not found" when the document does not exist in your company. A document without status events gives 200 OK with an empty events array.

Lifecycle event fields

string
required
The ID of the document.
array
required
The events, sorted by occurred_at from oldest to newest. Each event always contains all eight fields. A field without a value is null.
Differences from the timeline:
  • The lifecycle has no document_created event and no email events.
  • Each transmission attempt gives one local event. The timeline gives one event for each send request. Thus a send request with 3 attempts gives 3 local events.
  • A sandbox company has no lifecycle events. Its email delivery makes no transmission record, and it gets no Peppol responses.

Canonical status

These are the values of canonical_status: The API maps the Peppol codes as follows. A Peppol code that is not in this table gives canonical_status null. For example, the Invoice Response code IP (in process) and the Message Level Response code AB have no canonical value. The values deposited, emitted, disputed and paid have no Peppol code. They are only for the source fr:superpdp. At this time, the API writes no events with the source fr:superpdp, thus these values do not occur yet.
An Invoice Response with the code PD gives payment_sent, not paid. The buyer reports the payment. The response does not confirm that the payment arrived.

Limits

  • No webhook event for responses. There is no webhook event type for a Message Level Response or an Invoice Response. To follow the business status of an invoice, poll the timeline or the lifecycle events of the document.
  • No outbound Invoice Response. The API has no endpoint to send an Invoice Response for a document that you received.
  • No responses for sandbox companies. A sandbox company has no Peppol traffic, thus its documents get no mlr_received or imr_received events.
  • A response does not change the state. The state of a document stays SENT when a response arrives, also when the response code is RE.

Next Steps

Webhooks

Receive an event when a document is sent, received or failed.

Errors and troubleshooting

Find the cause of an API error and correct it.

Receive documents

Read and process the documents in your inbox.

List, filter and manage documents

Use the lists, the filters and the draft operations.