Odosielanie eFaktúr

XML payload, metadáta, idempotencia a význam odpovede 202 Accepted.

Endpoint slúži na technické prijatie dokumentu na odoslanie. Úspešná odpoveď HTTP 202 Accepted znamená, že Doklado dokument prijalo na ďalšie spracovanie. Neznamená úspešné doručenie príjemcovi, sémantickú validitu dokumentu ani právne účinky eFaktúry.

Stav odoslania sledujte cez SAPI+ webhooky. Dostupnosť ďalších spôsobov zisťovania stavu si potvrďte pri aktivácii.

Endpoint - Odoslanie dokumentu

Stav: Implementované, Nasadené: Sandbox

POST /v1/sapi/document/send
Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: <uuid>
X-Peppol-Participant-Id: <sender_participant_id>

Povinné HTTP hlavičky

Idempotency-Key

Idempotency-Key musí byť stabilný pre jeden logický pokus odoslania dokumentu.

Odporúčania:

použiť UUID v4,
pri retry rovnakého requestu použiť rovnaký Idempotency-Key,
pri odoslaní nového dokumentu použiť nový Idempotency-Key,
pri zmene payloadu alebo metadát nepoužiť starý Idempotency-Key.

Ak klient použije rovnaký Idempotency-Key s iným payloadom alebo inými metadátami, Doklado vráti informáciu o konflikte.

Request body

Príklad requestu:

{
  "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-05-11T12:00:00Z"
  },
  "payload": "<?xml version="1.0" encoding="UTF-8"?><Invoice>...</Invoice>",
  "payloadFormat": "XML",
  "payloadEncoding": "UTF-8",
  "checksum": "5f70bf18a086007016aaf1828a0972a2c1f8eec3e7c891944dfb2f7f3f4f1b55"
}

Pole	Povinné	Popis
`metadata`	áno	Objekt `DocumentMetadata`.
`payload`	áno	XML dokument ako string v JSON.
`payloadFormat`	áno	Pre SAPI-kompatibilnú vrstvu hodnota `XML`.
`payloadEncoding`	nie	Kódovanie payloadu, predvolene `UTF-8`.
`checksum`	nie	SHA-256 kontrolný súčet payloadu.

payload je XML dokument prenesený ako JSON string. Nie je base64, pokiaľ sa v ďalšej verzii špecifikácie výslovne nedoplní iný prenosový režim. Limit veľkosti sa vzťahuje na bytovú reprezentáciu XML po serializácii do UTF-8.

Objekt DocumentMetadata

Pole	Povinné	Popis
`documentId`	áno	Unikátny identifikátor dokumentu pridelený klientom, napr. `INV-2026-0001`.
`documentTypeId`	áno	Peppol Document Type Identifier.
`processId`	áno	Peppol Process Identifier.
`senderParticipantId`	áno	Peppol ID odosielateľa vo formáte `schemeId:identifier`.
`receiverParticipantId`	áno	Peppol ID príjemcu vo formáte `schemeId:identifier`.
`creationDateTime`	áno	Čas vytvorenia dokumentu v ISO 8601.

Príklady identifikátorov:

Document Type ID:
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

Process ID:
urn:fdc:peppol.eu:2017:poacc:billing:01:1.0

Schéma používaná pre slovenské DIČ:
0245

Výpočet checksumu

Ak klient posiela pole checksum, hodnota musí byť SHA-256 hash z presnej bytovej reprezentácie payload po serializácii do UTF-8. Výsledok sa posiela ako malé hexadecimálne znaky s dĺžkou 64 znakov.

checksum = sha256_hex(payload_bytes_utf8)

Úspešná odpoveď

HTTP 202 Accepted

{
  "providerDocumentId": "doc_01HX0000000000000000000000",
  "status": "ACCEPTED",
  "receivedAt": "2026-05-11T12:00:05Z",
  "timestamp": "2026-05-11T12:00:05Z"
}

Pole	Typ	Popis
`providerDocumentId`	string	Unikátny identifikátor dokumentu pridelený Doklado.
`status`	string	Pri úspešnom prijatí hodnota `ACCEPTED`.
`receivedAt`	datetime	Čas prijatia dokumentu Doklado.
`timestamp`	datetime	Čas generovania odpovede.

HTTP 202 Accepted potvrdzuje iba technické prijatie dokumentu na spracovanie. Ak je dokument odmietnutý už pri synchrónnej validácii requestu, Doklado vráti príslušný chybový HTTP status namiesto 202.

Chybové stavy odosielania

HTTP	Príčina a riešenie
`400`	Neplatný request, chýbajúce pole, neplatný formát metadát alebo nesúlad `X-Peppol-Participant-Id` s `metadata.senderParticipantId`.
`401`	Neplatný alebo expirovaný token. Klient musí obnoviť token alebo získať nový.
`403`	Klient nemá oprávnenie odosielať za uvedený `senderParticipantId`.
`409`	Rovnaký `Idempotency-Key` bol použitý s iným payloadom alebo metadátami.
`422`	Dokument bol syntakticky prijateľný ako request, ale neprešiel validačnými alebo Peppol pravidlami.
`429`	Prekročený rate limit. Klient má použiť retry s backoffom.
`500`	Interná chyba Doklado.
`503`	Dočasná nedostupnosť závislej služby alebo odosielacej infraštruktúry.

Príklad odoslania cez cURL

Použite premenné z prvého volania. Telo požiadavky z príkladu vyššie uložte do súboru request.json. Nahraďte metadáta vlastnými údajmi a do payload vložte skutočnú validnú Peppol eFaktúru ako JSON reťazec. Úvodzovky XML zapíšte ako \" a nové riadky ako . XML ukážka s ... iba ilustruje formát a nie je validnou faktúrou.

Voliteľné pole checksum vynechajte alebo vypočítajte pre skutočný XML payload; ukážkovú hodnotu nepreberajte. metadata.senderParticipantId musí zodpovedať SAPI_PARTICIPANT_ID.

Pre tento dokument si vygenerujte a uložte UUID do premennej SAPI_IDEMPOTENCY_KEY. Pri opakovaní rovnakej požiadavky zachovajte rovnaký kľúč aj obsah súboru.

SAPI_IDEMPOTENCY_KEY='UUID_PRE_TENTO_DOKUMENT'

curl --request POST --fail-with-body --silent --show-error \
  "$SAPI_BASE_URL/sapi/document/send" \
  --header "Authorization: Bearer $SAPI_ACCESS_TOKEN" \
  --header "X-Peppol-Participant-Id: $SAPI_PARTICIPANT_ID" \
  --header "Idempotency-Key: $SAPI_IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @request.json

Pred odoslaním overte účastníka a jeho capabilities. Uložte providerDocumentId z odpovede a sledujte ďalšie stavové udalosti cez webhooky. Samostatný endpoint na zisťovanie stavu odoslaného dokumentu aktuálna REST API referencia neobsahuje.

Was this page helpful?