Rychlý start

Aktivujte si tarif Pro (API je Pro funkce).
V aplikaci jděte na Nastavení → API klíče → Vytvořit klíč.
Klíč si uložte hned — z bezpečnostních důvodů ho znovu nezobrazíme.
Pošlete POST na https://app.faktuo.cz/api/v1/pdf s hlavičkou Authorization: Bearer fkt_….

Endpoint

POST https://app.faktuo.cz/api/v1/pdf

Vrací binární PDF s Content-Type: application/pdf. Limit 50 požadavků za minutu na klíč.

Hlavičky

Hlavička	Hodnota
`Authorization`	`Bearer fkt_…`
`Content-Type`	`application/json`

Tělo požadavku (JSON)

Pole	Typ	Popis
`doc_type` *	string	`invoice`, `proforma`, `proforma_tax`, `quote` nebo `credit_note` — opravný doklad, viz Opravné doklady.
`template`	string	`classic` (výchozí), `minimal`, `monochrome`, `modern`, `elegant`. Pokud neuvedete, použije se šablona zvolená v Nastavení → Vzhled dokumentů.
`language`	string	`cs` (výchozí), `en`, `sk`, `de`. Ovlivňuje jen popisky a hlavičky na PDF — vlastní data (názvy, položky, poznámky) zůstávají v jazyce, ve kterém je pošlete.
`accent`	string	HEX barva motivu (např. `#76c4a5`). Některé šablony (Minimal, Monochrome) ji ignorují záměrně.
`currency`	string	ISO kód měny (CZK, EUR, USD…). Výchozí `CZK`.
`doc_number`	string	Číslo dokladu (např. `FA-26-04-001`). Pokud neuvedete, vygeneruje se automaticky — ale pro účetní celistvost je vhodné posílat vlastní řadu z vašeho systému.
`variable_symbol`	string	VS pro platbu. Výchozí: číslice z `doc_number`.
`issue_date`	string (ISO date)	Datum vystavení (`YYYY-MM-DD`). Výchozí: dnes.
`due_date`	string (ISO date)	Datum splatnosti. Výchozí: `issue_date` + 14 dní.
`duzp`	string (ISO date)	Datum uskutečnění zdanitelného plnění. Výchozí: `issue_date`.
`vat_enabled`	boolean	Plátce DPH (true/false).
`vat_rate`	number	Výchozí sazba DPH v %, pokud položka nemá vlastní. Default 21.
`reverse_charge`	boolean	Přenesená daňová povinnost (§ 92a ZDPH).
`payment_method`	string	`prevodem`, `hotove` nebo `kartou`. Default `prevodem`.
`proforma_pct`	number	Procento zálohy (jen pro `proforma` a `proforma_tax`). 0–100.
`corrects`	object	Odkaz na opravovaný doklad. Povinné pro `doc_type: credit_note`; u ostatních typů vrátíme 422, aby se odkaz nikdy tiše nezahodil. Viz tabulka níže.
`supplier` *	object	Dodavatel. Viz tabulka níže.
`customer`	object	Odběratel. Viz tabulka níže.
`items` *	array	Položky dokladu (1–200). Viz tabulka níže.
`notes`	string	Volný text v patičce dokladu (max. 4 000 znaků).
`qr`	boolean	Pokud `true`, na PDF se vykreslí QR platba (SPAYD) — vyžaduje vyplněný `supplier.bank`. Bez vlivu na nepoplatkové doklady (cenová nabídka, daňový doklad k záloze bez požadavku na úhradu). S `doc_type: credit_note` nelze kombinovat (422). Zda se QR skutečně vykreslilo, poznáte z hlavičky `X-Faktuo-QR`. Default `false`.

Pole označená * jsou povinná.

`supplier` (dodavatel)

Pole	Typ	Popis
`name` *	string	Název firmy / OSVČ.
`street`, `city`, `zip`	string	Adresa.
`ico`, `dic`	string	IČO + DIČ.
`bank`	string	Číslo účtu (formát `123-4567/0100` nebo IBAN).
`bic`	string	BIC / SWIFT (volitelné).
`phone`, `email`	string	Pro patičku.
`is_vat_payer`	boolean	Plátce DPH.
`entity_type`	string	`firma` nebo `osvc`. Ovlivňuje text v patičce.
`court`	string	Spisová značka (firma) nebo evidující úřad (OSVČ).

`customer` (odběratel)

Pole	Typ	Popis
`name`	string	Název.
`street`, `city`, `zip`	string	Adresa.
`ico`, `dic`	string	IČO + DIČ.
`email`, `phone`	string	Volitelné.
`country_code`	string	ISO 3166-1 alpha-2 (např. `CZ`, `SK`, `DE`).

`items[]` (položky)

Pole	Typ	Popis
`name` *	string	Popis položky.
`quantity`	number	Množství.
`unit`	string	Jednotka (`ks`, `h`, `kg`, …).
`price`	number	Cena za jednotku (bez DPH).
`total`	number	Celkem za položku (bez DPH). Pokud neuvedete, dopočítáme jako `quantity × price`.
`vat_rate`	number	Sazba DPH v % (jen pro tuto položku). Pokud neuvedete, použije se globální `vat_rate`.

