Při odesílání faktur a dalších dokumentů přes API vždy existuje riziko duplicitního odeslání. Síťový timeout, restart aplikace nebo neočekávaná chyba mohou vést k situaci, kdy si nejste jisti, zda byl dokument skutečně zpracován. Bez ochrany byste mohli tentýž dokument odeslat znovu, což by vedlo k duplicitním fakturám.

PSB API nabízí zabudovaný mechanismus idempotency, který tento problém řeší. Odesláním unikátního documentId při každém uploadu PSB rozpozná duplicitní pokusy a zabrání dvojitému zpracování téhož dokumentu.

Mechanismus idempotency se opírá o HTTP hlavičku X-EConnect-DocumentId. Při odesílání dokumentu přidáte tuto hlavičku s unikátní hodnotou, která 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 zpracuje a uloží documentId. Pokud odešlete stejný požadavek znovu (například retry po timeoutu), PSB rozpozná, že documentId již existuje, a vrátí odpověď 409 Conflict místo opětovného zpracování dokumentu.

HTTP/1.1 409 Conflict

Tento 409 není chybová zpráva v tradičním smyslu. Je to potvrzení, že dokument byl již dříve úspěšně zpracován. Vaše aplikace může požadavek bezpečně označit jako dokončený.

DocumentId, které odesíláte v hlavičce X-EConnect-DocumentId, musí splňovat několik podmínek:

Důležité: nikdy nepoužívejte číslo faktury jako documentId. Číslo faktury se může znovu použít u dobropisu nebo opravené faktury, což vede ke konfliktům. Místo toho použijte UUID/GUID, který generujete při každém pokusu o odeslání.

UUID je doporučená volba. Je zaručeně unikátní a široce podporovaný ve všech programovacích jazycích.

Správně: 550e8400-e29b-41d4-a716-446655440000  (UUID)
Správně: DOC2026030800142                       (vlastní sekvence, pokud je unikátní)
Chybně:  INV-2026-001                           (číslo faktury, nepoužívat)
Chybně:  ab@cd                                  (speciální znaky)
Chybně:  abc                                    (příliš krátké)

Idempotency je nejcennější v kombinaci s retry logikou. Pokud API volání selže kvůli síťové chybě nebo 5xx chybě serveru, chcete požadavek zopakovat bez rizika duplicitního zpracování.

Doporučený postup funguje následovně:

1. Před odesláním požadavku vygenerujte unikátní documentId (UUID).
2. Odešlete dokument s hlavičkou X-EConnect-DocumentId.
3. Pokud obdržíte 200 OK: dokument je zpracován, hotovo.
4. Pokud obdržíte 409 Conflict: dokument byl již zpracován při předchozím pokusu, hotovo.
5. Pokud obdržíte 5xx chybu nebo timeout: počkejte a zopakujte požadavek se stejným documentId.
6. Pokud obdržíte 4xx chybu (kromě 409): problém je v samotném požadavku. Opakování nemá smysl, chybu je potřeba opravit.

Tip: při retries používejte exponential backoff. Začněte s krátkou čekací dobou (například 1 sekunda) a zdvojnásobte ji při každém dalším pokusu, do maxima například 60 sekund. Samotný PSB uplatňuje retry politiku s maximálně 8 pokusy během přibližně 35 hodin při 5xx chybách.

Hlavička X-EConnect-DocumentId je podporována na všech endpointech, kde nahráváte dokumenty do PSB. Nejdůležitější jsou:

Pro endpointy na přijímání (stahování dokumentů) se idempotency neuplatňuje: získávání dokumentu je ze své podstaty idempotentní, protože nemění data.

Idempotency je malý mechanismus s velkým účinkem. Důsledným odesíláním X-EConnect-DocumentId při každém uploadu dokumentu se chráníte před duplicitním odesláním. V kombinaci s retry logikou a exponential backoff budujete robustní integraci odolnou vůči síťovým problémům a dočasným chybám serveru.