Connector referencia
Connector príjem
Preberiete prijaté doklady cez Connector udalosti alebo polling a správne ich potvrdíte.
Predpoklady
- Connector prístup a uložený nextCursor pre pravidelný pull.
UBL, dôkazy a podklady pre podporu
Pokročilé čítanie vyžaduje Connector JWT so scope documents:read a povinný customerRef v query, uvedený presne raz. documentId je UUID dokumentu tejto firmy. Na bežný obchodný stav používajte detail dokumentu; tieto podklady ho nenahrádzajú.
- GET /api/v1/connector/documents/{documentId}/ubl — pôvodný dokument ako application/xml.
- GET /api/v1/connector/documents/{documentId}/evidence — štruktúrované technické dôkazy ako JSON.
- GET /api/v1/connector/documents/{documentId}/support-packet — JSON manifest pre podporu a audit, nie ZIP archív.
curl --get "https://dev.epostak.sk/api/v1/connector/documents/<DOCUMENT_UUID>/ubl" \
-H "Authorization: Bearer <CONNECTOR_JWT>" \
--data-urlencode "customerRef=erp-klient-42"Postup prevzatia
Čítajte udalosti
GET /api/v1/connector/events s posledným cursorom, alebo použite Connector webhook.
Importujte doklad
Na udalosť document.received importujte doklad do svojho systému.
Potvrďte a uložte cursor
nextCursor uložte až po lokálnom commite a potvrdenie pošlite idempotentne.
Prevádzkové pravidlá
- Cursor ukladajte až po lokálnom commite, inak pri páde preskočíte doklady.
- Webhook je doplnok k pollingu, nie jeho náhrada; udalosti môžu prísť mimo poradia.
- Potvrdzujte iba doklady, ktoré sú naozaj uložené vo vašom systéme.
Očakávaný výsledok
Prijaté doklady sú importované, potvrdené a cursor zodpovedá tomu, čo je naozaj uložené.
Keď to nefunguje
- Cursor uložený pred commitom: po páde preskočíte doklady.
- Duplicitný import: spracujte udalosť idempotentne podľa identifikátora dokladu.