`corrects` (opravovaný doklad)

Pole	Typ	Popis
`doc_number` *	string	Číslo původní faktury přesně tak, jak je na ní vytištěné (např. `FA-26-04-001`). Vytiskne se do hlavičky opravného dokladu. Max. 50 znaků.
`issue_date`	string (ISO date)	Datum vystavení původní faktury (`YYYY-MM-DD`). Doplní se za číslo dokladu jako „ze dne …“.
`reason`	string	Důvod opravy, volný text (např. „Odstoupení od smlouvy do 14 dnů“). Vytiskne se pod odkazem na původní doklad. Max. 500 znaků.

Opravné doklady (`credit_note`)

Jedno volání = jeden opravný doklad k jedné původní faktuře. Typický případ: zákazník odstoupí od smlouvy, peníze jste už vrátili přes platební bránu a potřebujete k tomu doklad, který původní fakturu ruší.

Jak se doklad jmenuje

Název na PDF se řídí polem supplier.is_vat_payer, ne polem vat_enabled:

`supplier.is_vat_payer`	Nadpis dokladu (cs)
`true`	OPRAVNÝ DAŇOVÝ DOKLAD — režim § 45 ZDPH
`false`	STORNO FAKTURA — běžný opravný účetní doklad, bez daňových náležitostí

Obojí je plně podporované; neplátcovská větev není žádná odbočka, sdílí stejnou šablonu i stejné testy. V language en / sk / de se nadpis přeloží (Credit note / Cancelled invoice, Gutschrift / Stornorechnung …).

Znaménko: posílejte kladné částky

Položky posílejte s kladnými částkami — stejně jako na původní faktuře. Že jde o vratku, vyjádří doklad sám: součet je označený jako „Celkem k vrácení“ místo „Celkem k úhradě“. Záporné price nebo total odmítneme s 422 — dvě strany, které se neshodnou na znaménku, jsou nejrychlejší cesta k tomu, aby vratka odešla jako platba.

Částečná oprava

Souhrn opravného dokladu s ničím neporovnáváme — nemáme původní fakturu u sebe (viz Bez stavu níže). Pošlete jen ty položky a částky, které skutečně vracíte. Vratka části faktury je stejně platný vstup jako vratka celá.

Doklad nevypadá jako výzva k platbě

Na opravném dokladu se nevytiskne QR platba, číslo účtu, variabilní symbol ani datum splatnosti. Peníze už jsou zpátky u zákazníka a doklad, který znovu žádá o platbu, je horší než žádný.

Pole due_date a qr: true proto s credit_note zkombinovat nejde — vrátíme 422. Raději chyba než doklad, kterému jste rozuměli jinak než my.

Číslo dokladu si přidělujete sami

doc_number je pro credit_note povinné a bereme ho tak, jak dorazí — žádnou vlastní řadu vám nepodsuneme. Aplikace Faktuo interně používá konvenci OD-RR-MM-NNN (např. OD-26-08-014) v řadě oddělené od faktur; můžete se jí držet, ale nic nevynucujeme.

Bez stavu

Jako u zbytku endpointu: nic neukládáme, nic nečíslujeme, nic nenavazujeme na projekt ve vašem účtu. corrects.doc_number je řetězec, který vytiskneme — neověřujeme, že taková faktura existuje. Volání je tím pádem idempotentní v praktickém smyslu: stejný požadavek vrátí stejné PDF a opakování po timeoutu nic nerozbije.

Příklad — vratka celé faktury (neplátce DPH)

curl -X POST https://app.faktuo.cz/api/v1/pdf \
  -H "Authorization: Bearer fkt_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -o storno.pdf \
  -d '{
    "doc_type": "credit_note",
    "doc_number": "OD-26-08-014",
    "issue_date": "2026-08-14",
    "language": "cs",
    "currency": "CZK",
    "vat_enabled": false,
    "corrects": {
      "doc_number": "FA-26-08-231",
      "issue_date": "2026-08-03",
      "reason": "Odstoupení od smlouvy do 14 dnů"
    },
    "supplier": {
      "name": "Vaše firma s.r.o.",
      "ico": "12345678",
      "is_vat_payer": false,
      "entity_type": "firma"
    },
    "customer": {
      "name": "Jan Novák",
      "country_code": "CZ"
    },
    "items": [
      {
        "name": "Roční předplatné",
        "quantity": 1,
        "unit": "ks",
        "price": 2400,
        "total": 2400
      }
    ]
  }'

Částka 2400 je kladná záměrně. Na PDF se vytiskne jako Celkem k vrácení 2 400 Kč.

Příklad volání (curl)

