Idempotency v eConnect PSB API: jak zabránit duplicitnímu odesílání pomocí hlavičky X-EConnect-DocumentId.
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:
@ a _ nejsou povolenyDů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ý vygenerujete jednou pro dokument a při retry znovu použijete.
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ě:
X-EConnect-DocumentId.200 OK: dokument je zpracován, hotovo.409 Conflict: dokument byl již zpracován při předchozím pokusu, hotovo.5xx chybu nebo timeout: počkejte a zopakujte požadavek se stejným documentId.4xx chybu (kromě 409): problém je v samotném požadavku. Opakování nemá smysl, chybu je potřeba opravit.Odeslání dokumentu s X-EConnect-DocumentId
Odpověď?
Zpracováno
Již zpracováno, bezpečně ukončit
Počkat (exponential backoff)
Opravit chybu, neretryovat
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.
Při doručení dokumentu platí retry politika maximálně 8 pokusů během přibližně 72 hodin (asi 3 dny). To je oddělené od HTTP 5xx retry na vlastním API nebo webhookech: zda se chyba doručení zopakuje, závisí na kanálu doručení.
Hlavička X-EConnect-DocumentId je podporována na všech endpointech, kde nahráváte dokumenty do PSB. Nejdůležitější jsou:
POST /api/v1/{partyId}/salesInvoice/sendPOST /api/v1/{partyId}/generic/sendPOST /api/v1/{partyId}/purchaseOrder/sendPro 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.
Ve zkratce
Při každém uploadu dokumentu odešlete hlavičku X-EConnect-DocumentId s unikátním UUID. Při retry PSB vrátí 409 Conflict, pokud byl dokument již zpracován. Nikdy nepoužívejte číslo faktury jako documentId.
Číslo faktury se může znovu objevit na dobropisu nebo opravené faktuře. Použijte UUID (v4) na dokument a při retry ho znovu použijte, aby kontrola 409 visela na dokumentu, ne na čísle faktury.
PSB pak vygeneruje documentId sám. Nevýhoda: po síťové chybě nevíte, zda dokument už byl zpracován. Vlastní documentId umožňuje bezpečný retry: duplicitní upload vrátí 409 Conflict.
Idempotency platí pro všechny write endpointy, které nahrávají dokumenty, například odeslání faktur, objednávek a obecných dokumentů. Pro download endpointy neplatí, protože stažení data nemění.
Zobrazit kompletní API dokumentaci