Odosielanie dokumentov

Jedno volanie, okamžitá odpoveď, asynchrónne doručenie.

Idempotencia

Hlavička Idempotency-Key je povinná a chráni vás pred duplicitnou faktúrou, keď sa spojenie preruší a vy odoslanie zopakujete. Zapamätáme si kľúč aj odtlačok tela na 24 hodín a správame sa takto:

• Rovnaký kľúč, rovnaké telo — vrátime pôvodnú odpoveď, dokument sa neodošle druhýkrát.
• Rovnaký kľúč, iné telo — 409 s kódom SAPI-VAL-009. Kľúč sa nesmie recyklovať.
• Nový kľúč — rozhodne obchodný kľúč nižšie.

Obchodný kľúč: pätica polí podľa ID-BDID-01

Nad hlavičkou beží ešte druhá vrstva, ktorá nezávisí od toho, aký Idempotency-Key pošlete. Dokument identifikujeme päticou polí podľa slovenskej Peppol architektúry (pravidlo ID-BDID-01): schéma a identifikátor dodávateľa, typ dokladu, číslo faktúry a dátum vystavenia. Presné umiestnenie v UBL nájdete v tabuľke nižšie.

Z toho plynú dva dôsledky: faktúra a dobropis s rovnakým číslom sú dva rôzne doklady (líšia sa v BT-03), a rovnako sú dva rôzne doklady dve faktúry s rovnakým číslom, ale iným dátumom vystavenia.

Rozhodujú dve otázky naraz: odišiel predošlý doklad do siete? a posielate ten istý doklad, alebo opravený?

• Predošlý doklad do siete neodišiel — podanie prejde, či už posielate ten istý doklad alebo opravený. Číslo faktúry ostáva vaše. Vznikne nový doklad s novým providerDocumentId, pôvodný ostáva vo výpise so svojím stavom.
• Predošlý doklad sme prevzali do úschovy alebo ho protistrana prevzala a posielate ho nezmenený — vrátime 202 s pôvodným providerDocumentId. Druhá faktúra nevznikne, kredit sa nespotrebuje a doklad sa neposiela znova. Kým prevzatie ešte prebieha, odpoveď je iná — viď „Doklad, ktorý sa práve spracúva” nižšie.
• Protistrana doklad odmietla (prišlo MLS NOK) — opravený doklad prejde pod tým istým číslom; nezmenená kópia dostane 409.
• Vo zvyšných prípadoch — 409 s kódom SAPI-PERM-002. V details je identifikátor existujúceho dokumentu. Číslo faktúry je obsadené; pošlite doklad pod novým číslom alebo použite dobropis.

Ako sa to meria. Nie podľa stavu — ten istý stav totiž vie vzniknúť pred odoslaním aj po ňom. Rozhodujú dve veci naraz: či dokument opustil náš Access Point, a či posielate ten istý doklad, alebo opravený.

Tri riadky si zaslúžia vysvetlenie.

Zamietnutý protistranou. Toto je jediný prípad, keď opravený doklad prejde pod tým istým číslom: vieme s istotou, že protistrana pôvodný doklad neprijala, takže opravená verzia u nej nemôže pribudnúť ako druhá. Predpisuje to aj architektúra e-faktúry Finančnej správy — pre tento výsledok výslovne uvádza, že pôvodca môže poslať opravené údaje faktúry. Poslať doklad znova nezmenený naopak nemá zmysel: má rovnaký technický identifikátor, protistrana ho zahodí ako duplicitu a vy by ste od nás dostali potvrdenie o niečom, čo príjemca zahodil. Preto vtedy odpovieme 409.

Kým je výsledok neistý, opravu pod tým istým číslom neprijmeme. Keď sa prenos rozbehol a nevieme, ako dopadol — zlyhal, alebo odpoveď zatiaľ nedorazila, prípadne nedorazila v lehote — mohol doklad u protistrany skončiť. Opravená verzia by mu tam pribudla ako druhý doklad s tým istým číslom; technický identifikátor má iný, takže by ju jej systém ako duplicitu nezachytil. Pre tento prípad tá istá architektúra nepredpisuje odoslanie ďalšieho dokladu, ale nápravu na strane poskytovateľov. Číslo sa uvoľní, len čo sa výsledok vyjasní — keď dorazí zamietnutie, platí prvý riadok tabuľky. Ak nechcete čakať, použite nové číslo faktúry alebo dobropis.

Pri nezmenenom doklade sa tie tri riadky líšia. Ak sme ho už odovzdali protistrane (riadky „odoslaný, odpoveď zatiaľ nedorazila” a TIMEOUT), opakovanie dostane 202 s pôvodným providerDocumentId a doklad sa zámerne neposiela znova — pravidlá Peppolu to zakazujú, lebo potvrdenie o prevzatí sme dostali. Ak prenos zlyhal ešte u nás, dostanete 409; zopakovanie takého prenosu nie je nové podanie — napíšte nám a prenos zopakujeme z našej strany.

