Track a document

Stage 4 of 6. After Wafeq ASP accepts a document, follow what happens to it. Then show the status of each document to your users.

This page uses these terms:

Document: an invoice or a credit note that your app submitted, and that Wafeq ASP accepted.
Document ID: the ID that Wafeq ASP gives a document when it accepts it (document_id, for example inv_0123456789ABCDEFGHIJ).
Report: the copy of the document that Wafeq ASP sends to the FTA. The FTA calls it the tax data document (TDD). For this reason, the field for its status is tdd_status.
Delivery: the transfer of the document to the e-invoicing provider of the buyer, on Peppol.
Webhook event: a message that Wafeq ASP sends to the webhook endpoint of your organization when something changes.

After Wafeq ASP accepts a document, two processes run. Each process has its own status:

The report to the FTA. Wafeq ASP reports each accepted document to the FTA.
The delivery to the buyer. Wafeq ASP delivers a document only when the buyer is on Peppol.

One process can succeed when the other fails. Thus your app must track both.

Before you start

Your organization has a webhook endpoint with the document.sent, document.status and document.reported events. Refer to Set up your organization.
Your app stored the document_id of each accepted document. Refer to Submit a document.

Track a document: the four steps

Step	Action
1	Receive each webhook event, and check it.
2	Find the document that the event is about.
3	Update the status of the document in your app.
4	Ask the API for documents that stay pending.

Step 1: Receive each webhook event and check it

Check the signature of the event with the signing secret of your webhook endpoint. Refer to Webhooks.
Read the webhook-id header. Wafeq ASP can send the same event more than one time. If your app already processed this webhook-id, ignore the event.
Store the event. Then answer with a 2xx status.

Step 2: Find the document that the event is about

Use data.document_id to find the document. Some document.status events do not contain data.document_id. For these events, use data.source_id. This is the value that your app sent in source_id.

Events can arrive in a different order than the changes. Use created_at to put the events of a document in the correct order.

Step 3: Update the status of the document in your app

The report to the FTA. The document.reported event gives the answer of the FTA in data.tax_authority_status. The API gives the same status in tdd_status:

`tdd_status`	`tax_authority_status`	Meaning
`reporting`	—	Wafeq ASP reported the document. The FTA did not answer yet.
`reported`	`REPORTED`	The FTA accepted the report.
`rejected`	`NOT_COMPLIANT`	The FTA rejected the report.
`withdrawn`	`WITHDRAWN`	Wafeq ASP withdrew the report, because the provider of the buyer rejected the document. Refer to Correct or cancel a document.
`unresolved`	—	The report has a problem that Wafeq ASP did not solve automatically.
`not_reported`	—	Wafeq ASP did not report the document. In Sandbox, this is always the status.

The delivery to the buyer. The document.sent and document.status events give the status in data.delivery_status. The API gives the same status in delivery_status:

`delivery_status`	Meaning
`queued`, `sending`, `retrying`	The queued delivery is in progress.
`sent`	Wafeq ASP sent the document to the provider of the buyer.
`received_by_ap`	The provider of the buyer received the document.
`forwarded`	The provider of the buyer acknowledged the document.
`delivered_confirmed`	The provider of the buyer accepted the document.
`rejected`	The provider of the buyer rejected the document. The reason is in `delivery_reason_code` on the document, and in `data.reason_code` in the event.
`failed`, `attention_required`	The delivery did not succeed.
`not_applicable`	Wafeq ASP reported the document to the FTA only. There is no delivery.

When the provider of the buyer rejects a document, the reason has one of these values:

BV: the document breaks a business rule.
SV: the format of the document is not correct.
FD: the provider could not deliver the document.

Step 4: Ask the API for documents that stay pending

Webhook events can be late. If a document stays pending for a long time, ask the API for its current status:

GET /invoices/{document_id} gives tdd_status, delivery_status and the history of the delivery.
GET /deliveries/{delivery_job_id} gives the progress of a queued delivery. The Location header of the 202 response points to this URL.

After a problem

These items are not steps. They tell you what each problem means and who acts.

The provider of the buyer rejected the document with BV or SV. Wafeq ASP withdraws the report. Your app must submit a corrected document. Refer to Correct or cancel a document.
The delivery failed, with a document_id. Wafeq ASP accepted the document and reports it to the FTA. Do not submit the document again.

Tracking in Sandbox

Wafeq ASP simulates the delivery. The document.status events of a simulated delivery contain simulated: true.
Wafeq ASP does not report documents to the FTA. tdd_status stays not_reported, and no real document.reported event comes.
To test how your app processes a document.reported event, send a test event from Developer → Webhooks in the Wafeq ASP portal. A test event contains test: true and changes no document.

Stage 5: Correct or cancel a document.