Enterprise referencia
Enterprise odoslanie
Odošlete Peppol dokument cez Enterprise API so správnym firemným kontextom a oprávnením.
Predpoklady
- Enterprise prístup a firemný kontext; pri operáciách v mene firmy hlavička X-Firm-Id.
- Oprávnenie pokrývajúce odoslanie dokumentov pre danú firmu.
Postup odoslania
Overte dokument pred odoslaním
POST /api/v1/documents/preflight odhalí chyby skôr, než vytvoríte doklad.
Odošlite dokument
POST /api/v1/documents/send s Idempotency-Key; batch variant riešte len ak naozaj dávkujete.
Overte stav a dôkaz
Stav čítajte cez /api/v1/documents/{id}/status a dôkaz doručenia cez /evidence.
Preflight pred odoslaním
- Preflight odhalí chýbajúce polia skôr, než vznikne doklad s chybou.
- Po chybe preflightu údaje opravte; preskočenie preflightu nie je riešenie.
- Dávkové odoslanie použite len vtedy, keď naozaj dávkujete, a overte stav každej položky.
Vstupné formáty
Za jednu kontrolu zistíte, či máte hotové Peppol UBL, mapovateľné údaje, alebo súbor, ktorý vyžaduje konverziu.
- Jeden konkrétny príklad dokumentu, ktorý váš softvér dnes vytvorí alebo prijme.
Tri typy vstupu
| Vstup | Ako to spoznáte | Ďalší krok |
|---|---|---|
| Hotové Peppol UBL 2.1 | XML s hlavičkou UBL, profilom Peppol BIS Billing a kompletnými fakturačnými údajmi. | SAPI — dokument sa posiela tak, ako je. |
| Štruktúrované údaje bez UBL | Položky, sumy a strany existujú ako polia, ale XML nevzniká. | Connector — údaje sa vedome mapujú na jeho JSON kontrakt. |
| PDF, sken alebo vlastné XML | Súbor nemá štandardnú UBL štruktúru ani úplné polia. | Nie je to automaticky Connector vstup; najprv overte mapovanie. |
Ako formát overiť
Hotový UBL overte cez POST /api/validate bez autentifikácie: application/xml alebo JSON s poľom xml. Limit je 2 MB a 20 volaní za minútu na IP. Výsledok obsahuje XSD, EN 16931 a Peppol BIS pravidlá; samotné HTTP 200 neznamená platný doklad. Validácia nič neposiela a nepotvrdzuje oprávnenia ani dostupnosť príjemcu.
- Skontrolujte koreňový element, hlavičku a profil dokumentu; názov súboru nič neznamená.
- Overte, že dokument obsahuje všetky povinné fakturačné údaje vrátane strán, položiek a súčtov.
- Pri neistote pošlite jeden reprezentatívny príklad podpore; neposielajte produkčné klientske doklady verejne.
curl -X POST "https://dev.epostak.sk/api/validate" \
-H "Content-Type: application/xml" \
--data-binary @invoice.xmlOčakávaný výsledok a chyby
Viete pomenovať svoj vstup a máte priradenú jednu cestu alebo jeden konkrétny overovací krok.
- Súbor vyzerá ako XML, ale nemá UBL profil: patrí na overenie, nie priamo do SAPI.
- Údaje sú v PDF: PDF nie je dokumentové API; potrebujete konverziu alebo vlastnú tvorbu UBL.
Odosielanie, príjem inde
Pochopíte, čo znamená odosielať cez ePošťák a nechať príjem u súčasného poskytovateľa.
- Informácia, kto dnes zabezpečuje príjem dokladov firmy.
Odosielanie a príjem sú dva samostatné smery
- ePošťák môže zabezpečovať iba odosielanie a príjem ponechať tam, kde je dnes.
- Pri send-only sa nemení prijímajúci participant: nevykonáva sa registrácia, migrácia ani odregistrácia v SMP.
- ePošťák nečíta schránku u iného poskytovateľa. Prijatá pošta zostáva u neho.
Čo bude nasledovať
Overí sa aktuálny stav príjmu
Overuje sa smerovanie príjmu u nás, inde, alebo potvrdená neprítomnosť. Neistý výsledok znamená opakovanie overenia, nie automatické prijatie.
Prejde sa send-only onboarding
Partner vytvorí požiadavku, firma potvrdí iba odosielanie a vznikne jej API oprávnenie bez nového účtu.
Firma odosiela kľúčom partnera
Kľúč je viazaný na konkrétnu firmu a pokrýva odoslanie a čítanie stavu vlastného dokladu.
Očakávaný výsledok a chyby
Viete, že príjem zostáva nezmenený, a poznáte kroky, ktoré k send-only ceste patria.
- Poskytovateľ príjmu neznámy: uveďte konkrétnu firmu a jej poskytovateľa; názvy poskytovateľov sa nedopĺňajú odhadom.
- Firma chce neskôr aj príjem: je to samostatná zmena služby, nie pokračovanie send-only toku.
Idempotencia
Zistíte, kedy je zopakovanie požiadavky bezpečné a kedy vytvorí novú operáciu.
- Prehľad operácií, ktoré váš systém opakuje po timeoute.
Kedy je opakovanie bezpečné
| Operácia | Opakovanie | Prečo |
|---|---|---|
| Čítanie stavu (GET) | Bezpečné kedykoľvek. | Nemenia stav. |
| Odoslanie s Idempotency-Key | Bezpečné s rovnakým kľúčom a rovnakým telom. | Systém rozpozná opakovanie a nevytvorí druhý doklad. |
| Pozvánka na súhlas (POST) | Nie je bezpečné naslepo. | Vytvorí novú pozvánku a nový jednorazový odkaz. |
Ako pracovať s idempotency kľúčom
- Kľúč vytvorte pred prvým pokusom a pri opakovaní ho nemeniť.
- Kľúč zmeňte, až keď ide o novú, zámerne odlišnú operáciu.
- customerRef ani customerReference nie je idempotency kľúč.
Očakávaný výsledok a chyby
Opakovanie po timeoute nezdvojí doklad ani operáciu.
- Duplicitný doklad: kľúč alebo telo sa pri opakovaní zmenili.
- Konflikt pri opakovaní: použite pôvodný kľúč a pôvodné telo, alebo zistite stav operácie.
Očakávaný výsledok
Doklad má identifikátor, stav a dostupný dôkaz doručenia pre správnu firmu.
Keď to nefunguje
- 403: firemný kontext a oprávnenie nezodpovedajú firme, ktorej dokument patrí.
- Doklad sa neodošle po preflight chybe: opravte údaje, neobchádzajte preflight.