REST API a webhooky

REST API je součástí tarifu PROFI. V nižších tarifech odpoví chybou 403 s vysvětlením. Klíč a webhooky spravuje administrátor v Nastavení → API a Webhooky.

Co API umí

• Vypsat a vytvořit klienty v adresáři.
• Vypsat faktury, vytvořit novou fakturu s položkami (PDF se vygeneruje samo) a načíst detail faktury.
• Stornovat fakturu (PDF dostane štítek STORNO a do historie se zapíše událost).
• Stáhnout PDF faktury.

Kompletní popis všech volání a možnost si je vyzkoušet najdete po přihlášení na app.fakturace26.cz/api/docs/.

Autentizace

Každý požadavek posílá klíč v hlavičce Authorization: Token <váš-API-klíč>. Klíč si administrátor vygeneruje v nastavení a celý ho uvidí jen jednou – ukládáme pouze jeho otisk. Při ztrátě nebo podezření na únik vygenerujte nový, původní okamžitě přestane platit.

Webhooky

Místo opakovaného dotazování vám pošleme zprávu sami. Zadejte adresu (musí začínat https://) a uložte – vygeneruje se podpisový klíč, který uvidíte celý jen jednou. Tlačítkem Odeslat testovací zprávu ověříte, že vše funguje.

• invoice.created – faktura (i zálohová nebo opravný doklad) byla vystavena,
• invoice.paid – faktura je uhrazená (spárovanou platbou nebo ručně),
• invoice.cancelled – faktura byla stornována,
• webhook.test – testovací zpráva z nastavení.

Zprávu posíláme jako POST s JSON a hlavičkami X-Fakturace26-Event (typ události), X-Fakturace26-Delivery (jedinečné ID) a X-Fakturace26-Signature (podpis).

{
  "id": "6f1c0e3a-5b7d-4c2e-9a41-0d8e2b7c9f10",
  "type": "invoice.paid",
  "created": "2026-10-08T14:44:12+02:00",
  "organization": {"id": 12, "tax_id": "12345678"},
  "data": {
    "invoice": {
      "id": 4821, "number": "20260042", "type": "STANDARD", "variable_symbol": "20260042",
      "date_issued": "2026-10-01", "date_taxable": "2026-10-01", "date_due": "2026-10-15",
      "currency": "CZK", "total_net": "1000.00", "total_vat": "210.00", "total_gross": "1210.00",
      "amount_paid": "1210.00", "is_paid": true, "is_cancelled": false,
      "client": {"id": 77, "name": "Odběratel s.r.o.", "tax_id": "87654321", "vat_id": null, "email": "info@odberatel.cz"},
      "items": [{"description": "Služba", "quantity": "1.00", "unit_price_net": "1000.00", "vat_rate": 21}],
      "api_url": "https://app.fakturace26.cz/api/v1/invoices/4821/"
    }
  }
}

Ověření podpisu

Hlavička má tvar t=1791470652,v1=5f2b…. Spočítejte HMAC-SHA256 z řetězce <t>.<tělo požadavku> vaším podpisovým klíčem a porovnejte s v1. Zprávy starší než 5 minut odmítněte.

# Python
import hashlib, hmac, time

def overit(telo: bytes, hlavicka: str, klic: str) -> bool:
    casti = dict(c.split("=", 1) for c in hlavicka.split(","))
    if abs(time.time() - int(casti["t"])) > 300:
        return False
    ocekavany = hmac.new(klic.encode(), f"{casti['t']}.".encode() + telo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(ocekavany, casti["v1"])

// PHP
function overit(string $telo, string $hlavicka, string $klic): bool {
    parse_str(str_replace(',', '&', $hlavicka), $c);
    if (abs(time() - (int)$c['t']) > 300) return false;
    $ocekavany = hash_hmac('sha256', $c['t'] . '.' . $telo, $klic);
    return hash_equals($ocekavany, $c['v1']);
}
// $telo = file_get_contents('php://input');
// $hlavicka = $_SERVER['HTTP_X_FAKTURACE26_SIGNATURE'];

Doručení a opakování

• Zpráva je doručená, když váš server odpoví kódem 2xx do 10 sekund. Odpovězte hned a zpracování udělejte až potom.
• Jinak to zkusíme znovu po 1 min, 5 min, 30 min, 2 h, 6 h a 24 h. Stejná zpráva může dorazit vícekrát – použijte její id.
• Přehled posledních zpráv a jejich výsledek najdete v nastavení, nedoručenou zprávu tam pošlete znovu.
• Přesměrování (3xx) nesledujeme a posíláme jen na veřejné adresy.