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

· Doklad.ai · ai

API pro vývojáře: propojení Doklad.ai s tvým systémem bez nervů. Vystav fakturu, zapiš úhradu, 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 ruční přepisování faktur z vlastní aplikace do fakturace tě nebaví. Doklad.ai má veřejné REST API, přes které tvůj systém založí zákazníka, vystaví fakturu, zapíše úhradu a pošle fakturu e-mailem. Tenhle návod popisuje, jak API funguje dnes, včetně věcí, které nemá.

Co API umí

  • REST rozhraní s JSON na adresách https://doklad.ai/api/… (bez verze v cestě).
  • Přihlášení API klíčem firmy v hlavičce Authorization: Bearer dk_….
  • Faktury, zákazníky, náklady, platby faktur, PDF, e-maily a exporty.
  • Webhooky na čtyři události.
  • Dokumentaci se Swaggerem přímo v aplikaci.
CoMetoda a cesta
Seznam a detail fakturGET /api/invoices, GET /api/invoices/{id}
Vytvořit fakturuPOST /api/invoices
Upravit fakturu, změnit stavPATCH /api/invoices/{id}
PDF faktury, víc PDF v ZIPGET /api/invoices/{id}/pdf, POST /api/invoices/bulk-pdf
Odeslat fakturu e-mailemPOST /api/invoices/{id}/email
Platby fakturyGET a POST /api/invoices/{id}/payments
Faktury po splatnostiGET /api/invoices/overdue
ZákazníciGET a POST /api/customers, PATCH /api/customers/{id}
NákladyGET a POST /api/expenses
ExportyGET /api/export/invoices/csv, /isdoc, /pohoda, /money-s3
Firma z ARES podle IČO (bez klíče)GET /api/test/ares/lookup/{ico}

Co API nemá

  • Sandbox. Klíč pracuje s ostrými daty firmy.
  • Verzi v cestě (/v1), OAuth pro REST API ani klíče s omezeným rozsahem. Klíč má plný přístup k datům své firmy.
  • Klíč idempotence. Opakovaný požadavek vytvoří fakturu znovu.
  • Oficiální SDK. API voláš přímo přes HTTP.
  • Bankovní účty a platební příkazy (odpověď 403) ani párování bankovních plateb.
  • Hotové konektory pro Zapier, Make nebo platební brány.

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

1) Vytvoř API klíč

Majitel nebo administrátor firmy otevře Nastavení → Integrace → karta „API klíče a webhooky“ → záložka „Klíče & Webhooky“ a klikne na „Nový klíč“. Celý klíč se zobrazí jen jednou. Zkopíruj ho tlačítkem „Kopírovat celý klíč“ a ulož na server, nikdy do kódu webu nebo mobilní aplikace.

2) Ověř přístup

Pošli GET https://doklad.ai/api/invoices?limit=5 s hlavičkou Authorization: Bearer dk_…. Seznam faktur i zákazníků vrací objekt { "data": [...], "total", "page", "totalPages" }. Chybějící nebo neplatný klíč vrátí 401.

3) Najdi nebo založ zákazníka

GET /api/customers?search=…&activeOnly=true hledá i části jména, e-mailu, IČO a DIČ, takže v data vyber přesnou shodu. Když zákazník neexistuje, založ ho přes POST /api/customers (povinné je jen name) a jeho id si ulož.

4) Vystav fakturu

{
  "customerId": 4821,
  "customerName": "Jana Nováková",
  "issueDate": "2026-10-06",
  "taxDate": "2026-10-06",
  "dueDate": "2026-10-20",
  "subtotal": "1000.00",
  "vatAmount": "210.00",
  "total": "1210.00",
  "items": [
    { "description": "Konzultace", "quantity": "1", "unit": "ks", "unitPrice": "1000.00", "vatRate": "21" }
  ]
}
  • Částky, množství a sazby posílej jako text s desetinnou tečkou, data jako RRRR-MM-DD.
  • customerName je povinné i s customerId.
  • unitPrice je cena bez DPH. U plátce DPH server součty nepřepočítává, musíš je poslat, jinak má faktura nulovou částku. Neplátci je dopočítá sám.
  • Číslo faktury neposílej, přidělí ho číselná řada firmy. Odpověď 201 vrací id a invoiceNumber.
  • Na zkoušku pošli "status": "draft". Vznikne koncept bez čísla, který jde smazat.

5) Zapiš úhradu a pošli fakturu

POST /api/invoices/{id}/payments s amount a paidAt. Plná úhrada přepne fakturu na Uhrazena a zákazník s e-mailem dostane „Potvrzení platby“. Fakturu s PDF pošleš přes POST /api/invoices/{id}/email. U zaplacené faktury přidej vlastní customMessage, výchozí text vyzývá k úhradě.

