Jak zabránit dvojímu zápisu dokladu do Pohody
Výpadek sítě, timeout nebo opakovaný webhook — a v Pohodě máte stejnou objednávku dvakrát. Jedna hlavička tomu spolehlivě zabrání.
Každá integrace jednou narazí na tuhle situaci: aplikace pošle objednávku do Pohody, ale odpověď nedorazí. Vypadla síť, vypršel timeout, server se restartoval. Prošla objednávka, nebo ne? Když požadavek zopakujete, riskujete duplicitu. Když ho nezopakujete, riskujete, že objednávka chybí.
apios tohle řeší hlavičkou Idempotency-Key.
Jak to funguje
Ke každému zápisu pošlete hlavičku Idempotency-Key s jedinečným klíčem. Pohoda si klíč zapamatuje a požadavek se stejným klíčem zpracuje jen jednou. Když ho pošlete znovu, nic nového nezapíše a API vrátí 409 Conflict.
curl -X PUT https://api.apios.cz/api/v1/order/received \
-H "X-AUTH-TOKEN: VAS_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: eshop-objednavka-2026-1042" \
-d '{ "order_id": "2026-1042", "customer_id": 25, "order_items": [{ "ids": "STUL-01", "qty": 1 }] }'
Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:
Druhé odeslání téhož požadavku vrátí:
{
"error": "Požadavek s tímto Idempotency-Key už Pohoda zpracovala.",
"detail": {
"idempotency_key": "eshop-objednavka-2026-1042",
"hint": "Nic nového se nezapsalo. Výsledek původního požadavku najdete exportem (např. filtrem last_changes). Pro nový záznam použijte nový klíč."
}
}
Jaký klíč zvolit
Klíč musí být stejný pro opakování téže operace a jiný pro každou novou operaci. Nejlépe ho odvodíte z identifikátoru ve vašem systému:
| Operace | Dobrý klíč |
|---|---|
| Import objednávky | eshop-objednavka-{číslo objednávky} |
| Faktura z objednávky | faktura-z-objednavky-{ID objednávky} |
| Úhrada z platební brány | platba-{ID platby v bráně} |
| Měsíční faktura za předplatné | predplatne-{zákazník}-{rok}-{měsíc} |
Co dělat s odpovědí 409
409 znamená „tohle už v Pohodě je“. Pro většinu integrací to je úspěch — objednávka existuje, stačí ji dohledat. Pomůže export s filtrem, například podle čísla objednávky z e-shopu nebo podle data změny:
curl "https://api.apios.cz/api/v1/order/received?last_changes=2026-10-19T08:00:00" \
-H "X-AUTH-TOKEN: VAS_API_TOKEN"
Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:
Kde hlavičku použít
Idempotency-Key přijímají všechny zápisové endpointy: vytvoření objednávky, faktury, adresy, skladových dokladů, úhrady faktury i hromadné importy. Posílejte ji všude, kde požadavek po chybě automaticky opakujete — typicky ve frontách, cron úlohách a webhoocích.