API pro vývojáře: propojení s Doklad.ai

Sedíš nad backlogem a říkáš si: „Export CSV zase selhal? Fakt jo?“ Přesně. Ruční přepisování faktur do ERP je očistec. API pro vývojáře ti dá klid: systém si s Doklad.ai povídá sám a ty koukáš jen na čistá data.

Co přesně naše API umí a proč se o něj opřít

API pro vývojáře v Doklad.ai je navržené tak, aby ses k datům dostal rychle, bezpečně a bez záseků. Faktury, zálohovky, kontakty, sklady, párování plateb, cashflow přehledy. Všechno přes jednotné endpointy, konzistentní kódy a čitelné chyby. Prostě to, co chceš jako vývojář slyšet.

REST rozhraní s JSON payloady

Stabilní verzování (v1, v1.1… s changelogem)

OAuth 2.0 i Personal Access Token (pro server–server)

Webhooky na důležité eventy (vystavena faktura, zaplaceno, storno)

Sandbox prostředí zdarma pro testy

Tip: Potřebuješ jen vystavit fakturu a hotovo? Minimální integrace = 1 endpoint na vytvoření dokladu + webhook na placení. Zvládneš odpoledne.

Jak začít: od klíče k první faktuře do 15 minut

Chceš rychlý start? Jasně. Tohle je nejkratší cesta od nuly k prvnímu úspěšnému requestu.

1) Založ sandbox a vygeneruj token

V Doklad.ai otevři Nastavení → Integrace → Vývojářský přístup

Zapni Sandbox a vygeneruj „Personal Access Token“

Ulož si ho do trezoru (Vault, Doppler, 1Password). Nikdy do repa

2) Ověř přístup a verzi API

Posli GET na /api/v1/me s hlavičkou Authorization: Bearer <TOKEN>

V odpovědi uvidíš účet, oprávnění a aktivní verzi

Kód 200? Máš zelenou. Kód 401? Zkontroluj token nebo scope

3) Vytvoř první fakturu

POST /api/v1/invoices

Posli zákazníka, položky, sazby DPH a variabilní symbol

Odpovědí je JSON s ID faktury, QR platbou a PDF URL

Tip: Generuj external_id podle tvého ERP. Později pak synchronizuješ bezpečně bez duplikátů.

4) Zapni webhooky

V Nastavení → Webhooky přidej URL svého listeneru (HTTPS)

Zvol eventy: invoice.issued, payment.matched, invoice.cancelled

Ověř podpis zprávy přes HMAC klíč, ať ti to nikdo nefalšuje

Jaké datové modely a endpointy budeš používat nejčastěji

API pro vývojáře stojí na pár jednoduchých, ale dobře promyšlených modelech. Tohle je top pětka, kterou používá 90 % integrací.

Faktury (Invoices)

Vystavení, aktualizace, storno, PDF export, QR platba

Možnost zálohové → vyúčtovací faktury, dobropisy

Pole: customer, lines, currency, due_date, vs, tags

Kontakty (Customers)

Firemní i osobní zákazníci s párováním na IČ/DIČ

Enrichment přes ARES/VIES (pokud zapneš)

Platby (Payments)

Import z banky, ruční zápis, automatické párování podle VS/částky/datumu

Napojení na platební brány (GoPay, Stripe) přes externí referenci

Sklad a náklady (Items, Expenses)

Položky s ceníkem, jednotkami, DPH a kategoriemi

Náklady s OCR, schvalováním a přiřazením k projektu

Webhooky a události (Events)

Spolehlivá dodávka s retry backoffem

Podpis payloadu a idempotence event_id

Bezpečnost a autentizace: jak to děláme, aby ses nebál

Když integruješ fakturaci a účetnictví, chyba prostě nepřipadá v úvahu. Takže autentizace, oprávnění a audit jsou první liga.

Autentizace

OAuth 2.0 Authorization Code Flow pro aplikace s uživatelem

Personal Access Token pro server–server integrace, rotovatelný, se scope

Oprávnění (Scopes)

Jemná granularita: invoices:read, invoices:write, payments:read, contacts:write…

Token nikdy nedostane víc, než explicitně požádáš

Idempotence a opakovatelnost

Pošli hlavičku Idempotency-Key u zápisových operací