Webhooky: když má tvoje aplikace reagovat sama

V Nastavení → Integrace → „API klíče a webhooky“ klikni na „Nový webhook“, zadej „Endpoint URL“ (jen https, veřejný server, port 443), vyber události a klikni na „Vytvořit“. Secret začínající whsec_ se zobrazí jen jednou.

UdálostKdy odejde
invoice.createdfaktura z formuláře v aplikaci, přes REST API nebo MCP
invoice.paidzměna stavu na Uhrazena nebo úplná úhrada automaticky spárovanou platbou z banky
invoice.overduejen ruční změna stavu na Po splatnosti
customer.createdzákazník založený v adresáři, přes API nebo MCP
  • Podpis v hlavičce X-Webhook-Signature je HMAC-SHA256 nezměněného těla, klíčem je celý secret, výsledek v šestnáctkovém zápisu.
  • Za úspěch se počítá odpověď 2xx do 10 sekund. Po neúspěchu přijdou ještě dva pokusy, zhruba po minutě a po pěti minutách.
  • Pořadí událostí není zaručené. Opakované doručení poznáš podle stejné hlavičky X-Webhook-Delivery.
  • Úhrada zapsaná přes /payments událost invoice.paid nespustí. Adresu ani události existujícího webhooku nezměníš, vytvoř nový.

Duplicity bez klíče idempotence

  • K platbě nebo objednávce si ve své aplikaci ukládej id faktury a vytvářej ji jen jednou. Souběh ošetři zámkem nebo unikátním omezením v databázi.
  • Po timeoutu nejdřív ověř, jestli faktura nevznikla: GET /api/invoices?customerId=…&dateFrom=…&dateTo=….
  • Má-li zákazník do 7 dnů jiný doklad stejného typu na stejnou částku, odpověď nese duplicateWarning a hlavičku X-Duplicate-Warning. Faktura ale vznikne. Hlídá se to jen u požadavků s customerId a nenulovým total.

Limity a chyby

  • 400 chybný vstup (u validace VALIDATION_ERROR a pole errors s path a message), 401 neplatný klíč, 403 nepovolená oblast, 404 nenalezeno, 429 překročený limit e-mailů, 503 nedostupný kurz ČNB u cizí měny.
  • E-maily: nejvýš 10 za minutu, 100 za hodinu a 500 za den. ARES bez klíče 30 požadavků za minutu z jedné IP.
  • Jiný limit počtu požadavků REST API teď neuplatňuje. Stránkování page a limit (výchozí 50).

Kdy API a kdy něco jiného

PotřebaŘešení v Doklad.ai
Faktura automaticky z vlastní aplikaceREST API
Reakce tvé aplikace na zaplaceníwebhooky
E-shop na Shoptetu nebo WooCommercehotová integrace bez programování
Pravidelná faktura se stejnou částkouopakované faktury
Podklady pro účetníexport Pohoda XML, Money S3 XML, ISDOC, CSV
Práce s fakturami z AI aplikace (Claude, ChatGPT)MCP server

Dokumentace

Na kartě „API klíče a webhooky“ jsou záložky „Dokumentace“ a „Swagger“, veřejně je OpenAPI na doklad.ai/api/docs. Swagger se v detailech od skutečnosti liší: u položek uvádí čísla (server chce text), DUZP je pole taxDate, PSČ postalCode, filtry jsou dateFrom a dateTo a zapsaná platba vrací 201. Záložka „Dokumentace“ uvádí limit 100 požadavků za minutu, který server neuplatňuje.

Časté otázky

Má Doklad.ai sandbox pro testování API?

Ne. Klíč pracuje s ostrými daty firmy. Na zkoušku vytvářej faktury jako koncept ("status": "draft"), který nemá číslo a jde smazat.

Umí API párovat platby z banky?

Ne. Platby z banky páruje aplikace sama z e-mailových oznámení banky nebo z Fio API. Přes API úhradu jen zapíšeš. O automaticky spárované úplné úhradě se tvoje aplikace dozví z webhooku invoice.paid.

Co když pošlu požadavek na vytvoření faktury dvakrát?

Vzniknou dvě faktury, klíč idempotence API nemá. Ukládej si id vytvořené faktury, po timeoutu nejdřív ověř seznam faktur zákazníka a sleduj pole duplicateWarning.

Máte SDK nebo Postman kolekci?

Ne. API voláš přímo přes HTTP a strojově čitelný popis najdeš na doklad.ai/api/docs.json.

Jak ověřím, že webhook poslal Doklad.ai?

Spočítej HMAC-SHA256 z těla požadavku tak, jak přišlo, s klíčem rovným celému secretu včetně whsec_, a porovnej ho s hlavičkou X-Webhook-Signature. Adresa webhooku musí být veřejná a na https.

← Všechny články