API reference

Základní informace

Base URL (produkce)	https://api.fakturos.cz/v1
Base URL (sandbox)	https://sandbox.api.fakturos.cz/v1
Formát	JSON (request i response)
Autentizace	API klíč (Bearer) nebo OAuth 2.0
Rate limit	1 000 requestů / hodinu (Business), 10 000 (Accounting Partner)
Aktuální verze	v1 · stabilní

Autentizace

FakturOS API podporuje dva způsoby autentizace.

API klíč (Bearer)

Vhodný pro skripty, integrace, vlastní backend. Klíč vygenerujete v Klientská zóna → Nastavení → API → + Nový klíč. Pošlete ho v hlavičce:

cURLcurl https://api.fakturos.cz/v1/invoices \
  -H "Authorization: Bearer fos_live_xK9p…q2Ws"

OAuth 2.0

Vhodný pro vícestranné aplikace (např. e-shop platforma, kde každý obchodník má svůj FakturOS účet). Standardní flow Authorization Code s PKCE. Detaily v sekci OAuth níže.

Hlavní endpointy

Faktury

• GET /v1/invoices — seznam, podporuje ?from=2026-01-01&to=2026-12-31&status=paid&limit=50&cursor=…
• GET /v1/invoices/:id — detail vč. URL k PDF a ISDOC
• POST /v1/invoices — vystavit fakturu
• PUT /v1/invoices/:id/pay — označit za uhrazenou
• DEL /v1/invoices/:id — stornovat

POST /v1/invoices — parametry

Parametr	Typ	Popis
firm_id required	string	ID firmy, za kterou fakturu vystavujete.
client	object	Klient (name, ico, dic, email, …). Když existuje, stačí client_id.
items required	array	Pole položek (label, qty, price, vat_rate).
type	enum	invoice · proforma · credit_note. Výchozí invoice.
currency	string	ISO kód (CZK, EUR, USD…). Výchozí CZK.
due_days	integer	Splatnost ve dnech. Výchozí 14.
recurring	enum	monthly · quarterly · yearly. Pravidelná fakturace.
webhook	url	URL pro callback po vystavení.

JSONPOST /v1/invoices
{
  "firm_id": "acme_sro",
  "client": {
    "name": "Nordic Studio s.r.o.",
    "ico": "12345678"
  },
  "items": [
    { "label": "Webdesign", "qty": 40, "price": 1000, "vat_rate": 21 }
  ],
  "due_days": 14,
  "webhook": "https://acme.cz/hooks/invoice"
}

→ 201 Created
{
  "id": "inv_2026_0118",
  "number": "2026-0118",
  "pdf_url": "https://files.fakturos.cz/.../faktura.pdf",
  "isdoc_url": "https://files.fakturos.cz/.../faktura.isdoc",
  "total": 48400,
  "status": "issued"
}

Sklad

• GET /v1/stock/items
• POST /v1/stock/items
• POST /v1/stock/movements
• GET /v1/stock/levels/:sku

Klienti, náklady, exporty

• GET /v1/clients, POST /v1/clients, …
• GET /v1/expenses, POST /v1/expenses, POST /v1/expenses/ocr
• POST /v1/exports, GET /v1/exports/:id
• GET /v1/ares/:ico — načtení údajů z ARES

Idempotence

Všechny POST endpointy podporují idempotency key. Pošlete jednoznačný klíč v hlavičce a FakturOS zaručí, že každý klíč zpracuje jen jednou:

Idempotency-Key: order_2026_4827

Klíč si pamatujeme 24 hodin. Doporučujeme použít unikátní ID objednávky / transakce z vašeho systému.

Webhooky

FakturOS pošle POST na vaši URL ve chvíli, kdy se stane sledovaná událost. Endpoint musí vrátit HTTP 2xx do 10 vteřin — jinak FakturOS opakuje s exponenciálním backoff (až 6× během 24 hodin).

Dostupné události

• invoice.issued — faktura vystavena
• invoice.paid — faktura uhrazena
• invoice.overdue — faktura po splatnosti
• expense.created — nový náklad
• stock.low — sklad pod limitem
• user.invited — pozvaný uživatel přijal pozvánku

Ověření podpisu

Každý webhook obsahuje hlavičku X-Fakturos-Signature s HMAC-SHA256 podpisem těla. Vždy ho ověřujte:

Node.jsconst crypto = require('crypto');

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rate limity

Každá odpověď obsahuje hlavičky:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset:     1763890000

Při překročení limitu dostanete 429 Too Many Requests s hlavičkou Retry-After v sekundách.

Chybové kódy

Kód	Význam	Akce
400	Špatný požadavek	Zkontrolujte tělo, neopakujte stejně.
401	Neautorizováno	Špatný / vypršený token.
403	Bez oprávnění	Token nemá scope na tuto akci.
404	Nenalezeno	Zdroj neexistuje, nebo na něj nemáte přístup.
409	Konflikt	Idempotency klíč už použit pro jiný požadavek.
422	Validace selhala	Detail v errors v těle odpovědi.
429	Příliš mnoho požadavků	Počkejte podle Retry-After.
5xx	Naše chyba	Retry s exponenciálním backoff.

SDK

• JavaScript / Node.js — npm install @fakturos/sdk
• PHP — composer require fakturos/sdk
• Python — komunitní SDK
• Pro ostatní jazyky stáhněte OpenAPI 3.1 spec a vygenerujte si klienta.