Fakturace přes API: napojte fakturaci na vlastní systém

Vystavujete pořád stejné faktury z jiného systému — e-shopu, rezervačního kalendáře nebo vlastní aplikace? Fakturujsi.cz má veřejné REST API, přes které můžete faktury, kontakty, náklady i produkty číst a zakládat programově. Napojíte si fakturaci na svůj systém, na automatizační nástroj jako Zapier nebo Make, nebo si taháte data do vlastního reportovacího dashboardu. V tomto návodu projdeme, jak získat API klíč, jak API funguje a co všechno přes něj jde.

K čemu je API dobré

API (rozhraní pro programový přístup) se hodí všude, kde fakturu nechcete klikat ručně, protože podnět k ní vzniká jinde:

• E-shop nebo vlastní aplikace — po přijetí objednávky váš systém sám zavolá API a založí fakturu, místo aby ji někdo přepisoval.
• Automatizace přes Zapier / Make — propojíte Fakturujsi.cz s dalšími službami bez psaní kódu (nová objednávka v jiné appce → faktura).
• Reporting a BI — taháte si tržby, náklady nebo pohledávky po splatnosti do vlastního dashboardu (Power BI, Looker, Metabase) z reportovacích endpointů.
• Synchronizace kontaktů — udržujete adresář odběratelů shodný s CRM, které už používáte.

Pokud nechcete programovat vůbec a stačí vám faktury zadávat větou v chatu, mrkněte radši na propojení s Claude a ChatGPT přes MCP — k tomu se vrátíme na konci.

Jak získat API klíč

API klíč je jako heslo pro váš systém — dokazuje, že požadavek patří vaší organizaci. Vytvoříte ho v Nastavení → Integrace → API klíče. Vytvářet a mazat klíče může vlastník nebo administrátor organizace.

1. Klikněte na vytvořit klíč a pojmenujte ho (ať víte, kterému systému patří — třeba „E-shop“).
2. Vyberte oprávnění (scopes) — co přesně klíč smí. Dejte mu jen to, co opravdu potřebuje (viz níže).
3. Volitelně nastavte datum expirace. Po něm klíč přestane fungovat.
4. Po vytvoření se jednou zobrazí celý klíč začínající na fak_. Zkopírujte si ho hned — aplikace si ukládá jen jeho otisk (SHA-256), ne klíč samotný, takže později už ho znovu neukáže. V seznamu uvidíte jen zkrácenou předponu.

Když klíč unikne nebo ho přestanete potřebovat, v seznamu ho zneplatníte (revoke) nebo smažete — od té chvíle každý požadavek s ním dostane chybu 401. Vytvoření API klíče je placená funkce; jestli ji váš tarif má, zjistíte v ceníku.

Oprávnění (scopes): klíč dostane jen to, co potřebuje

Každý klíč nese seznam oprávnění ve tvaru zdroj:akce. Endpoint, na který klíč nemá odpovídající scope, vrátí chybu 403 (Missing required scope). Klíč pro reporting tak klidně nedostane právo zápisu faktur. Dostupná oprávnění:

• invoices:read / invoices:write — faktury (čtení / zápis)
• contacts:read / contacts:write — kontakty
• expenses:read / expenses:write — náklady
• products:read / products:write — produkty
• payments:read / payments:write — platby
• webhooks:read / webhooks:write — webhooky
• bank:read — bankovní účty a transakce (pouze čtení)
• reports:read — finanční reporty (pouze čtení)
• mcp:connect — připojení přes MCP

Jak API funguje

Všechny endpointy žijí pod /api/v1/ a klíč se posílá v hlavičce Authorization. Nejrychlejší způsob, jak ověřit, že klíč funguje, je testovací endpoint GET /api/v1/auth/test — vrátí název vaší organizace, tarif a seznam oprávnění klíče:

curl https://www.fakturujsi.cz/api/v1/auth/test \
  -H "Authorization: Bearer fak_vas_klic"

Odpovědi jsou JSON. Úspěch má data pod klíčem data, seznamy navíc nesou pagination (stránkování). Chyba přijde jako objekt error s polem code a message. Běžné stavy: 401 (chybí nebo neplatí klíč), 403 (klíč nemá potřebný scope), 404 (záznam jiné organizace nebo neexistuje), 429 (překročený limit požadavků).

Co přes API jde