curl -X POST https://app.faktuo.cz/api/v1/pdf \
  -H "Authorization: Bearer fkt_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -o faktura.pdf \
  -d '{
    "doc_type": "invoice",
    "template": "modern",
    "language": "cs",
    "doc_number": "FA-26-04-001",
    "issue_date": "2026-04-27",
    "due_date": "2026-05-11",
    "vat_enabled": true,
    "vat_rate": 21,
    "currency": "CZK",
    "supplier": {
      "name": "Vaše firma s.r.o.",
      "street": "Vinohradská 23",
      "city": "Praha 2",
      "zip": "120 00",
      "ico": "12345678",
      "dic": "CZ12345678",
      "bank": "1234567890/0100",
      "is_vat_payer": true,
      "entity_type": "firma"
    },
    "customer": {
      "name": "Demo zákazník a.s.",
      "ico": "87654321",
      "dic": "CZ87654321",
      "country_code": "CZ"
    },
    "items": [
      {
        "name": "Konzultační hodina",
        "quantity": 8,
        "unit": "h",
        "price": 1500,
        "total": 12000
      }
    ],
    "notes": "Děkujeme za spolupráci."
  }'

Příklad (JavaScript / Node.js)

const res = await fetch('https://app.faktuo.cz/api/v1/pdf', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fkt_a1b2c3d4...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    doc_type: 'invoice',
    template: 'modern',
    language: 'en',
    supplier: { name: 'Your company', is_vat_payer: true, entity_type: 'firma' },
    customer: { name: 'Acme Corp.' },
    items: [{ name: 'Service', quantity: 1, price: 1000 }],
  }),
});
if (!res.ok) throw new Error('Failed: ' + res.status);
const pdfBlob = await res.blob();
// → save to disk, attach to email, …

Hlavičky odpovědi

Hlavička	Význam
`Content-Type`	`application/pdf` při úspěchu, `application/json` při chybě.
`Content-Disposition`	`inline; filename="<doc_number>.pdf"` (nepovolené znaky nahrazeny podtržítkem).
`X-RateLimit-Limit`	Vždy `50`. Limit na klíč a minutu.
`Retry-After`	Jen u 429. Počet sekund do dalšího pokusu.
`X-Faktuo-QR`	Stav QR platby na vygenerovaném PDF. Viz níže.

`X-Faktuo-QR` — proč na dokladu QR není

Generování QR platby může selhat, aniž by selhal celý požadavek — PDF dostanete tak jako tak. Aby se „QR selhalo“ nedalo splést s „QR jsem nechtěl“, posíláme na každé úspěšné odpovědi hlavičku X-Faktuo-QR:

Hodnota	Význam
`included`	QR se vykreslilo.
`off`	`qr` nebylo `true` — nic jsme negenerovali.
`skipped:doc-type`	Typ dokladu QR platbu nemá (`quote`).
`skipped:currency`	SPAYD podporuje jen CZK; u jiné měny QR záměrně vynecháváme, aby ho banka nepřečetla 1:1 ve špatné měně.
`skipped:no-bank`	`supplier.bank` je prázdné.
`failed:bank-format`	`supplier.bank` se nepodařilo přečíst jako české číslo účtu ani IBAN. Toto je chyba vstupu na vaší straně — účet zkontrolujte.
`failed:generator`	Chyba na naší straně při sestavení QR. Nahlaste nám ji.

Podporované formáty účtu: 123456789/0100, 19-123456789/0710 (s předčíslím) nebo IBAN CZ65 0800 0000 1920 0014 5399. Cokoli jiného skončí jako failed:bank-format.

Hlavička je čistě informativní a tělo odpovědi nemění. Doporučujeme ji logovat u každého volání — na hotovém PDF už zpětně nepoznáte, který z důvodů to byl.

Stavové kódy

Kód	Význam
200	OK — tělo odpovědi je PDF.
400	Tělo není JSON objekt, nebo chybí `doc_number` u typu, který ho vyžaduje (`invoice`, `proforma_tax`, `credit_note`).
401	Chybí nebo neplatný Bearer token.
402	Tarif Free — API je Pro funkce.
403	Klíč byl revokován.
405	Použijte POST.
413	Tělo větší než 256 KB.
422	Validace selhala. Tělo obsahuje `{ "error": "...", "field": "..." }`.
429	Překročen limit 50/min. Hlavička `Retry-After` uvádí počet sekund.
500/502/503	Něco se pokazilo na naší straně. Zkuste znovu za chvíli; opakované chyby nahlaste na [email protected].

Co API neumí (zatím)

Číst nebo měnit existující projekty (jen generování PDF).
Navázat opravný doklad na fakturu ve vašem účtu Faktuo. doc_type: credit_note vytvoří PDF, ale ne záznam ani stopu v Historii změn — na to je potřeba vystavit storno v aplikaci.
Vystavit příjmový doklad (receipt) — zatím jen přes aplikaci.
Embedovat ISDOC do PDF (pouze čistý PDF). ISDOC verze pro účetní stahujte v aplikaci přes Export pro účetní.

Bezpečnostní doporučení

Klíč nepřenášejte přes klientský JS — držte ho na serveru.
Mějte oddělený klíč pro testy a produkci. Při kompromitaci stačí revokovat tu jednu sadu.
Logujte si X-RateLimit-Limit hlavičku — pokud se blížíte k 50/min, zvažte vlastní fronta a retry.
Otevřete novou sadu klíčů, jakmile zaměstnanec, který klíč znal, odejde.

Otázky?

Pište na [email protected]. Odpovídáme obvykle do jednoho pracovního dne.

API dokumentace