Pokud spadne spojení, restartni request se stejným klíčem — vytvoří se jen jeden záznam

Audit a logování

Každá změna má stopu: kdo, kdy, co přesně poslal a jaký byl výsledek

Logy v sandboxu i produkci, export přes CSV/JSON

Verzování a stabilita: co se ti nerozsype při releasu

Mám rád API, které nepřekvapí. Změny jsou fajn, ale ne v pátek večer bez varování.

Stabilní major verze: /api/v1/ držíme beze změn rozhraní

Novinky přidáváme minor verzemi a volitelnými poli

Deprekace vždy s předstihem, e-maily + changelog + datově měkký přechod

Tabulka, jak k tomu přistupujeme v praxi:

Scénář změny	Jak to řešíme	Co to znamená pro tebe
Přidání pole	Non-breaking v rámci v1	Stačí ignorovat, pokud nepotřebuješ
Přejmenování pole	Nikdy bez nové verze	Bezpečné, žádný skrytý breaking change
Odebrání endpointu	Deprekace 6 měsíců + v2	Dost času a jasný migrační návod
Změna limitů	Oznámení 30 dní předem	Upravíš retry/backoff a je klid

Limity, výkon a škálování: ať se ti to pod zátěží nezlomí

Jasně, děláš integraci, která v noci nasype desetitisíce faktur. API pro vývojáře na to myslí.

Rate limiting a retry

Limit per token a IP; standardně 600 requestů/min

429 Too Many Requests vrací bezpečný Retry-After

Doporučuju exponenciální backoff + jitter, ať se to po výpadku nesejde

Stránkování a filtry

Konzistentní page a per_page, maximum 200

Filtry podle času updated_from, updated_to pro inkrementální sync

Webhook retry

Až 12 pokusů v rostoucích intervalech

Požadavky vždy podepsané a znovu přehratelné

Praktické integrační vzory, které fungují

Tři scénáře, co vídám pořád. A které ti ušetří dny práce.

1) ERP/CRM → Doklad.ai (vystavení faktur)

Tvoje aplikace drží master data zákazníků a objednávek

Při přechodu do stavu „k fakturaci“ vytvoří fakturu v Doklad.ai

Sleduješ payment.matched a podle toho měníš stavy v ERP

2) E‑shop → Doklad.ai (automat faktur)

Po zaplacení objednávky přes bránu zavoláš POST /invoices

Do popisu položek dáš SKU a daňové sazby z katalogu

PDF a číslo faktury vrátíš zákazníkovi v potvrzovacím e‑mailu

3) Banka → Doklad.ai → tvoje BI (cashflow)

Bankovní výpisy se importují do Doklad.ai a párují s fakturami

Přes GET /payments taháš agregace do datového skladu

V BI kreslíš DSO, aging, předvídáš cashflow

Tip: Všechny integrace dělej event‑driven. Webhook je pravda, REST je dohánění stavu. Ušetříš náklady na polling a zrychlíš reakce systému.

Chyby a ladění: jak číst odpovědi a neztratit čas

Chyby máme radši čitelné než poetické. Každý 4xx/5xx vrací kód, strojově čitelný error a lidské message.

400 Bad Request — schází pole, špatný formát, detail v fields[]

401 Unauthorized — token/hlavička nesedí, nebo vyexpirované oprávnění

403 Forbidden — chybí scope, nebo přístup k danému účtu

404 Not Found — id neexistuje, nebo je skryté scope

409 Conflict — duplicitní external_id bez idempotence

422 Unprocessable Entity — validační chyba položek/DPH

429 Too Many Requests — zpomal, čekej Retry-After

500/503 — výjimečně; logujeme, máme status stránku a SLA

Pro sandbox posíláme detailní correlation_id. Ulož si ho do logu; když napíšeš supportu, je to tvůj zlatý klíč.

Bezpečné nasazení: checklist pro produkci

Nechci ti kázat, ale tohle je osvědčený seznam, který drží integrace v kondici.

Rotace tokenů min. 90 dní, oddělené tokeny pro prostředí

Idempotentní zápisy s Idempotency-Key

Validace webhook podpisu (HMAC + časové okno)

Circuit breaker a retry s jitterem

Rate limit guard (lokální fronta)

Alerty na chybovost a latenci, dashboard s 5xx a 429