Endpointy jsou rozdělené podle zdroje. U faktur, kontaktů, nákladů, produktů a plateb umí API číst i zakládat; banka a reporty jsou jen pro čtení:

• Faktury — seznam s filtry (stav, typ, odběratel, období, hledání), detail, založení nové faktury i stažení PDF.
• Kontakty, náklady, produkty, platby — seznam, detail a zakládání nových záznamů.
• Banka (čtení) — bankovní účty a transakce s filtry podle účtu, období a směru platby.
• Reporty (čtení) — tržby (volitelně po dnech/týdnech/měsících), náklady podle kategorie a pohledávky po splatnosti s aging rozpadem.
• Webhooky — registrace adres, na které vám API samo pošle upozornění, když se něco stane (viz dál).

Čtecí endpointy banky a reportů záměrně nevracejí citlivé údaje — třeba celé číslo účtu, interní propojení na účetní zápis ani surová data z banky. Z každého požadavku navíc vidíte jen záznamy své organizace; cizí data přes API neproteknou.

Praktický příklad: e-shop založí fakturu

curl -X POST https://www.fakturujsi.cz/api/v1/invoices \
  -H "Authorization: Bearer fak_vas_klic" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "0e2b1c7a-...",
    "issueDate": "2026-10-15",
    "dueDate": "2026-10-29",
    "items": [
      {
        "description": "Objednavka #2026-1042",
        "quantity": 1,
        "unitPrice": 1290,
        "taxRate": 21
      }
    ]
  }'

Čísla na faktuře se neřeší na straně vašeho systému — o číslování se stará Fakturujsi.cz (jak, popisujeme v návodu číslování faktur a číselné řady).

Webhooky: ať se vám systém ozve sám

Místo abyste API každou chvíli ptali „už je zaplaceno?“, zaregistrujete webhook — adresu, na kterou vám Fakturujsi.cz pošle zprávu, jakmile nastane vybraná událost. Vybíráte si, o čem chcete vědět: založení, úprava, odeslání, zaplacení nebo po splatnosti u faktury (invoice.paid, invoice.sent a další), stejně tak události u kontaktů, nákladů, produktů a plateb.

Při registraci webhooku dostanete tajný klíč (začíná na whsec_), kterým si na své straně ověříte, že zpráva opravdu přišla od Fakturujsi.cz. Typické využití: událost invoice.paid rovnou odblokuje objednávku v e-shopu nebo zapíše platbu do vašeho systému.

Limity a bezpečnost

• Limit požadavků: API je chráněné limitem počtu požadavků za minutu (u tarifů s API přístupem 1 000 požadavků za minutu). Při překročení vrátí stav 429 a hlavičku Retry-After — počkejte uvedený počet sekund a zkuste to znovu.
• Klíč = heslo: ukládejte ho na serveru, nikdy ho nedávejte do veřejného kódu (frontend, repozitář). Když unikne, hned ho zneplatněte a vytvořte nový.
• Nejmenší nutná oprávnění: klíči dejte jen ty scopes, které jeho systém potřebuje. Na reporting stačí čtení.
• Komunikace přes HTTPS: API běží výhradně přes šifrované spojení.

Časté dotazy

Jak se API klíč posílá v požadavku?

V hlavičce Authorization: Bearer fak_…. Klíč musí být aktivní, nezneplatněný a nesmí mít prošlou expiraci, jinak endpoint vrátí 401. Rychle si funkčnost ověříte na GET /api/v1/auth/test.

Ztratil jsem klíč, ukáže se znovu?

Ne. Celý klíč se zobrazí jen jednou, při vytvoření — aplikace si ukládá pouze jeho otisk, ne klíč samotný. Když si ho nezkopírujete, nezbývá než starý zneplatnit a vytvořit nový.

Můžu přes API jen číst data a nic nezapisovat?

Ano. Klíči přidělte jen scopes končící na :read (a banka s reporty ani jiné než čtení neumí). Takový klíč fakturu nezaloží ani neupraví — ideální pro reporting a dashboardy.

Vidí klíč data jiných organizací?

Ne. Každý klíč je svázaný s jednou organizací a všechny dotazy jsou omezené na její data. Požadavek na záznam jiné organizace vrátí 404.

Kde najdu seznam všech endpointů?

V interaktivní dokumentaci na /docs/api, kde je u každého endpointu příklad volání i ukázka odpovědi. K dispozici je i strojově čitelný popis (OpenAPI) na /api/v1/openapi.json.