Práca s eFaktúramiStav odoslania a doručenky

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ódaEndpointVýsledok
GET/v1/sapi-plus/document/send/{providerDocumentId}/statusStav doručenia a samostatný výsledok TDD reportingu
GET/v1/sapi-plus/document/send/{providerDocumentId}/receiptsStrá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ím document:send,
  • X-Peppol-Participant-Id pôvodného odosielateľa dokumentu, za ktorého sa dokument odoslal,
  • providerDocumentId pridelený 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 MLSVýznam pri doručovaní dokumentu
APDoručenie smerom k systému príjemcu (C4) bolo potvrdené.
ABDokument bol odovzdaný smerom k systému príjemcu (C4), ale úspešné doručenie nie je potvrdené.
REDokument 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.statustaxReporting.statusVýznam
QUEUEDQUEUEDČaká na spracovanie
PROCESSINGPROCESSINGPrebieha príprava alebo odoslanie
RETRYINGRETRYINGDoklado automaticky opakuje dočasne neúspešný pokus
SENTSENTExistuje pozitívna AS4 doručenka, výsledok MLS ešte neprišiel
DELIVERED_CONFIRMEDACCEPTEDKorelovaný MLS s kódom AP
DELIVERED_UNCONFIRMEDACCEPTED_UNCONFIRMEDKorelovaný MLS s kódom AB
REJECTEDREJECTEDMLS s kódom RE
FAILEDFAILEDSpracovanie skončilo známou chybou bez automatického opakovania
UNKNOWNUNKNOWNVýsledok nie je spoľahlivo známy, napríklad po nejednoznačnom timeoute
NOT_APPLICABLENOT_REQUIREDDaná 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é:

ParameterHodnoty a význam
scopeDELIVERY alebo TAX_REPORTING; bez filtra obe vetvy. Ide o vetvu spracovania, nie OAuth scope.
typeMLS alebo AS4_RECEIPT; bez filtra oba typy
reportIdDoručenky konkrétneho TDD reportu; kombinácia so scope=DELIVERY vráti 400
pageTokenNezmenený kurzor nextPageToken z predchádzajúcej odpovede
limit1–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čenkyHlavička AcceptObsah odpovede
MLS alebo AS4_RECEIPTapplication/json, bez Accept alebo */*JSON s metadátami a payloadom
MLSapplication/xmlPôvodné UBL MLS XML (ApplicationResponse)
AS4_RECEIPTapplication/soap+xmlUlož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

HTTPVýznam
400Neplatný vstup, filter, kombinácia reportId a scope, limit alebo kurzor
401Neplatný alebo expirovaný token
403Chýbajúce oprávnenie k participantovi alebo dokumentu
404Dokument alebo doručenka neexistuje v oprávnenom kontexte; doručenka iného dokumentu nie je dostupná cez túto cestu
406Požadovaný formát sa pre typ doručenky nepodporuje; týka sa detailu doručenky
429Prekročený limit volaní
503Doč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.