Prijímanie a stavy

Ako sledovať stav odoslaných faktúr (GET /peppol/status), čítať príchodzie doklady prijaté cez Peppol (GET /peppol/received) a ako sa to viaže na webhook peppol.document.received. Obe čítacie operácie vyžadujú scope invoice:read a hlavičku X-Organization-Id.

Stav odoslanej faktúry

Vráti posledný (najnovší) prenos pre danú faktúru. Ak pre faktúru ešte neexistuje žiadny prenos, vráti syntetický stav not_sent bez ďalších polí.

GET /v1/agent/peppol/status/b1f0d7a2-…
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…

{
  "data": {
    "invoice_id": "b1f0d7a2-…",
    "state": "SENT",
    "error_message": null,
    "receiver_identifier": "9915:2010101010",
    "document_id": "…",
    "updated_at": "2026-06-22T10:00:05.000Z"
  }
}

Stavový automat

Kým GET /peppol/status dá jeden súhrnný stav, podrobný rozpad doručenia po vrstvách (transport AS4 / MLS / business response) a celú históriu prenosov pre audit a archiváciu získate cez Dôkaz o doručení (GET /v1/agent/peppol/sent/{invoiceId}/evidence).

Príchodzie doklady

Query parametre:

Záznamy sú zoradené od najnovšieho.

GET /v1/agent/peppol/received?limit=20&offset=0
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…

{
  "data": [
    {
      "id": "f3a1…",
      "sender_participant_id": "9915:9999999999",
      "sender_name": "Dodávateľ a.s.",
      "sender_ico": "11112222",
      "document_type": "invoice",
      "document_number": "VF2026123",
      "total": "240.00",
      "vat_total": "40.00",
      "currency": "EUR",
      "status": "new",
      "issue_date": "2026-06-20",
      "received_at": "2026-06-20T08:15:00.000Z",
      "acknowledged_at": null,
      "sbdh_instance_id": "8f2c1c0e-…",
      "attachments_count": 1,
      "is_test": false
    }
  ]
}

Stiahnutie prijatého dokladu (PDF / XML)

Jednotlivý prijatý doklad viete stiahnuť ako PDF (vygenerované z dát dokladu, vrátane pay‑by‑square QR pri IBAN) alebo ako pôvodné UBL XML. Obe operácie sú scope invoice:read a vracajú súbor ako prílohu (Content-Disposition: attachment). id je hodnota z GET /peppol/received.

Ak pre doklad nie je dostupné pôvodné XML, endpoint /xml vráti 404. Neexistujúce id (alebo doklad inej organizácie) vráti tiež 404.

GET /v1/agent/peppol/received/f3a1…/pdf
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="prijata-faktura-VF2026123.pdf"

%PDF-1.7 …

Detail, prílohy a potvrdenie prevzatia

Detail vráti metadáta dokladu vrátane identifikátorov z SBDH (receiver_participant_id, document_type_id, process_id, sbdh_instance_id), SHA-256 archivovaného UBL (ubl_sha256), zoznam príloh a odkazy links na XML, PDF, prílohy a dôkaz o prijatí. Prílohy sú tie, ktoré odosielateľ vložil do UBL (PDF, XLSX, DOCX, XML…); /attachments vráti zoznam, /attachments/{attachmentId} obsah s pôvodným Content-Type.

POST /v1/agent/peppol/received/f3a1…/acknowledge
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…

{
  "data": {
    "id": "f3a1…",
    "acknowledged_at": "2026-06-20T08:20:11.000Z",
    "already_acknowledged": false
  }
}

Dôkaz o prijatí

Nemenné identifikátory príchodzieho prenosu, čas prijatia, integrita UBL a Message Level Status (MLS), ktorý sme odoslali späť odosielateľovi ako potvrdenie prijatia na spracovanie. mls.state je sent (s AS4 message_id, ak MLS odoslalo toto API), sent_by_access_point (MLS odpovedá priamo Access Point – predvolený produkčný režim, message id nie je k dispozícii), pending kým MLS na strane API ešte nebol odoslaný, alebo not_applicable pre doklady mimo siete Peppol. Protipól pre odoslané doklady je Dôkaz o doručení.

{
  "data": {
    "document_id": "f3a1…",
    "transport": "peppol",
    "mode": "live",
    "sender_participant_id": "iso6523-actorid-upis::0245:2020202020",
    "receiver_participant_id": "iso6523-actorid-upis::0245:3030303030",
    "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",
    "sbdh_instance_id": "8f2c1c0e-…",
    "document_number": "VF2026123",
    "received_at": "2026-06-20T08:15:00.000Z",
    "ubl_sha256": "3b7c…",
    "ubl_bytes": 18422,
    "mls": { "state": "sent", "message_id": "…@phase4.phoss-ap", "sent_at": "2026-06-20T08:15:03.000Z" },
    "acknowledged_at": "2026-06-20T08:20:11.000Z"
  }
}

