REST API v1

Napojte e-shop, CRM nebo vlastní skript: vystavení faktury, označení platby, odeslání e-mailem, adresář odběratelů a náklady. API je součástí tarifu Max.

Začátek

V aplikaci otevřete Nastavení → Účet → API a vytvořte klíč. Zobrazí se jen jednou – uložte si ho.
Každý požadavek posílejte s hlavičkou Authorization: Bearer fk_….
Adresa API: https://www.fakturou.cz/api/v1/. Data se posílají i vrací jako JSON v UTF-8.

curl https://www.fakturou.cz/api/v1/account \
  -H "Authorization: Bearer fk_vas_klic"

Limit je 120 požadavků za minutu na klíč (pak odpověď 429). Chyby vrací JSON {"error": "…", "details": […]} s kódem 400/401/402/404/422.

Doklady

GET/invoices – seznam (50 na stránku). Parametry: od, do (datum vystavení RRRR-MM-DD), status (invoice | proforma | credit_note | offer), paid (1/0), page.

GET/invoices/{id} – detail včetně položek. {id} je identifikátor dokladu (stejný jako ve veřejném odkazu /doklad/{id}), odpověď obsahuje i pdf_url. Pole tags (jen pro čtení) nese názvy štítků dokladu.

POST/invoices – vystaví fakturu v číselné řadě firmy (variabilní symbol = číslo dokladu). Odběratel se podle IČO najde v adresáři, jinak se založí.

curl -X POST https://www.fakturou.cz/api/v1/invoices \
  -H "Authorization: Bearer fk_vas_klic" -H "Content-Type: application/json" \
  -d '{
    "customer": {"name": "Odběratel s.r.o.", "ico": "12345678", "dic": "CZ12345678",
                 "street": "Hlavní 1", "city": "Praha", "zip": "11000", "email": "[email protected]"},
    "items": [
      {"description": "Grafický návrh", "quantity": 2, "unit": "hod", "unit_price": 800, "vat_rate": 21}
    ],
    "issue_date": "2026-10-12",
    "payment_method": "transfer",
    "currency": "CZK",
    "language": "cs",
    "order_number": "OBJ-1042",
    "note": "Děkujeme za objednávku."
  }'

Pole	Popis
`customer.name`*	název odběratele; dále `ico`, `dic`, `street`, `city`, `zip`, `email`
`items[]`*	`description`*, `quantity` (výchozí 1), `unit` (ks), `unit_price` (u plátce bez DPH), `vat_rate` 0 / 12 / 21 (jen plátce), `sku` nebo `catalog_item_id` – položka ceníku; se zapnutým skladem se zboží při vystavení odepíše
`issue_date`, `taxable_date`, `due_date`	RRRR-MM-DD; výchozí dnes, DUZP = vystavení, splatnost podle nastavení firmy
`payment_method`	transfer (výchozí) \| cash \| card
`currency`	CZK (výchozí) \| EUR – jen když má firma eura povolená
`vat_mode`	standard \| reverse_cz (přenesená DP) \| eu (dodání do EU) – jen plátce, u reverse_cz/eu je povinné `customer.dic`
`language`	cs \| cs_en \| en \| de – jazyk dokladu

POST/invoices/{id}/pay – označí doklad jako zaplacený. Tělo nepovinné: {"paid_at": "2026-10-15"}. U plateb hotově a kartou se tržba eviduje v EET stejně jako v aplikaci.

POST/invoices/{id}/send – zařadí doklad k odeslání e-mailem odběrateli (PDF v příloze).

Odběratelé

GET/customers?q= – adresář (hledání v názvu, IČO a e-mailu).

POST/customers – {"name": "…", "ico": "…", "dic": "…", "street": "…", "city": "…", "zip": "…", "email": "…", "phone": "…"}

Náklady

GET/expenses?od=&do= – přijaté doklady za období.

POST/expenses – zapíše přijatý doklad:

