Fakturák

Propojte Fakturák se svým systémem.

REST API a webhooky pro automatizaci fakturace. Jeden API klíč zpřístupňuje právě jednu firmu a vyžaduje aktivní placený tarif.

Klíč vytvoří vlastník firmy

V Nastavení → Integrace vytvoříte API klíč pro čtení nebo čtení a zápis. Celý klíč se zobrazí pouze při vytvoření. Uložte si jej bezpečně. Klíč lze zrušit nebo nahradit novým.

Stejné doklady jako v aplikaci

API pracuje se stejnými kontakty a fakturačním jádrem jako aplikace. Umí vytvářet a upravovat kontakty i doklady, vystavovat je, posílat e-mailem, přidávat úhrady a připravovat PDF či ISDOC.

Webhooks místo opakovaného dotazování

Podepsané události informují váš systém o změnách dokladů, úhradách a připraveném PDF. Přijímač ověří podpis, vrátí úspěšnou odpověď a zpracování události zajistí idempotentně. Doručení se při chybě opakuje.

Verzované rozhraní

Základní adresa je https://api.fakturak.cz/v1. Rozhraní vrací JSON a veřejné identifikátory UUID. Úplné struktury požadavků, odpovědí a stavových kódů najdete ve specifikaci OpenAPI níže.

První požadavek

curl https://api.fakturak.cz/v1/me \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Požadavky se změnou dat vyžadují Idempotency-Key. Klíč ani webhookové tajemství nedávejte do veřejného JavaScriptu.

Odpovědi a asynchronní úlohy

200 a 201 znamenají úspěšné dokončení; 202 přijetí úlohy na pozadí. U PDF nebo odesílání sledujte stav úlohy a respektujte Retry-After. 401 značí neplatný klíč, 403 chybějící oprávnění nebo tarif, 404 nenalezený zdroj, 409 konflikt, 422 chybný vstup a 429 překročený limit. Úplný kontrakt každé operace je ve specifikaci.

Stáhnout specifikaci OpenAPI ↓

Endpointy REST API v1

GET /v1/meIdentita firmy a scope klíče

GET /v1/companyÚdaje napojené firmy

GET /v1/bank-accountsAktivní bankovní účty

GET /v1/number-seriesAktivní číselné řady

GET /v1/contactsSeznam se stránkováním data + meta; sestupně podle pořadí vytvoření.

POST /v1/contactsVytvoření contacts

GET /v1/contacts/{id}Detail contacts

PATCH /v1/contacts/{id}Částečná aktualizace podle stejných pravidel jako app.

GET /v1/invoicesSeznam se stránkováním data + meta; sestupně podle pořadí vytvoření.

POST /v1/invoicesVytvoření invoices

GET /v1/invoices/{id}Detail invoices

PATCH /v1/invoices/{id}Částečná aktualizace podle stejných pravidel jako app.

POST /v1/invoices/{id}/issueVystavení konceptu

POST /v1/invoices/{id}/cancelStorno vystaveného dokladu

POST /v1/invoices/{id}/sendZařazení asynchronní úlohy pro e-mail s PDF a ISDOC

POST /v1/invoices/{id}/paymentsEvidence příchozí úhrady; plná úhrada neplátcovy zálohovky vytvoří navazující fakturu.

GET /v1/invoices/preview-numberNezávazný náhled čísla/VS, bez rezervace.

GET /v1/invoices/{id}/pdfStažení PDF

GET /v1/invoices/{id}/isdocStažení ISDOC

GET /v1/jobs/{id}Stav PDF/e-mailové úlohy, e-mail pending/processing/sent/failed/cancelled podle fronty.

POST /v1/jobs/{id}/retryZnovu spustit neúspěšnou úlohu; neaktuální PDF se obnoví novým GET dokladu.

GET /v1/webhooksSeznam konfigurací bez podpisového tajemství.

POST /v1/webhooksVytvořit webhook; platný entitlement webhooks a nejvýše5konfigurací na firmu.

GET /v1/webhooks/{id}Detail konfigurace bez tajemství.

PATCH /v1/webhooks/{id}Změnit konfiguraci; stará čekající doručení se zruší.

DELETE /v1/webhooks/{id}Smazat konfiguraci a zrušit čekající doručení.

POST /v1/webhooks/{id}/rotate-secretRotace podpisového tajemství s kontrolou verze.

POST /v1/webhooks/{id}/testZařadit syntetickou testovací událost.

GET /v1/webhooks/{id}/deliveriesStránkovaná historie doručení bez citlivých odpovědí příjemce.

POST /v1/webhook-deliveries/{id}/retryRuční opakování selhaného doručení aktuální aktivní konfigurace.