SAPI-SK: sending and receiving

Document endpoints require an access token (Authorization: Bearer …) and the X-Peppol-Participant-Id header, which specifies the organization. You send UBL XML; you read received documents via cursor pagination and mark them as received.

Sending a document

The POST /document/send endpoint accepts a single document (UBL XML) and queues it for delivery over Peppol. Required headers:

Header	Description
`Idempotency-Key`	Required. A UUID identifying the send attempt (see idempotency below).
`X-Peppol-Participant-Id`	Required. The sender's Peppol ID: must match metadata.senderParticipantId.

Request body:

POST https://api.efaktura.sk/sapi/document/send
Authorization: Bearer <access_token>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
X-Peppol-Participant-Id: 0245:1234567890
Content-Type: application/json

{
  "metadata": {
    "documentId": "INV-2026-0001",
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "senderParticipantId": "0245:1234567890",
    "receiverParticipantId": "0245:9876543210",
    "creationDateTime": "2026-07-04T10:30:00Z"
  },
  "payload": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">…</Invoice>",
  "payloadFormat": "XML",
  "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

payloadFormat is fixed to "XML" in SAPI v1.0. payload is UTF-8 UBL XML, up to 10 MB. checksum is optional: if you send it, it must be a SHA-256 of the exact payload bytes (64 lowercase hex characters); on mismatch the API returns 400 (SAPI-VAL-003).

Response (202, technically accepted):

{
  "providerDocumentId": "b1f2c3d4-5678-49ab-cdef-0123456789ab",
  "status": "ACCEPTED",
  "receivedAt": "2026-07-04T10:30:01.123Z",
  "timestamp": "2026-07-04T10:30:01.123Z"
}

202 ACCEPTED only confirms technical receipt, not semantic validation, delivery over Peppol, or legal effect. Track delivery status in eFaktúra or via webhooks.

Idempotency

The endpoint is idempotent on two levels:

Situation	Behavior
Same Idempotency-Key + same body	Returns the original stored 202 response (same providerDocumentId). Keys expire after 24 h.
Same UBL content, different Idempotency-Key	Content-hash dedup: 202 ACCEPTED with the original providerDocumentId (nothing is sent twice).
Same Idempotency-Key + DIFFERENT body	`409` `SAPI-PROC-001` (conflict).
Invoice number collides with a natively issued document	`400` `SAPI-VAL-005`: nothing is sent.
Insufficient credit	`422` `SAPI-PROC-002`.

Listing received documents

GET /document/receive returns a cursor-paginated list of received documents, sorted from oldest first (so a polling client doesn't skip a document inserted between pages). Parameters: pageToken (cursor from the previous response), limit (1–100, default 20), and status (RECEIVED or ACKNOWLEDGED).

GET https://api.efaktura.sk/sapi/document/receive?status=RECEIVED&limit=20
Authorization: Bearer <access_token>
X-Peppol-Participant-Id: 0245:1234567890

// 200
{
  "documents": [
    {
      "documentId": "b1f2c3d4-5678-49ab-cdef-0123456789ab",
      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "senderParticipantId": "0245:9876543210",
      "receiverParticipantId": "0245:1234567890",
      "creationDateTime": "2026-07-03T00:00:00.000Z"
    }
  ],
  "nextPageToken": "MjAyNi0wNy0wM1QxMDowMDowMC4wMDAwMDBafGIxZjJjM2Q0..."
}

If nextPageToken is present, pass it as ?pageToken= on the next call. It's absent when there are no more records. documentId is our document identifier: use it in the detail and acknowledge calls.

Document detail

GET /document/receive/{documentId} returns both metadata and content. The payload is delivered unchanged, exactly as it arrived over the Peppol network.

GET https://api.efaktura.sk/sapi/document/receive/b1f2c3d4-5678-49ab-cdef-0123456789ab
Authorization: Bearer <access_token>
X-Peppol-Participant-Id: 0245:1234567890

// 200
{
  "metadata": { "documentId": "b1f2c3d4-…", "documentTypeId": "…", "processId": "…", "senderParticipantId": "0245:9876543210", "receiverParticipantId": "0245:1234567890", "creationDateTime": "2026-07-03T00:00:00.000Z" },
  "payload": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice …>…</Invoice>",
  "payloadFormat": "XML"
}

Acknowledging receipt

POST /document/receive/{documentId}/acknowledge marks the document as ACKNOWLEDGED: confirming successful receipt by your software, so you can filter it out on the next poll (?status=RECEIVED vs. ?status=ACKNOWLEDGED). The operation is idempotent: repeated calls return the same original timestamp.

POST https://api.efaktura.sk/sapi/document/receive/b1f2c3d4-5678-49ab-cdef-0123456789ab/acknowledge
Authorization: Bearer <access_token>
X-Peppol-Participant-Id: 0245:1234567890

// 200
{
  "documentId": "b1f2c3d4-5678-49ab-cdef-0123456789ab",
  "status": "ACKNOWLEDGED",
  "acknowledgedDateTime": "2026-07-04T10:35:00.000Z"
}

Acknowledge does not change the invoice's workflow status in eFaktúra: it is purely a technical confirmation of "handed off to software". Posting or payment is handled separately in the app.

Credits and limits

Sending is billed exactly like any other e-invoice send (portal plans: free quota → credits; API/WL partners: volume price list per transaction; a free partner promo applies until Nov 30, 2026). Receiving is free in the eFaktúra app; in partner API/WL metering a received document counts as 0.5 tx. Calls are subject to the plan's rate limit (or a per-client override): responses carry the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; if exceeded the API returns 429 (SAPI-TMP-001) with Retry-After.