Skip to main content

Overview

Each document has a state that shows where it is in its life. The timeline endpoint gives the events behind that state: creation, each transmission, and each response from the receiver. 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 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. 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.
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.

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 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.