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

Metóda	Cesta	Scope
GET	`/v1/agent/peppol/status/{invoiceId}`	`invoice:read`

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"
  }
}

Pole	Typ	Popis
`invoice_id`	UUID	ID faktúry.
`state`	enum	Stav prenosu (viď stavový automat nižšie).
`error_message`	string \| null	Dôvod zlyhania pri stave ERROR.
`receiver_identifier`	string \| null	Peppol identifikátor príjemcu (napr. 9915:DIČ alebo 0245:DIČ).
`document_id`	string \| null	Identifikátor dokladu v prenose.
`updated_at`	ISO 8601	Čas poslednej zmeny stavu.

Stavový automat

Stav	Význam	Akcia / kedy opakovať
`not_sent`	Pre faktúru zatiaľ neexistuje prenos — ešte nebola odoslaná.	Zavolajte POST /peppol/send/{invoiceId}.
`QUEUED`	Odoslanie je zaradené vo fronte, čaká na worker.	Počkajte a pollujte ďalej (alebo počúvajte webhook).
`SENDING`	Worker práve odosiela doklad cez AP.	Počkajte — prechodný stav.
`SENT`	Doklad bol prijatý Peppol sieťou (AS4 receipt).	Hotovo na úrovni odoslania. Doručenie príjemcovi signalizuje webhook delivered.
`DEFERRED`	Odoslanie je dočasne odložené (napr. dočasná nedostupnosť) a bude sa opakovať.	Neopakujte send manuálne — systém retryuje sám. Pollujte ďalej.
`ERROR`	Odoslanie finálne zlyhalo (viď error_message).	Odstráňte príčinu (často chýbajúca adresa / IČ DPH) a odošlite znova.

Stav DELIVERED (doklad doručený príjemcovi) sa nesie samostatným webhook eventom peppol.document.delivered — na úrovni GET /peppol/status je terminálnym úspešným stavom odoslania SENT. V sandboxe phoss‑ap potvrdzuje doručenie hneď pri submite, takže prechod do SENT je rýchly.

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

Metóda	Cesta	Scope
GET	`/v1/agent/peppol/received`	`invoice:read`

Query parametre:

Parameter	Typ	Default	Popis
`limit`	int 1–100	50	Počet záznamov.
`offset`	int ≥ 0	0	Posun pre stránkovanie.

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"
    }
  ]
}

Pole	Typ	Popis
`id`	UUID	ID prijatého dokladu.
`sender_participant_id`	string	Peppol identifikátor odosielateľa.
`sender_name`	string \| null	Názov odosielateľa.
`sender_ico`	string \| null	IČO odosielateľa.
`document_type`	string	Typ dokladu (napr. invoice, credit_note).
`document_number`	string	Číslo dokladu odosielateľa.
`total`	string	Celková suma s DPH.
`vat_total`	string	Suma DPH.
`currency`	string	Mena.
`status`	enum	Stav spracovania: new, reviewed, matched, rejected, partially_paid, paid.
`issue_date`	date	Dátum vystavenia.
`received_at`	ISO 8601	Čas prijatia dokladu.

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.

Metóda	Cesta	Scope	Content-Type
GET	`/v1/agent/peppol/received/{id}/pdf`	`invoice:read`	`application/pdf`
GET	`/v1/agent/peppol/received/{id}/xml`	`invoice:read`	`application/xml`

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 …

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-…"
  }
}

Odporúčaný vzor: počúvajte webhook a po jeho prijatí (alebo periodicky pre istotu) načítajte GET /peppol/received. Webhooky deduplikujte podľa X-Webhook-Id — detaily v Webhooky.