API – centrální fakturace

Poslední aktualizace: 27. 5. 2026 · verze 1

FakturID poskytuje jednoduché REST API pro vytvoření faktury vydané přímo z jiné aplikace. Slouží jako centrální fakturační bod – vaše aplikace (e-shop, rezervační systém, předplatné…) odešle proběhlou platbu a FakturID založí odpovídající fakturu, přidělí jí číslo z jednotné řady a vrátí odkaz na PDF.

Toto API je určené pro serverovou integraci. Přístupový token vydává provozovatel služby – není samoobslužný. Postup získání najdete v sekci Získání přístupu.

Jak to funguje

Faktura se zakládá pod účtem provozovatele FakturID, takže všechny aplikace ekosystému sdílejí jednu společnou číselnou řadu. Původ každé faktury se eviduje v poli source_app, takže lze kdykoli dohledat, která aplikace fakturu vytvořila.

Jedna řada, žádné kolize. Číslo faktury se přiděluje atomicky (podmíněný posun sekvence + pojistka přes UNIQUE index), takže dvě souběžné integrace nikdy nedostanou stejné číslo.
Evidence původu. Každá aplikace má vlastní token, který se mapuje na source_app. Token lze samostatně odvolat, aniž by to ovlivnilo ostatní aplikace.
Faktura jako uhrazená. Endpoint je navržen pro účtování již proběhlých plateb – faktura vzniká rovnou ve stavu uhrazeno s datem úhrady k aktuálnímu dni.

Autentizace

Každý požadavek musí obsahovat HTTP hlavičku s přístupovým tokenem aplikace:

X-Fakturid-Token: VAS_TOKEN

Token se na serveru porovnává v konstantním čase (hash_equals), takže není zranitelný vůči časovým útokům.
Per-app token automaticky určí hodnotu source_app – tu pak v těle požadavku není potřeba posílat.
Pro zpětnou kompatibilitu existuje i sdílený (legacy) token; při jeho použití se source_app přebírá z těla požadavku.
Při neplatném nebo chybějícím tokenu vrací API 403 forbidden.

Token je tajný klíč. Ukládejte jej výhradně na straně serveru, nikdy ne do klientského kódu (prohlížeč, mobilní aplikace) ani do verzovacího systému. Komunikujte vždy přes HTTPS.

Endpoint

POST https://fakturid.cz/api/external_invoice.php

Tělo požadavku se odesílá jako JSON s hlavičkou Content-Type: application/json. Endpoint přijímá pouze metodu POST.

Struktura požadavku

Kořenový objekt JSON:

Pole	Typ	Povinné	Popis
`item`	object	ano	Fakturovaná položka. Aktuálně jedna položka na fakturu (viz tabulka níže).
`customer`	object	ne	Údaje odběratele (viz tabulka níže).
`currency`	string	ne	Měna faktury. Povolené hodnoty: `CZK`, `EUR`, `USD`. Výchozí `CZK` (neznámá hodnota se převede na CZK).
`external_ref`	string	doporučeno	Vaše jednoznačná reference platby či objednávky. Spolu se `source_app` zajišťuje idempotenci (viz níže).
`source_app`	string	podmíněně	Identifikátor zdrojové aplikace. U per-app tokenu se doplní automaticky; nutné pouze při použití sdíleného (legacy) tokenu.
`note`	string	ne	Poznámka zobrazená na faktuře.

Objekt item:

Pole	Typ	Povinné	Popis
`unit_price`	number	ano	Cena za jednotku. Musí být > 0. Při `vat_rate` > 0 je chápána jako cena včetně DPH, při `vat_rate` = 0 jako základ daně.
`quantity`	number	ano	Množství. Musí být > 0. Výchozí `1`.
`vat_rate`	int	ne	Sazba DPH v procentech. Výchozí `21`. Hodnota `0` = bez DPH / přenesená daňová povinnost.
`description`	string	ne	Popis položky. Výchozí „Předplatné".

Objekt customer (všechna pole volitelná):

Pole	Typ	Popis
`name`	string	Název firmy nebo jméno odběratele.
`ico`	string	IČO.
`dic`	string	DIČ.
`street`	string	Ulice a číslo popisné.
`city`	string	Město.
`zip`	string	PSČ.
`country_code`	string	Kód země (ISO). Výchozí `CZ`.
`email`	string	E-mail odběratele.

Výpočet DPH

Způsob výpočtu řídí pole vat_rate v položce:

vat_rate > 0 (např. 21): unit_price je cena včetně DPH. Systém z brutto částky rozpočítá základ daně i samotnou DPH. Základ se počítá jako cena / (1 + sazba/100).
vat_rate = 0: režim bez DPH (např. přenesená daňová povinnost). unit_price je rovnou základem, DPH je 0.

Částky se zaokrouhlují na 2 desetinná místa.

Idempotence

Pokud odešlete požadavek se stejnou kombinací source_app + external_ref, jaká už v systému existuje, nevznikne duplicitní faktura – API vrátí již existující fakturu a do odpovědi přidá příznak "duplicate": true.

Vždy posílejte stabilní external_ref (např. ID objednávky). Bezpečně tak ošetříte opakované odeslání po timeoutu nebo výpadku sítě, aniž byste riskovali dvojí fakturaci.

Struktura odpovědi

Při úspěchu vrací API stavový kód 200 a JSON:

{
    "ok": true,
    "invoice_id": "1287",
    "number": "2026042",
    "pdf_url": "https://fakturid.cz/api/invoice_pdf.php?id=1287"
}

