Většina lidí, kteří napojují e-shop na fakturační API, řeší stejných pět věcí — a často je řeší až ve chvíli, kdy systém v produkci spadne. Tady je, na co myslet hned od začátku.

1. Idempotence: pište jako kdyby se vám síť rozbila

E-shop pošle požadavek na vystavení faktury. Síť mezi vámi a FakturOS klopýtne. Vy nevíte, jestli faktura vznikla, nebo ne. Pošlete to znovu. Vznikne duplikát. Klient dostane dvě faktury. Vy dostanete e-mail.

Řešení: idempotency key. Každý POST má v hlavičce Idempotency-Key: <cokoliv unikátního>. FakturOS si pamatuje, který klíč už zpracoval — když přijde podruhé, vrátí původní odpověď, ne novou fakturu.

curl -X POST https://api.fakturos.cz/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: order_2026_4827" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Pravidlo: použijte unikátní ID objednávky z vašeho e-shopu. Jednoduché, robustní, funkční.

2. Webhooks místo neustálého ptaní

Špatné řešení: každou minutu se ptáte API, jestli už je faktura zaplacená. Dobré řešení: FakturOS vám pošle POST ve chvíli, kdy se to stane.

Nastavte si webhooky pro:

  • invoice.paid — odešli zboží zákazníkovi
  • invoice.overdue — pozastav opakovanou objednávku
  • stock.low — objednej nové zboží od dodavatele
Bezpečnost

Vždy ověřujte HMAC podpis v hlavičce X-Fakturos-Signature. Bez něj nemůžete důvěřovat, že požadavek opravdu poslal FakturOS a ne někdo třetí.

3. Retry, ale chytře

Pokud FakturOS vrátí 5xx, je to dočasná chyba — vyplatí se zkusit znovu. Pokud vrátí 4xx, je něco špatně s vaším požadavkem — opakovaným pokusem to nezachráníte. Implementujte exponenciální backoff:

  1. 1. pokus → ihned
  2. 2. pokus → po 2 vteřinách
  3. 3. pokus → po 4 vteřinách
  4. 4. pokus → po 8 vteřinách
  5. 5+ pokusů → uložit do fronty a zkusit za hodinu

4. Vyzkoušejte si vše v sandboxu

FakturOS má samostatné sandbox prostředí na sandbox.api.fakturos.cz. Vystavujete tam fiktivní faktury, vyvoláváte webhooks, testujete edge case scénáře — a všechno se vám každý týden samo resetuje. Bez sandboxu byste otestovali jen 30 % toho, co můžete.

5. Sledujte rate limit hlavičky

Po každé odpovědi vám FakturOS v hlavičkách řekne, kolik máte ještě k dispozici:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset:     1763890000

Když se blížíte k limitu, zpomalte. Když ho překročíte, dostanete 429 — počkejte do času v Retry-After a teprve pak pokračujte.

Pět drobností, které vám ušetří desítky hodin ladění. Podrobnější návody najdete v API dokumentaci, nebo nám napište přímo na api@fakturos.cz — ozveme se.