Inkrementální sync přes updated_from

Obsahová validace DPH a částek, jednotky měny

Příklad mapování dat: jak z ERP do faktury

Struktura je přímá. Tohle rychle pochopíš i poslepu.

Tvoje pole v ERP	Pole v Doklad.ai	Poznámka
customer.id	customer.external_id	Stabilní klíč pro sync
customer.ICO	customer.registration_id	IČ, kontrola přes ARES
items[].sku	lines[].item_code	Pro párování ceníku
items[].price_vat	lines[].unit_price	U nás bez DPH, pošli i sazbu
order.vs	vs	Páteř párování plateb
order.note	note	Volitelné, uvidí ho účetní

Dokumentace a nástroje: kde všechno najdeš

Živá dokumentace s try‑it konzolí

OpenAPI (Swagger) schéma ke stažení

SDK: JS/TS, Python, PHP — oficiální balíčky, verzované

Postman kolekce s příklady requestů a testy

Tip: V CI pipeline pouštěj kontraktní testy proti našemu OpenAPI schematu. Odhalí breaking změny v tvém kódu dřív, než je uvidí zákazník.

Integrace krok za krokem: rychlý plán na 1 sprint

Den 1–2: Analýza use‑casu, výběr scope, návrh mapování

Den 3: Sandbox, token, první faktura, QR a PDF

Den 4: Webhooky, validace podpisu, idempotence

Den 5: Sync kontaktů, párování plateb

Den 6: Chybové stavy, retry strategie, logování

Den 7: E2E testy, monitoring, nasazení do pilotu

Kdy zvolit API pro vývojáře a kdy raději export/import

Někdy se vyplatí jít lehčí cestou. Jindy je API jasná volba.

Potřeba	API	Export/Import
Real‑time aktualizace	✔︎	✖︎
Obousměrná synchronizace	✔︎	✖︎
Jednorázová migrace	✖︎	✔︎
Nulový vendor‑lock	✔︎	✔︎
Nízké náklady bez vývoje	✖︎	✔︎

Bezpečnost dat a compliance: ano, řešíme to důsledně

Šifrování dat v klidu i za letu (AES‑256, TLS 1.2+)

Datová rezidence EU, pravidelné penetrační testy

Role‑based access + audit trail, export auditů pro kontroly

DPH režimy a sazby podle ČR/EU, reverse charge, OSS podpora

Závěr: API pro vývojáře, co ti zrychlí podnikání

Chceš méně ručních chyb, méně CSV a víc automatizace? API pro vývojáře v Doklad.ai ti otevře dveře k čisté integraci — od faktur přes platby až po reporting. Připoj to jednou, funkčně a bezpečně. A pak už jen sleduj, jak si systémy povídají samy.

Časté otázky

Jak rychle můžu přes API vystavit první fakturu?

Sandbox aktivuješ za minutu, token máš hned. První fakturu přes POST /api/v1/invoices zvládneš do 10–15 minut, pokud máš připravená data zákazníka a položek.

Umí API párovat platby automaticky podle variabilního symbolu?

Ano. Doklad.ai načítá platby z banky a páruje podle VS, částky a data. Ty přes webhook payment.matched dostaneš potvrzení a můžeš změnit stav objednávky v ERP.

Co když při vytváření faktury pošlu request dvakrát?

Použij hlavičku Idempotency-Key. I když request zopakuješ, vznikne jen jeden doklad. Bez ní dostaneš 409 Conflict u stejného external_id.

Máte SDK nebo musím psát integraci od nuly?

Máme oficiální SDK pro JS/TS, Python a PHP, plus Postman kolekci. Klidně ale můžeš jet čisté REST; dokumentace je srozumitelná a obsahuje příklady.

Jak dlouho držíte kompatibilitu starších verzí API?

Major verze držíme stabilní. Při deprekaci dáváme minimálně 6 měsíců a detailní migrační návod. Minor změny jsou non‑breaking a volitelné.

Jak zabezpečím webhook endpoint proti podvržení?

Ověřuj HMAC podpis a časové razítko, přijímej jen HTTPS a používej allowlist IP. Pro jistotu loguj event_id a correlation_id pro audit a replay.

API pro vývojáře — jak propojit Doklad.ai s vlastním systémem