Doručený. Tu je číslo faktúry definitívne použité. Opravu takého dokladu urobte dobropisom alebo opravnou faktúrou, nie novým podaním pod tým istým číslom.

Doklady mimo Peppolu. Keď posielate na substitútneho príjemcu 0245:9970300001 (faktúra ide k odberateľovi mimo siete a do Peppolu odchádza len daňový doklad pre Finančnú správu), platí tá istá tabuľka — len rolu „protistrany” hrá Finančná správa. Doklad, ktorý FS SR odmietla, teda pošlete opravený pod tým istým číslom; doklad, ktorý FS SR prijala, sa opravuje dobropisom.

Prakticky to znamená, že po zlyhaní doklad neprečíslovávate. Keď zamietneme validáciu a vy chybu opravíte, alebo sa príjemca dodatočne zaregistruje v Peppole po UNDELIVERABLE, pošlete tú istú faktúru pod tým istým číslom. Zodpovedá to aj tomu, čo predpisuje architektúra e-faktúry Finančnej správy pre neúspešné doručenie, aj tomu, že faktúra má poradové číslo podľa zákona o DPH — nedoručená faktúra sa nevystavuje nanovo.

To isté platí pri zlyhaní na našej strane pred prevzatím do úschovy: dostanete 502 s kódom SAPI-PROC-003 a retryable: true a doklad zopakujte pod tým istým číslom.

Doklad, ktorý sa práve spracúva. Ak predošlé podanie toho istého čísla ešte beží, dostanete 502 s kódom SAPI-PROC-003 a retryable: true — počkajte a zopakujte. Táto odpoveď platí najviac 15 minút; potom považujeme prevzatie za nedokončené a nové podanie prejde. Výnimkou je doklad, ktorý sa medzitým už dostal na drôt — vtedy platí tabuľka vyššie bez ohľadu na to, ako dlho je v spracovaní.

Ak dokument ktorékoľvek z tých piatich polí neobsahuje, kľúč sa vyčítať nedá a podanie touto kontrolou neprechádza.

Kontrola duplicity: tie isté polia na oboch rozhraniach

Tá istá kontrola obchodnej duplicity beží aj pri POST /api/v1/invoices. Kľúč je spoločný pre obe rozhrania — líši sa len kód chyby (ERR-400 tu, SAPI-PERM-002 na SAPI) a to, čo sa stane s číslom po zlyhaní: na Enterprise API ho doklad drží ďalej, na SAPI ceste ho uvoľní doklad, ktorý do siete neodišiel (tabuľka vyššie).

Nezáleží pri nej na bajtoch dokumentu — porovnáva sa päť polí faktúry podľa slovenskej Peppol architektúry (pravidlo ID-BDID-01):

Z nich vzniká invoice_uuid v odpovedi. Druhý dokument s rovnakou päticou dostane 409 s kódom ERR-400 a s invoice_id už existujúcej faktúry.

Čo z toho vyplýva pre ERP:

• Iný dátum vystavenia = iný doklad. Faktúra s rovnakým číslom, ale iným cbc:IssueDate, duplicita nie je a prejde.
• Dobropis smie použiť číslo z faktúry — líši sa v BT-03 (381 vs 380).
• Ak príjemca implementuje ID-BDID-01, spočíta pre ten istý doklad tú istú hodnotu — vtedy je invoice_uuid použiteľný ako spoločná referencia naprieč sieťou. Norma to od oboch strán vyžaduje, ale vynútiť sa to nedá: voči príjemcovi, ktorý pravidlo neimplementuje, je invoice_uuid len naša hodnota. Spoľahlivá spoločná referencia je preto naďalej číslo faktúry (BT-01).
• Keď dokument ktorékoľvek z piatich polí neobsahuje, kontrola sa preskočí a invoice_uuid je náhodné. Všetkých päť je v EN16931 povinných, takže sa to týka len dokumentov, ktoré aj tak neprejdú validáciou.
• Faktúry podané pred zavedením ID-BDID-01 kontrola duplicity nezachytí. Ich uložený invoice_uuid vznikol podľa staršieho pravidla a neprepočítava sa — prepočet by menil identifikátor, ktorý ERP už dostalo v odpovedi 202. Podanie toho istého dokladu pod novým Idempotency-Key preto 409 nedostane a založí sa druhýkrát. Podanie s nezmeneným telom a bez nového kľúča zachytí ešte pred kontrolou duplicity idempotencia a vráti pôvodnú faktúru. Je to jednorazové okno: podania od zavedenia pravidla kryté sú — pokiaľ sa z dokumentu dá vyčítať všetkých päť polí.

Obmedzenia požiadavky