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

25. srpna 2026 · Doklad.ai · ai

API pro vývojáře: propojení Doklad.ai s tvým systémem bez nervů. Vygeneruj fakturu, páruj platby, tahaj data. Rychle, bezpečně, předvídatelně.

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

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:

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.

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.

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.