SAPI-SK — odosielanie a príjem

Dokumentové endpointy vyžadujú access token (Authorization: Bearer …) a hlavičku X-Peppol-Participant-Id, ktorá určuje organizáciu. Odosiela sa UBL XML; prijaté dokumenty čítate cez cursor stránkovanie a označujete ako prevzaté.

Odoslanie dokumentu

Endpoint POST /document/send prijme jeden dokument (UBL XML) a zaradí ho na doručenie cez Peppol. Povinné hlavičky:

Hlavička	Popis
`Idempotency-Key`	Povinný. UUID identifikujúci pokus o odoslanie (viď idempotencia nižšie).
`X-Peppol-Participant-Id`	Povinný. Peppol ID odosielateľa — musí sa zhodovať s metadata.senderParticipantId.

Telo požiadavky:

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 je v SAPI v1.0 fixne "XML". payload je UTF-8 UBL XML, maximálne 10 MB. checksum je voliteľný — ak ho pošlete, musí byť SHA-256 nad presnými bajtmi payloadu (64 malých hex znakov); pri nezhode vráti API 400 (SAPI-VAL-003).

Odpoveď (202 — technicky prijaté):

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

202 ACCEPTED potvrdzuje iba technické prevzatie — nie sémantickú validáciu, doručenie cez Peppol ani právny účinok. Stav doručenia sledujte v eFaktúre alebo cez webhooky.

Idempotencia

Endpoint je idempotentný na dvoch úrovniach:

Situácia	Správanie
Rovnaký Idempotency-Key + rovnaké telo	Vráti pôvodnú uloženú 202 odpoveď (rovnaký providerDocumentId). Kľúče expirujú po 24 h.
Rovnaký obsah UBL, iný Idempotency-Key	Content-hash dedup: 202 ACCEPTED s pôvodným providerDocumentId (nič sa neodošle druhýkrát).
Rovnaký Idempotency-Key + INÉ telo	`409` `SAPI-PROC-001` (konflikt).
Číslo faktúry koliduje s natívne vystaveným dokladom	`400` `SAPI-VAL-005` — nič sa neodošle.
Nedostatok kreditu	`422` `SAPI-PROC-002`.

Zoznam prijatých dokumentov

GET /document/receive vráti cursor-stránkovaný zoznam prijatých dokumentov, zoradený od najstaršieho (aby polling klient nepreskočil dokument vložený medzi stránkami). Parametre: pageToken (kurzor z predchádzajúcej odpovede), limit (1–100, predvolene 20) a status (RECEIVED alebo 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..."
}

Ak je nextPageToken prítomný, posuňte ho ako ?pageToken= do ďalšieho volania. Chýba, keď už nie sú ďalšie záznamy. documentId je náš identifikátor dokumentu — použijete ho v detaile aj potvrdení.

Detail dokumentu

GET /document/receive/{documentId} vráti metadáta aj obsah. Payload je doručený nezmenený tak, ako prišiel cez Peppol sieť.

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"
}

Potvrdenie prevzatia (acknowledge)

POST /document/receive/{documentId}/acknowledge označí dokument ako ACKNOWLEDGED — potvrdzuje úspešné prevzatie vaším softvérom, aby ste ho v ďalšom pollingu vedeli vyfiltrovať (?status=RECEIVED vs. ?status=ACKNOWLEDGED). Operácia je idempotentná — opakované volanie vráti ten istý pôvodný čas.

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 nemení pracovný (workflow) stav faktúry v eFaktúre — je to výhradne technické potvrdenie „odovzdané softvéru". Zaúčtovanie či úhradu riešite samostatne v aplikácii.

Kredity a limity

Odoslanie sa účtuje presne ako každé iné odoslanie e-faktúry (bezplatná kvóta plánu → kredity; v roku 2026 platí promo zdarma). Príjem je zdarma. Volania podliehajú rate limitu podľa plánu (prípadne override na klientovi) — odpovede nesú hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset; pri prekročení vráti API 429 (SAPI-TMP-001) s Retry-After.