Stav odoslania a doručenky
Technický stav doručenia eFaktúry, výsledok TDD reportingu a stiahnutie MLS alebo AS4 doručeniek cez SAPI+.
Po odoslaní dokumentu uložte providerDocumentId z odpovede POST /v1/sapi/document/send. Tri operácie SAPI+ umožňujú čítať stav odoslania a dostupné doručenky. Sú rozšírením Doklado nad rámec štandardu SAPI-SK v1.0 a nemenia stav procesu.
| Metóda | Endpoint | Výsledok |
|---|---|---|
GET | /v1/sapi-plus/document/send/{providerDocumentId}/status | Stav doručenia a samostatný výsledok TDD reportingu |
GET | /v1/sapi-plus/document/send/{providerDocumentId}/receipts | Stránkovaný zoznam metadát doručeniek |
GET | /v1/sapi-plus/document/send/{providerDocumentId}/receipts/{receiptId} | Obsah jednej doručenky v JSON alebo priamy XML/SOAP súbor |
Definície nových operácií a dátových schém vychádzajú zo Swaggera Doklado SAPI PLUS.
Prístupy a identifikátory
Všetky tri operácie vyžadujú:
Authorization: Bearer <access_token>s oprávnenímdocument:send,X-Peppol-Participant-Idpôvodného odosielateľa dokumentu, za ktorého sa dokument odoslal,providerDocumentIdpridelený Doklado pri odoslaní.
providerDocumentId nie je číslo faktúry ani hodnota metadata.documentId pridelená klientom. Pri čítaní doručeniek používajte receiptId zo stavovej odpovede alebo zo zoznamu doručeniek; identifikátor patrí ku konkrétnemu dokumentu a organizačnému kontextu.
Príklady používajú premenné z prvého volania. SAPI_BASE_URL už obsahuje /v1. Nastavte identifikátor skutočne odoslaného dokumentu:
SAPI_PROVIDER_DOCUMENT_ID='PROVIDER_DOCUMENT_ID_Z_ODPOVEDE'
Stav odoslaného dokumentu
curl --fail-with-body --silent --show-error \
"$SAPI_BASE_URL/sapi-plus/document/send/$SAPI_PROVIDER_DOCUMENT_ID/status" \
--header "Authorization: Bearer $SAPI_ACCESS_TOKEN" \
--header "X-Peppol-Participant-Id: $SAPI_PARTICIPANT_ID" \
--header 'Accept: application/json'
HTTP 200 znamená úspešné načítanie stavu. Vracia sa aj pri odmietnutí dokumentu, zlyhaní odoslania alebo odmietnutí TDD reportingu. Výsledok dokumentu vyhodnocujte podľa tela odpovede; HTTP chyby 4xx/5xx opisujú problém aktuálneho volania GET.
Odpoveď rozlišuje dve vetvy:
delivery: technické doručenie pôvodného obchodného dokumentu,taxReporting: výsledok súvisiaceho slovenského TaxDataDocument (TDD) reportingu do C5.
Každá vetva má vlastný súhrnný status a podrobnosti transport (AS4) a mls (Peppol Message Level Status). Doručenie faktúry a výsledok TDD reportingu sa vyhodnocujú samostatne. Tieto stavy nepotvrdzujú obchodné schválenie, zaúčtovanie ani úhradu faktúry.
Čo znamenajú kódy MLS
MLS (Message Level Status) je stavová správa siete Peppol o výsledku spracovania a doručenia dokumentu. Hodnoty AP, AB a RE v poli mls.responseCode sú kódy z oficiálneho číselníka MLS:
| Kód MLS | Význam pri doručovaní dokumentu |
|---|---|
AP | Doručenie smerom k systému príjemcu (C4) bolo potvrdené. |
AB | Dokument bol odovzdaný smerom k systému príjemcu (C4), ale úspešné doručenie nie je potvrdené. |
RE | Dokument bol odmietnutý alebo doručenie smerom k systému príjemcu (C4) zlyhalo. |
Podrobnosti nájdete v oficiálnej špecifikácii Peppol MLS a v číselníku MLS Response Codes. Rovnaké kódy obsahuje aj pole responseCode v metadátach doručenky typu MLS.
Ilustračná úspešná odpoveď:
{
"providerDocumentId": "doc_a1b2c3d4e5f6g7h8",
"documentId": "INV-2026-0001",
"receivedAt": "2026-10-27T10:00:00Z",
"delivery": {
"status": "DELIVERED_CONFIRMED",
"transport": {
"status": "ACKNOWLEDGED",
"receiptId": "rcpt_c3_as4"
},
"mls": {
"status": "RECEIVED",
"responseCode": "AP",
"receiptId": "rcpt_c3_mls"
}
},
"taxReporting": {
"status": "ACCEPTED",
"reportId": "tdd_456",
"taxDataTypeCode": "S",
"transport": {
"status": "ACKNOWLEDGED",
"receiptId": "rcpt_c5_as4"
},
"mls": {
"status": "RECEIVED",
"responseCode": "AP",
"receiptId": "rcpt_c5_mls"
}
},
"updatedAt": "2026-10-27T10:00:10Z",
"timestamp": "2026-10-27T10:05:00Z"
}
Súhrnné stavy
delivery.status | taxReporting.status | Význam |
|---|---|---|
QUEUED | QUEUED | Čaká na spracovanie |
PROCESSING | PROCESSING | Prebieha príprava alebo odoslanie |
RETRYING | RETRYING | Doklado automaticky opakuje dočasne neúspešný pokus |
SENT | SENT | Existuje pozitívna AS4 doručenka, výsledok MLS ešte neprišiel |
DELIVERED_CONFIRMED | ACCEPTED | Korelovaný MLS s kódom AP |
DELIVERED_UNCONFIRMED | ACCEPTED_UNCONFIRMED | Korelovaný MLS s kódom AB |
REJECTED | REJECTED | MLS s kódom RE |
FAILED | FAILED | Spracovanie skončilo známou chybou bez automatického opakovania |
UNKNOWN | UNKNOWN | Výsledok nie je spoľahlivo známy, napríklad po nejednoznačnom timeoute |
NOT_APPLICABLE | NOT_REQUIRED | Daná vetva sa na dokument nevzťahuje |
taxReporting.status=ACCEPTED označuje technický výsledok konkrétnej TDD operácie. reportId identifikuje aktuálny report; taxDataTypeCode aktuálne používa S (Submit). Hodnoty R a D sú rezervované.
transport.status=ACKNOWLEDGED vychádza z overenej pozitívnej AS4 doručenky. Samotné HTTP 200 vzdialeného servera na tento stav nestačí.
mls.status má hodnoty PENDING, RECEIVED alebo NOT_APPLICABLE. Kód AB sa nepovažuje za AP. mls.receivedAt je čas prijatia MLS v Doklado, nie čas doručenia faktúry príjemcovi. Stav OVERDUE sa v tejto implementácii nepoužíva.
Ak je dostupná diagnostika failure, obsahuje kód SEND_FAILED alebo NEGATIVE_AS4_RECEIPT a popis chyby. Diagnostika nie je pokynom na opätovné odoslanie faktúry cez POST /document/send.
Zoznam doručeniek
curl --fail-with-body --silent --show-error --get \
"$SAPI_BASE_URL/sapi-plus/document/send/$SAPI_PROVIDER_DOCUMENT_ID/receipts" \
--header "Authorization: Bearer $SAPI_ACCESS_TOKEN" \
--header "X-Peppol-Participant-Id: $SAPI_PARTICIPANT_ID" \
--header 'Accept: application/json' \
--data-urlencode 'scope=DELIVERY' \
--data-urlencode 'type=MLS' \
--data-urlencode 'limit=20'
Všetky query parametre sú voliteľné:
| Parameter | Hodnoty a význam |
|---|---|
scope | DELIVERY alebo TAX_REPORTING; bez filtra obe vetvy. Ide o vetvu spracovania, nie OAuth scope. |
type | MLS alebo AS4_RECEIPT; bez filtra oba typy |
reportId | Doručenky konkrétneho TDD reportu; kombinácia so scope=DELIVERY vráti 400 |
pageToken | Nezmenený kurzor nextPageToken z predchádzajúcej odpovede |
limit | 1–100 položiek, predvolene 20 |
Zoznam obsahuje iba metadáta, bez XML obsahu. Napríklad:
{
"receipts": [
{
"receiptId": "rcpt_c3_mls",
"providerDocumentId": "doc_a1b2c3d4e5f6g7h8",
"scope": "DELIVERY",
"type": "MLS",
"receivedAt": "2026-10-27T10:00:10Z",
"responseCode": "AP"
}
]
}
Výsledky sú zoradené podľa receivedAt vzostupne a následne podľa receiptId. Ak odpoveď obsahuje nextPageToken, pokračujte s rovnakým dokumentom, organizačným kontextom a filtrami; token odovzdajte bez úprav. Ak ďalšia strana neexistuje, nextPageToken chýba.
HTTP 200 s receipts: [] znamená, že zatiaľ nie je dostupná doručenka alebo filtru nič nezodpovedá. receiptId sa zverejní až po uložení obsahu doručenky. Čakanie na doručenku sa neoznamuje chybou 409.
Zoznam zahŕňa aj odmietavé MLS s kódom RE. Pri AS4 sa sprístupňujú uložené pozitívne transportné doručenky; negatívne AS4 chybové odpovede zostávajú interné.
Detail a stiahnutie doručenky
Nastavte receiptId z predchádzajúcej odpovede:
SAPI_RECEIPT_ID='RECEIPT_ID_Z_ODPOVEDE'
curl --fail-with-body --silent --show-error \
"$SAPI_BASE_URL/sapi-plus/document/send/$SAPI_PROVIDER_DOCUMENT_ID/receipts/$SAPI_RECEIPT_ID" \
--header "Authorization: Bearer $SAPI_ACCESS_TOKEN" \
--header "X-Peppol-Participant-Id: $SAPI_PARTICIPANT_ID" \
--header 'Accept: application/json'
Predvolená JSON reprezentácia obsahuje metadata, payload a payloadFormat: "XML". payload je presný uložený obsah doručenky ako UTF-8 XML reťazec.
| Typ doručenky | Hlavička Accept | Obsah odpovede |
|---|---|---|
MLS alebo AS4_RECEIPT | application/json, bez Accept alebo */* | JSON s metadátami a payloadom |
MLS | application/xml | Pôvodné UBL MLS XML (ApplicationResponse) |
AS4_RECEIPT | application/soap+xml | Uložená SOAP obálka AS4 doručenky |
Pri priamom stiahnutí sa vracajú pôvodné uložené byty s Content-Disposition: attachment, bez preformátovania XML alebo normalizácie namespace. Nepodporovaná reprezentácia pre daný typ vráti 406. Chybové odpovede sú JSON.
Príklad priameho stiahnutia MLS do súboru:
curl --fail --silent --show-error \
"$SAPI_BASE_URL/sapi-plus/document/send/$SAPI_PROVIDER_DOCUMENT_ID/receipts/$SAPI_RECEIPT_ID" \
--header "Authorization: Bearer $SAPI_ACCESS_TOKEN" \
--header "X-Peppol-Participant-Id: $SAPI_PARTICIPANT_ID" \
--header 'Accept: application/xml, application/json;q=0.1' \
--output receipt.xml
Pre AS4 doručenku použite Accept: application/soap+xml, application/json;q=0.1 a zodpovedajúce receiptId.
Chyby a opakovanie čítania
| HTTP | Význam |
|---|---|
400 | Neplatný vstup, filter, kombinácia reportId a scope, limit alebo kurzor |
401 | Neplatný alebo expirovaný token |
403 | Chýbajúce oprávnenie k participantovi alebo dokumentu |
404 | Dokument alebo doručenka neexistuje v oprávnenom kontexte; doručenka iného dokumentu nie je dostupná cez túto cestu |
406 | Požadovaný formát sa pre typ doručenky nepodporuje; týka sa detailu doručenky |
429 | Prekročený limit volaní |
503 | Dočasná nedostupnosť, napríklad nedostupné úložisko doručenky |
Každý z troch endpointov má samostatný limit 100 volaní za minútu na participanta. Pri 429 rešpektujte Retry-After.
Chybové odpovede používajú objekt error s poľami category, code, message, retryable a correlation_id; voliteľne aj details. Opakovanie požiadavky riaďte podľa error.retryable a použite exponenciálny backoff. Nedostupnosť úložiska (503) nevyhodnocujte ako neexistenciu doručenky (404).
Pri zmene stavu môžete načítanie spustiť aj na základe webhooku. Čítanie stavu alebo doručeniek nemení stav dokumentu a nevyžaduje acknowledge používané pri prijímaní eFaktúr.