SAPI-SK for developers

What SAPI-SK is

SAPI-SK is the national REST interface between a client system (ERP, e-shop, accounting software) and an Access Point. The aim is a uniform, vendor-independent way to send and receive documents through a “digital postman”, instead of each provider’s proprietary API. Treat support for SAPI-SK as insurance against vendor lock-in.

Authentication

OAuth2 client_credentials is used. You create an API token in the portal: its UUID serves as the client_id and the vpt_… value as the client_secret. Via POST /sapi/auth/token you obtain a short-lived access token and a refresh token; you then send the access token in the Authorization: Bearer … header. Revoking the API token in the portal immediately invalidates the issued tokens as well.

Sending and receiving

• Sending: POST /sapi/document/send with the header X-Peppol-Participant-Id (the participant ON WHOSE BEHALF you send: your company or a client under your token; the recipient is given in the document metadata) and Idempotency-Key (safe retries without duplicates). In bulk via POST /sapi/document/batch (up to 100 documents per call).
• Delivery status: GET /sapi/document/sent returns the statuses of sent documents (pending → delivered / rejected from the MLS delivery receipt, or undeliverable when the recipient has no address in the Peppol network), with ?since= for incremental download.
• Receiving: GET /sapi/document/receive (pagination, filter by status) and confirmation of processing via acknowledge.
• Evidence and FS reports (from 1.8.14): every document carries an fsReport object (reported / pending / not_required with a reason, the report id and the C5 verdict), sent documents also statusReason and xmlSha256; the status of up to 200 documents at once via POST /sapi/document/sent/status, the timeline via GET /sapi/document/sent/{id}/events. Webhooks carry fsReport and the new events invoice.report_pending and invoice.report_rejected.
• Token status / renewal / revocation: separate endpoints under /sapi/auth/*.

Sandbox and idempotency

You can try out the contract in the sandbox without the risk of real delivery: the sandbox validates requests and returns mock responses. When sending, always use an Idempotency-Key: when the same request is repeated (e.g. after a timeout) no duplicate document is created. Derive the key from something stable for the invoice (e.g. the ID or the invoice number in your system); a new key for the same invoice bypasses this protection. If our pre-send check rejected the document (e.g. a validation error), nothing went into the network and nothing is reported to the Financial Administration: correct it and send it again with the same key, with the date of issue according to the day it really goes out. A delivered invoice is not sent again; it is corrected with a credit note or a debit note. You prevent errors with POST /sapi/document/validate (checks the document without sending) and GET /sapi/discovery (is the recipient in the Peppol network).

Where to find the details

The complete list of endpoints, request/response examples and error codes are in our technical documentation (SAPI-SK section), including the machine-readable OpenAPI 3.1 specification. We recommend starting in the sandbox and only then moving to production.