Prijímanie eFaktúr

Táto sekcia popisuje SAPI-kompatibilný spôsob, akým klientsky systém získava eFaktúry prijaté cez Doklado SAPI+ API. Prijímanie dokumentov je navrhnuté ako polling workflow: klient najprv získa zoznam dostupných dokumentov, následne si stiahne detail vybraného dokumentu a po úspešnom spracovaní potvrdí prevzatie cez acknowledge.

Výpis dokumentov neznamená ich spracovanie ani akceptáciu v klientskom systéme. Za spracovaný sa dokument považuje až po úspešnom volaní acknowledge.

Pri spracovaní sa riaďte kurzorom nextPageToken; poradie dokumentov nepoužívajte ako náhradu kurzora.

Základné pravidlá:

• klient číta dokumenty v organizačnom kontexte hlavičky X-Peppol-Participant-Id,
• endpoint zoznamu vráti len metadáta a stránkovanie,
• XML obsah dokumentu sa sťahuje samostatne cez detail endpoint,
• acknowledge sa volá až po úspešnom uložení alebo spracovaní dokumentu v klientskom systéme,
• polling zostáva povinný fallback aj pri použití webhookov.

Endpoint - Zoznam prijatých dokumentov

Stav: Implementované, Nasadené: Sandbox

GET /v1/sapi/document/receive
Authorization: Bearer <access_token>
X-Peppol-Participant-Id: <participant_id>

Endpoint vráti stránkovaný zoznam prijatých dokumentov dostupných pre daný participant_id.

Query parametre:

Úspešná odpoveď: HTTP 200

{
  "documents": [
    {
      "documentId": "doc_01HX0000000000000000000000",
      "clientDocumentId": "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",
      "receivedAt": "2026-05-11T12:00:05Z",
      "status": "RECEIVED",
      "payloadFormat": "XML"
    }
  ],
  "nextPageToken": "eyJjdXJzb3IiOiJuZXh0In0"
}

Response body:

Definícia objektu DocumentMetadata je spoločná pre odosielanie aj prijímanie dokumentov.

Stránkovanie:

• klient spracuje všetky položky z aktuálnej odpovede,
• ak odpoveď obsahuje nextPageToken, použije ho ako pageToken v ďalšom volaní,
• ak nextPageToken nie je prítomný, aktuálny polling cyklus je ukončený.

Endpoint - Detail prijatého dokumentu

Stav: Implementované, Nasadené: Sandbox

GET /v1/sapi/document/receive/{documentId}
Authorization: Bearer <access_token>
X-Peppol-Participant-Id: <participant_id>

Endpoint vráti metadáta a XML obsah jedného prijatého dokumentu.

Path parametre:

Úspešná odpoveď: HTTP 200

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

Response body:

Stiahnutie detailu samo o sebe nemení stav dokumentu na ACKNOWLEDGED. Klient môže detail stiahnuť opakovane, kým dokument nepotvrdí cez acknowledge.

Endpoint - Potvrdenie prijatia

Stav: Implementované, Nasadené: Sandbox

POST /v1/sapi/document/receive/{documentId}/acknowledge
Authorization: Bearer <access_token>
X-Peppol-Participant-Id: <participant_id>

Operácia acknowledge potvrdí, že klientsky systém dokument úspešne prevzal a spracoval do vlastného úložiska alebo workflow. Po úspešnom potvrdení sa dokument nastaví do stavu ACKNOWLEDGED.

Operácia je idempotentná. Opakované volanie acknowledge pre už potvrdený dokument vráti úspešnú odpoveď so stavom ACKNOWLEDGED.

Path parametre:

Úspešná odpoveď: HTTP 200

{
  "documentId": "doc_01HX0000000000000000000000",
  "status": "ACKNOWLEDGED",
  "acknowledgedDateTime": "2026-05-11T12:05:30Z"
}

Response body:

Klient nemá volať acknowledge, ak sa dokument nepodarilo uložiť, validovať alebo odovzdať do interného spracovania. V takom prípade dokument zostáva dostupný v stave RECEIVED a klient ho môže spracovať v ďalšom polling cykle.

Stavy prijatého dokumentu

Odporúčaný workflow prijímania

Odporúčané správanie klienta:

1. Zavolať GET /v1/sapi/document/receive?status=RECEIVED.
2. Pre každý dokument zo zoznamu zavolať GET /v1/sapi/document/receive/{documentId}.
3. Uložiť alebo spracovať XML payload vo vlastnom systéme.
4. Zavolať POST /v1/sapi/document/receive/{documentId}/acknowledge až po úspešnom spracovaní.
5. Pokračovať ďalšou stranou cez nextPageToken, kým ďalšia strana neexistuje.

Chybové stavy prijímania

Opakované spracovanie

Dokument identifikujte podľa documentId prideleného Doklado a rozpoznávajte už uložené dokumenty. Ak uloženie uspeje, ale potvrdenie zlyhá, pri ďalšom príjme nevytvárajte duplicitu a zopakujte potvrdenie. Pri zmene organizačného kontextu nepoužívajte kurzor inej firmy.

Funkčný popis uvádza rozdielne pravidlá zoradenia výsledkov. Integráciu preto nestavajte na konkrétnom poradí a pre ďalšiu stranu vždy používajte token vrátený serverom.