Auditná stopa (export udalostí)

Exportovateľná auditná stopa odvodená z nemenných záznamov prenosov, pre odoslané aj prijaté doklady. Každá udalosť nesie occurred_at, event, result, document_id, AS4 message_id, sbdh_instance_id, counterparty_participant_id a ubl_sha256. Parametre: from/to (UTC dni, predvolene posledných 31 dní), direction (sent | received), format (json | csv), limit (max 1000) a offset. Okno vyberá udalosti podľa ich vlastného času: doklad prijatý v auguste a potvrdený v septembri patrí do septembrového exportu. Hlavička X-Events-Truncated: true (JSON aj CSV) znamená, že okno presiahlo 5 000 zdrojových záznamov jedného smeru – zúžte ho.

GET /v1/agent/peppol/events?from=2026-06-01&to=2026-06-30&format=csv
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="peppol-events-2026-06-01_2026-07-01.csv"

occurred_at,event,direction,result,mode,document_id,invoice_id,message_id,sbdh_instance_id,counterparty_participant_id,ubl_sha256,detail
2026-06-20T08:15:03.000Z,received.mls_sent,received,success,live,f3a1…,,…@phase4.phoss-ap,8f2c1c0e-…,0245:2020202020,3b7c…,Message Level Status sent to the sender
2026-06-20T08:15:00.000Z,received,received,success,live,f3a1…,,,8f2c1c0e-…,0245:2020202020,3b7c…,invoice VF2026123

Testovanie príchodzích dokladov (sandbox)

S test kľúčom (efk_pk_test_…) sa odoslanie na 9915: participanta, ktorý žije na našej platforme — vrátane odosielateľa samého — zároveň materializuje ako reálny prijatý doklad pre danú organizáciu a vyšle ten istý webhook peppol.document.received, aký posiela ostrá inbound linka. Celú cestu príjmu si tak overíte sami, bez toho, aby sme vám niečo posielali my.

Cieľovú organizáciu zaregistrujte test kľúčom (POST /v1/agent/peppol/enroll vytvorí jej 9915:{DIČ} participanta), na webhook endpointe si zapnite odber peppol.document.received a pošlite test faktúru, ktorej odberateľ má DIČ tejto organizácie — vlastné pre self-send, alebo druhej test organizácie pre test A → B.

POST /v1/agent/peppol/send/b1f0d7a2-…
X-API-Key: efk_pk_test_...
X-Organization-Id: <odosielajúca org>

GET /v1/agent/peppol/received
X-API-Key: efk_pk_test_...
X-Organization-Id: <prijímajúca org>

Vzťah k webhooku

Keď vám príde doklad cez Peppol, systém ho uloží (objaví sa v GET /peppol/received) a zároveň vyšle webhook peppol.document.received. Polling a webhook sú dva pohľady na tú istú udalosť: webhook je push notifikácia, received endpoint je autoritatívny zoznam.

{
  "event": "peppol.document.received",
  "timestamp": "2026-06-20T08:15:00.000Z",
  "data": {
    "senderName": "Dodávateľ a.s.",
    "senderParticipantId": "9915:9999999999",
    "documentNumber": "VF2026123",
    "documentType": "invoice",
    "total": "240.00",
    "currency": "EUR",
    "orgId": "0a2c1f3e-…"
  }
}

Doklady z API do účtovného programu

Prijaté doklady vytvorené cez POST /v1/agent/expenses odovzdáte účtovnému programu firmy cez Konektor (Omega, Pohoda, Money S3, MRP) rovnako ako klik na „Zaúčtovať“ v eDokladoch. Bez tohto kroku sa doklad z API do programu nedostane. Potrebný scope je receipt:approve:

Prvé volanie označí doklad ako schválený na zaúčtovanie a odovzdá ho aktívnemu konektoru firmy. Opakované volania nič nerobia. Telo požiadavky netreba.

POST /v1/agent/expenses/5b7e91c4-…/approve-for-accounting
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 200 OK

{
  "data": {
    "id": "5b7e91c4-…",
    "approved_for_accounting_at": "2026-10-13T08:15:00.000Z",
    "sent_to_accounting": true
  }
}

sent_to_accounting: false znamená, že doklad už bol schválený skôr alebo ho zamkol súborový export — nič sa neodoslalo znova. Doklad v stave processing, needs_review alebo rejected vráti 409 EXPENSE_NOT_POSTABLE (details.status nesie stav); neexistujúci doklad 404.

Hromadne: POST /v1/agent/expenses/bulk s { "ids": [...], "action": "approve_for_accounting" } (max 100 ID). Odošlú sa len doklady schválené na zaúčtovanie prvýkrát a nie v stave processing, needs_review ani rejected; ostatné sa preskočia a nezapočítajú do processed_count.