API pro vývojáře

Veřejné REST API EUFactura (tarif Scale) umožňuje vašim vlastním nástrojům — CRM, e-shopu, vlastnímu skriptu — vytvářet zákazníky, připravovat a vystavovat faktury a nabídky, evidovat platby a dostávat upozornění na klíčové události prostřednictvím webhooků. Každý endpoint využívá naprosto stejnou logiku jako samotná aplikace EUFactura, takže se přes API nic nechová jinak než v uživatelském rozhraní.

Úplná dokumentace

Kompletní API je popsáno jako specifikace OpenAPI 3.1 — importujte ji přímo do Postmanu, Insomnie nebo jakéhokoli nástroje podporujícího OpenAPI.

Ověřování

Klíč vytvořte na stránce Nastavení → Vývojáři vaší organizace (pouze vlastník/správce). Každý klíč je vázán na jednu organizaci a nese roli — member (čtení a zápis) nebo accountant (pouze čtení). Úplný tajný klíč se zobrazí pouze jednou při vytvoření; uložte si jej bezpečně.

curl https://app.eufactura.eu/api/v1/customers?companyId=<company-id> \
  -H "Authorization: Bearer eufk_..."

Vytvoření zákazníka a vystavení faktury

curl -X POST https://app.eufactura.eu/api/v1/customers \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "<company-id>",
    "type": "business",
    "legalName": "Acme GmbH",
    "countryCode": "DE"
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a UUID you generate>" \
  -d '{
    "companyId": "<company-id>",
    "customerId": "<customer-id>",
    "currency": "EUR",
    "issueDate": "2026-01-01",
    "lines": [{ "description": "Consulting", "quantity": "1", "unitPriceNet": "500" }]
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices/<invoice-id>/issue \
  -H "Authorization: Bearer eufk_..."

Faktury se vždy vytvářejí jako koncepty a vystavují se jako samostatný, explicitní krok — vystavením se přidělí zákonné číslo faktury a faktura se stane neměnnou, stejně jako v samotné aplikaci.

Idempotence

U požadavku, který mění data, odešlete hlavičku Idempotency-Key (libovolný vámi vygenerovaný řetězec, obvykle UUID). Opakování stejného požadavku se stejným klíčem vrátí původní odpověď namísto opětovného provedení akce — bezpečné vůči síťovým opakováním a dvojím kliknutím.

Omezení četnosti požadavků

Požadavky jsou omezeny na jeden klíč API. Odpověď při překročení limitu vrátí 429 s polem Retry-After, jehož ekvivalentem je pole retryAfter v těle chyby.

Chyby

Každá chyba se vrací jako {"error": {"code": "...", "message": "..."}}. ID zdroje patřícího jiné organizaci vždy vrátí 404, nikdy 403 — EUFactura nikdy nepotvrdí existenci zdroje dříve, než potvrdí, že k němu máte přístup.

Webhooky

Zaregistrujte URL koncového bodu a v Nastavení → Vývojáři vyberte, které události chcete přijímat: invoice.issued, invoice.payment_recorded, quote.converted a credit_note.issued. Každé doručení je podepsaný HTTPS POST požadavek:

POST <your endpoint>
Content-Type: application/json
X-EUFactura-Signature: t=1700000000,v1=<hex-encoded HMAC-SHA256>

{"id": "...", "type": "invoice.issued", "data": { ... }}

Ověřte jej výpočtem HMAC-SHA256 z časového razítka, doslovné tečky a syrového těla požadavku pomocí tajného klíče vašeho koncového bodu a porovnáním výsledku s hodnotou v1 — stejný formát t=...,v1=..., jaký pro své webhooky používá i Stripe, takže jakýkoli existující kód pro ověřování webhooků Stripe je dobrým výchozím bodem. Doručení se při selhání opakují s prodlevami (až pětkrát v průběhu přibližně 12 hodin); váš koncový bod by měl být idempotentní vůči id obsahu.

Dotazy

Kontaktujte nás na hello@eufactura.eu.