# Odosielanie dokumentov

URL: https://postman.slovakodata.com/developers/odosielanie/
Aktualizované: 2026-08-27

Idempotencia, limity požiadavky a odpoveď pri odoslaní dokumentu.

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ý**.

| Ako doklad skončil | Ten istý doklad | Opravený doklad |
|---|---|---|
| zamietnutý našou validáciou | prejde | prejde |
| príjemca sa nenašiel v Peppole (`UNDELIVERABLE`) | prejde | prejde |
| zrušený pred odoslaním | prejde | prejde |
| **zamietnutý protistranou** (prišlo MLS `NOK`) | `409` | **prejde** |
| **prenos sme začali a zlyhal** | `409` | `409` |
| **odoslaný, odpoveď zatiaľ nedorazila** | `202` (prehratie) | `409` |
| **bez odpovede protistrany** (`TIMEOUT`) | `202` (prehratie) | `409` |
| **doručený** | `202` (prehratie) | `409` — riešte **dobropisom** |

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`):

| Pole | Kde v UBL |
|---|---|
| BT-34-1 | atribút `schemeID` na `cbc:EndpointID` dodávateľa |
| BT-34 | hodnota toho istého `cbc:EndpointID` |
| BT-03 | `cbc:InvoiceTypeCode` (`cbc:CreditNoteTypeCode` pri dobropise) |
| BT-01 | číslo faktúry, koreňové `cbc:ID` |
| BT-02 | dátum vystavenia, `cbc:IssueDate` |

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

| Vlastnosť | Hodnota |
|---|---|
| `Content-Type` | `application/json` |
| Maximálna veľkosť | 10 MB |
| Odpoveď pri úspechu | `202 Accepted` |
| Kontrola pri príjme | Platná JSON obálka a správne utvorené XML v poli `payload`. Hlbšia validácia beží až potom. |