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}/timelinegives all events: creation, each transmission, and each response from the receiver. See Get the timeline.GET /api/documents/{document_id}/lifecyclegives only the status events after creation, each with a canonical status. See Get the lifecycle events.
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 toFAILED. 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}/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.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
The API returns404 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.
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.
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.
cURL
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
The events, sorted by
occurred_at from oldest to newest. Each event always contains all eight fields. A field without a value is null.- The lifecycle has no
document_createdevent and no email events. - Each transmission attempt gives one
localevent. The timeline gives one event for each send request. Thus a send request with 3 attempts gives 3localevents. - 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 ofcanonical_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_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.