Idempotency: zabránění duplicitnímu odesílání

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.

Jak to funguje

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

Požadavky na documentId

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

PožadavekPopisMinimálně 6 znakůKratší hodnoty jsou odmítnutyŽádné speciální znakyZnaky jako @ a _ nejsou povolenyUnikátní pro každý dokumentKaždý dokument musí mít vlastní documentId

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ý 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é)
Implementace retry logiky

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.

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í.

Které endpointy podporují idempotency?

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

EndpointFunkcePOST /api/v1/{partyId}/salesInvoice/sendOdeslání prodejní fakturyPOST /api/v1/{partyId}/generic/sendGenerické odeslání dokumentu (self-billing, despatch advice)POST /api/v1/{partyId}/purchaseOrder/sendOdeslání objednávky

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.

Shrnutí

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.

Časté otázky
Proč nesmím použít čí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.

Co se stane, když nepošlu X-EConnect-DocumentId?

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.

Pro které endpointy platí idempotency?

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