Pole	Typ	Popis
`ok`	bool	`true` při úspěchu.
`invoice_id`	string	Interní ID faktury ve FakturID.
`number`	string	Přidělené číslo faktury z číselné řady provozovatele.
`pdf_url`	string	Odkaz na PDF faktury. Bez podpisu vyžaduje přihlášení – veřejný odkaz viz sekce Veřejné odkazy na PDF.
`duplicate`	bool	Přítomno a `true` pouze u idempotentního zásahu (vrácena existující faktura).

Návratové kódy a chyby

Při chybě vrací API odpovídající HTTP kód a JSON ve tvaru { "ok": false, "error": "..." }.

HTTP	`error`	Význam a řešení
403	`forbidden`	Chybný nebo chybějící token. Zkontrolujte hlavičku `X-Fakturid-Token`.
400	`bad_request`	Neplatné JSON tělo nebo chybí objekt `item`. Ověřte `Content-Type` a strukturu těla.
400	`invalid_amount`	`quantity` nebo `unit_price` je ≤ 0. Zadejte kladné množství i cenu.
500	`owner_not_found`	Účet provozovatele nenalezen (chyba konfigurace serveru). Kontaktujte provozovatele.
500	`subject_not_found`	Profil provozovatele nenalezen (chyba konfigurace serveru). Kontaktujte provozovatele.
500	`sequence_contention`	Nepodařilo se přidělit číslo z řady kvůli souběhu (přechodný stav). Požadavek zopakujte.
500	`insert_failed`	Chyba při zápisu do databáze. Zopakujte; pokud přetrvává, kontaktujte provozovatele.

Veřejné odkazy na PDF

Pole pdf_url z odpovědi míří na invoice_pdf.php, které ve výchozím stavu vyžaduje přihlášení. Pro veřejně přístupný odkaz (např. do e-mailu zákazníkovi) připojte podpis t – HMAC-SHA256 z ID faktury podepsané tokenem vaší aplikace:

GET https://fakturid.cz/api/invoice_pdf.php?id=1287&t=PODPIS

Podpis: t = hash_hmac('sha256', (string) id, VAS_TOKEN).
Platí pouze pro tu jednu fakturu, jejíž id bylo podepsáno – nelze jej zneužít k zobrazení jiných faktur.
Volitelně &download=1 vynutí stažení souboru místo zobrazení v prohlížeči.

Příklady

cURL

curl -X POST https://fakturid.cz/api/external_invoice.php \
  -H "Content-Type: application/json" \
  -H "X-Fakturid-Token: VAS_TOKEN" \
  -d '{
    "currency": "CZK",
    "external_ref": "ORDER-2026-00042",
    "note": "Předplatné PRO – květen 2026",
    "customer": {
      "name": "Jan Novák",
      "ico": "12345678",
      "email": "jan@example.cz",
      "country_code": "CZ"
    },
    "item": {
      "description": "Předplatné PRO (1 měsíc)",
      "quantity": 1,
      "unit_price": 119,
      "vat_rate": 21
    }
  }'

PHP (cURL)

<?php
$token   = 'VAS_TOKEN';
$payload = [
    'currency'     => 'CZK',
    'external_ref' => 'ORDER-2026-00042',
    'note'         => 'Předplatné PRO – květen 2026',
    'customer'     => [
        'name'         => 'Jan Novák',
        'ico'          => '12345678',
        'email'        => 'jan@example.cz',
        'country_code' => 'CZ',
    ],
    'item' => [
        'description' => 'Předplatné PRO (1 měsíc)',
        'quantity'    => 1,
        'unit_price'  => 119,   // cena za jednotku včetně DPH
        'vat_rate'    => 21,
    ],
];

$ch = curl_init('https://fakturid.cz/api/external_invoice.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Fakturid-Token: ' . $token,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
$status   = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
if ($status === 200 && !empty($data['ok'])) {
    // $data['invoice_id'], $data['number'], $data['pdf_url']
}

Veřejný odkaz na PDF (PHP)

<?php
$invoiceId = 1287;
$token     = 'VAS_TOKEN';                       // stejný token aplikace
$sig       = hash_hmac('sha256', (string) $invoiceId, $token);
$publicUrl = "https://fakturid.cz/api/invoice_pdf.php?id={$invoiceId}&t={$sig}";

Limity a doporučení

Jedna položka na fakturu. Endpoint aktuálně vytváří fakturu s jednou položkou.
Měny. Podporované jsou CZK, EUR a USD.
Stav faktury. Faktura vzniká jako uhrazená (datum úhrady = den vytvoření). Endpoint je určen pro účtování již proběhlých plateb.
Číselná řada. Všechny aplikace sdílejí jednu řadu provozovatele; čísla se přidělují atomicky bez kolizí.
Počet požadavků. Služba aktuálně neuplatňuje pevný limit, využívejte API uvážlivě a opakované požadavky ošetřete přes external_ref. Provozovatel může limity v budoucnu zavést.

Získání přístupu

Přístupové tokeny vydává administrátor služby ve správě API tokenů. Token lze přiřadit konkrétnímu uživateli – faktury z něj pak vznikají v účtu a číselné řadě toho uživatele; bez přiřazení se faktury zakládají centrálně pod účtem provozovatele. Každý token má vlastní source_app a lze ho kdykoli samostatně zneplatnit.

O vydání tokenu, přiřazení uživateli nebo nahlášení problému s integrací napište na bachurek@gmail.com – uveďte název aplikace a stručný popis použití.