Pri odosielaní faktúr a iných dokumentov cez API vždy existuje riziko duplicitného odoslania. Sieťový timeout, reštart aplikácie alebo neočakávaná chyba môžu viesť k situácii, keď si nie ste istí, či bol dokument skutočne spracovaný. Bez ochrany by ste mohli ten istý dokument odoslať znovu, čo by viedlo k duplicitným faktúram.

PSB API ponúka zabudovaný mechanizmus idempotency, ktorý tento problém rieši. Odoslaním unikátneho documentId pri každom uploade PSB rozpozná duplicitné pokusy a zabráni dvojitému spracovaniu toho istého dokumentu.

Mechanizmus idempotency sa opiera o HTTP hlavičku X-EConnect-DocumentId. Pri odosielaní dokumentu pridáte túto hlavičku s unikátnou hodnotou, ktorá dokument identifikuje.

POST /api/v1/{partyId}/salesInvoice/send HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {token}
Content-Type: application/xml
X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  ...
</Invoice>

PSB dokument spracuje a uloží documentId. Ak odošlete rovnakú požiadavku znovu (napríklad retry po timeoute), PSB rozpozná, že documentId už existuje, a vráti odpoveď 409 Conflict namiesto opätovného spracovania dokumentu.

HTTP/1.1 409 Conflict

Tento 409 nie je chybová správa v tradičnom zmysle. Je to potvrdenie, že dokument bol už skôr úspešne spracovaný. Vaša aplikácia môže požiadavku bezpečne označiť ako dokončenú.

DocumentId, ktoré odosielate v hlavičke X-EConnect-DocumentId, musí spĺňať niekoľko podmienok:

Dôležité: nikdy nepoužívajte číslo faktúry ako documentId. Číslo faktúry sa môže znovu použiť pri dobropise alebo opravenej faktúre, čo vedie ku konfliktom. Namiesto toho použite UUID/GUID, ktorý generujete pri každom pokuse o odoslanie.

UUID je odporúčaná voľba. Je zaručene unikátny a široko podporovaný vo všetkých programovacích jazykoch.

Správne: 550e8400-e29b-41d4-a716-446655440000  (UUID)
Správne: DOC2026030800142                       (vlastná sekvencia, ak je unikátna)
Chybné:  INV-2026-001                           (číslo faktúry, nepoužívať)
Chybné:  ab@cd                                  (špeciálne znaky)
Chybné:  abc                                    (príliš krátke)

Idempotency je najcennejšia v kombinácii s retry logikou. Ak API volanie zlyhá kvôli sieťovej chybe alebo 5xx chybe servera, chcete požiadavku zopakovať bez rizika duplicitného spracovania.

Odporúčaný postup funguje nasledovne:

1. Pred odoslaním požiadavky vygenerujte unikátne documentId (UUID).
2. Odošlite dokument s hlavičkou X-EConnect-DocumentId.
3. Ak obdržíte 200 OK: dokument je spracovaný, hotovo.
4. Ak obdržíte 409 Conflict: dokument bol už spracovaný pri predchádzajúcom pokuse, hotovo.
5. Ak obdržíte 5xx chybu alebo timeout: počkajte a zopakujte požiadavku s rovnakým documentId.
6. Ak obdržíte 4xx chybu (okrem 409): problém je v samotnej požiadavke. Opakovanie nemá zmysel, chybu je potrebné opraviť.

Tip: pri retries používajte exponential backoff. Začnite s krátkou čakacou dobou (napríklad 1 sekunda) a zdvojnásobte ju pri každom ďalšom pokuse, do maxima napríklad 60 sekúnd. Samotný PSB uplatňuje retry politiku s maximálne 8 pokusmi počas približne 35 hodín pri 5xx chybách.

Hlavička X-EConnect-DocumentId je podporovaná na všetkých endpointoch, kde nahrávate dokumenty do PSB. Najdôležitejšie sú:

Pre endpointy na prijímanie (sťahovanie dokumentov) sa idempotency neuplatňuje: získavanie dokumentu je zo svojej podstaty idempotentné, pretože nemení dáta.

Idempotency je malý mechanizmus s veľkým účinkom. Dôsledným odosielaním X-EConnect-DocumentId pri každom uploade dokumentu sa chránite pred duplicitným odoslaním. V kombinácii s retry logikou a exponential backoff budujete robustnú integráciu odolnú voči sieťovým problémom a dočasným chybám servera.