{"supplier": {"name": "Dodavatel a.s.", "ico": "87654321", "dic": "CZ87654321"},
 "document_number": "FV-2026-118", "description": "Nájem 10/2026", "category": "najem",
 "issue_date": "2026-10-01", "taxable_date": "2026-10-01", "due_date": "2026-10-14",
 "vat_mode": "standard", "vat": {"base_21": 10000, "vat_21": 2100},
 "paid_at": "2026-10-10"}

Neplátce posílá jen "total". Kategorie: material, sluzby, najem, energie, telefon, software, auto, cestovne, reklama, vybaveni, pojisteni, ostatni.

Webhooky

Místo opakovaného dotazování vám pošleme zprávu sami, když se něco stane. Webhook nastavíte v Nastavení → Účet → Webhooky: adresu (jen https://, veřejně dostupnou), události a dostanete tajný klíč pro ověření podpisu. Hodí se pro Make, Zapier, n8n i vlastní systém. Součást tarifu Max, nejvýše 5 webhooků.

Událost	Kdy	`data`
`invoice.created`	vystavená faktura, zálohová faktura nebo dobropis (koncept ne; z konceptu až při vystavení)	doklad jako v `GET /invoices/{id}` včetně `items`
`invoice.paid`	doklad označen jako uhrazený – ručně, přes API, importem plateb nebo spárováním platby z banky
`invoice.sent`	doklad odeslán odběrateli e-mailem
`invoice.overdue`	neuhrazená faktura se dostala po splatnost (jednou, první den po splatnosti)
`customer.created`	nový odběratel v adresáři	odběratel jako v `GET /customers`
`expense.created`	nový přijatý doklad v Nákladech	náklad jako v `GET /expenses`
`ping`	tlačítko „Poslat testovací událost“	`{"message": "…"}`

Požadavek je POST s tělem v JSON:

POST /vas-endpoint HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Fakturou-Event: invoice.paid
X-Fakturou-Delivery: whd_1842
X-Fakturou-Signature: t=1760870400,v1=5f2c…e91a

{"id": "evt_3f9a1c…", "type": "invoice.paid", "created_at": "2026-10-19T10:00:00+02:00",
 "data": {"id": "a8Kd2…", "number": "26100012", "type": "invoice", "total": 2420, "paid": true, "paid_at": "2026-10-19", …}}

Odpovězte kódem 2xx do 10 sekund (zpracování si klidně odložte). Přesměrování se nesleduje.
Při chybě nebo vypršení času to zkusíme znovu za 1 min, 10 min, 1 h, 6 h a 24 h. Pak doručení vzdáme; když webhook celý den nic nepřijal, vypneme ho a dáme vědět v aplikaci.
Stejná událost může výjimečně přijít dvakrát – podle id události (evt_…) si ji odfiltrujte.
Události posíláme průběžně plánovanou úlohou, ne v tutéž vteřinu, kdy nastaly.

Ověření podpisu

Hlavička X-Fakturou-Signature obsahuje čas t (Unix) a podpis v1 = HMAC-SHA256 tajným klíčem z řetězce <t>.<tělo požadavku> (přesně tak, jak přišlo – před parsováním JSON). Zprávy starší než 5 minut odmítněte.

<?php // PHP
$secret = 'whsec_…';
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_FAKTUROU_SIGNATURE'] ?? '';
if (!preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $sig, $m) || abs(time() - (int)$m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
// … zpracovat $event['type'] a $event['data']
http_response_code(204);

// Node.js (Express)
const crypto = require('crypto');
app.post('/fakturou', express.raw({ type: 'application/json' }), (req, res) => {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(req.get('X-Fakturou-Signature') || '');
  const expected = m && crypto.createHmac('sha256', process.env.FAKTUROU_SECRET)
    .update(m[1] + '.' + req.body.toString('utf8')).digest('hex');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300 ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]))) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  // … zpracovat event.type a event.data
  res.sendStatus(204);
});

Účet

GET/account – název, IČO, DIČ, plátcovství DPH, výchozí splatnost a povolené měny.

Fakturou.cz · API v1