Fakturační API

Základní URL

https://freebillgen.com/api/v1

Autentizace

Každý požadavek používá Bearer token. Vytvořte si ho v Nastavení → API klíče, přiřaďte mu potřebné rozsahy čtení/zápisu pro jednotlivé prostředky, nastavte volitelnou dobu platnosti a odesílejte ho s každým požadavkem:

Authorization: Bearer <your-api-key>

Požadavky jsou autentizovány vůči účtu, který klíč vytvořil, a kontrolovány vůči přiřazeným rozsahům. Token uchovávejte v tajnosti a zrušte ho, pokud dojde k jeho úniku nebo již není potřeba.

Co můžete dělat

• Načítat faktury, klienty, společnosti, platby a opakující se plány
• Vytvářet a aktualizovat je (API pro zápis - Pro)
• Stahovat sestavy DPH a přehledy stáří pohledávek jako JSON
• Načítat stejnou omezenou frontu dalších kroků používanou přehledovým panelem
• Načítat soubory e-faktur dodavatelů, které jste ručně nahráli do Doručené pošty (nejedná se o přijímací koncový bod Peppol/e-mailu)
• Stahovat obecná mapování OASIS UBL a UN/CEFACT CII ke kontrole (nevalidovaná podle profilu)
• Registrovat koncové body webhooků pro události faktur a plateb (Pro)
• Idempotency-Key u podporovaných operací zápisu - změněná data požadavku pod stejným klíčem vrátí 409
• Kurzorové stránkování prostřednictvím links.next, nastavitelné pomocí per_page (max. 100)
• Umožněte AI agentům číst libovolnou sdílenou fakturu - schema.org/Invoice JSON-LD, plus Accept: application/json nebo text/markdown na každém podepsaném odkazu pro sdílení
• MCP server bez autentizace, pouze pro čtení, na adrese https://freebillgen.com/api/mcp (get_invoice, verify_invoice) pro AI agenty

Konvence

Idempotence

U podporovaných volání pro vytvoření a akce odešlete jedinečný Idempotency-Key. Opakování identických dat požadavku přehraje původní úspěšnou odpověď; změněná data požadavku vrátí 409.

Stránkování

Uložené seznamy zdrojů jsou stránkovány kurzorem - sledujte links.next (nebo předejte ?cursor=...) a upravte ?per_page= (max 100). Omezený kanál akcí hlásí svůj limit a stav zkrácení.

Peněžní částky

Peněžní částky jsou přesné řetězce ve formátu JSON formátované podle měřítka měny dle ISO 4217, například "121.00" pro EUR nebo "500" pro JPY. Jednotkové ceny mohou zachovávat vyšší přesnost vstupních dat.

Identifikátory

Každý zdroj je adresován neprůhledným identifikátorem (id), nikdy sekvenčním číslem.

Příklad: výpis vašich faktur

curl https://freebillgen.com/api/v1/invoices \
  -H "Authorization: Bearer $FREEBILLGEN_API_KEY"

Otevřít úplnou interaktivní referenci API →

Otázky k API pro faktury

Je API pro faktury zdarma?

Ano - API pro čtení je součástí bezplatné úrovně bez jakýchkoli nákladů. API pro zápis a odchozí webhooks jsou součástí Lifetime Pro za 49 € včetně daně: jednorázová platba bez měsíčního poplatku nebo ročního obnovení.

Jak probíhá ověření?

Vytvořte Bearer token v Nastavení -> API klíče, přiřaďte mu rozsahy čtení/zápis pro jednotlivé zdroje a odešlete jej jako hlavičku Authorization: Bearer v každém požadavku. Klíče jsou vázány na váš účet a lze je zrušit nebo nechat vypršet.

Mohu vytvářet faktury programově?

Ano, prostřednictvím API pro zápis, které je součástí doplňku Pro. Vytváří stejné profesionální faktury jako webová aplikace, se sekvenčním číslováním a konfigurovatelným zpracováním DPH aplikovaným na straně serveru. API nezaručuje soulad s místními právními předpisy.

Jak zabráním vytvoření duplicitních faktur při opakovaném pokusu?

Při volání pro vytvoření odešlete jedinečný Idempotency-Key. Opakování identických dat požadavku s tímto klíčem vrátí původní výsledek. Opětovné použití klíče se změněnými daty požadavku vrátí chybu 409 namísto tichého přehrání jiné faktury.

Mohu číst přijaté faktury?

Ano, zdarma. GET /api/v1/inbox vypíše podporované soubory dodavatelů ve formátu UBL/CII, které jste ručně nahráli a FreeBillGen je zpracoval, přičemž originál je uchován pro účely auditu; GET /api/v1/inbox/{id} vrátí jeden z nich. Rozpoznání syntaxe není validace profilu a tyto koncové body nečiní z FreeBillGen koncový bod Peppol, vládní sítě ani příjmu e-mailů.

Může AI agent číst fakturu bez účtu?

Ano. Každá faktura, kterou sdílíte prostřednictvím podepsaného veřejného odkazu, je čitelná pro agenty na stejné adrese URL: stránka obsahuje vložený schema.org/Invoice JSON-LD a odeslání Accept: application/json vrátí strukturovanou fakturu (smluvní strany, položky, celkové částky, dlužnou částku, platební možnosti), zatímco Accept: text/markdown vrátí přehledný výstup s nízkým počtem tokenů. K dispozici je také server Model Context Protocol (MCP) bez nutnosti ověření a pouze pro čtení na adrese https://freebillgen.com/api/mcp s nástroji get_invoice a verify_invoice. Podpis odkazu slouží jako přístupový token. S celou adresou URL zacházejte jako s tajemstvím, protože kdokoli, kdo ji obdrží, může fakturu otevřít.