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 isFAILED 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 toFAILED. To try again, send the document again: see Read a failed transmission.
State rules
- Send.
POST /api/documents/{document_id}/sendis permitted only for a document in the stateDRAFTorFAILED. For other states the API returns405 Method Not Allowed. - Delete.
DELETE /api/documents/{document_id}is permitted only for a document in the stateDRAFTorFAILED. For other states the API returns400 Bad Requestwith the detailDocument 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.
Get the timeline
The timeline endpoint returns all events of one document in chronological order.string
required
The ID of the document.
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.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_successwhen the document isSENT,send_attemptedwhen the document isTRANSIT, andsend_failedin all other cases.
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.
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_receivedorimr_receivedevents. - A response does not change the state. The
stateof a document staysSENTwhen a response arrives, also when the response code isRE.
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.