API dla programistów

Publiczne API REST EUFactura (plan Scale) pozwala Twoim własnym narzędziom — CRM-owi, sklepowi e-commerce, własnemu skryptowi — tworzyć klientów, przygotowywać i wystawiać faktury oraz oferty, rejestrować płatności i otrzymywać powiadomienia o kluczowych zdarzeniach za pomocą webhooków. Każdy endpoint korzysta dokładnie z tej samej logiki, co sama aplikacja EUFactura, więc nic nie zachowuje się inaczej przez API niż w interfejsie użytkownika.

Pełna dokumentacja

Pełne API jest opisane jako specyfikacja OpenAPI 3.1 — zaimportuj ją bezpośrednio do Postmana, Insomnii lub dowolnego narzędzia obsługującego OpenAPI.

Uwierzytelnianie

Utwórz klucz na stronie Ustawienia → Programiści swojej organizacji (tylko właściciel/administrator). Każdy klucz jest przypisany do jednej organizacji i posiada rolę — member (odczyt i zapis) lub accountant (tylko odczyt). Pełny sekret jest wyświetlany tylko raz podczas tworzenia; przechowuj go w bezpiecznym miejscu.

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

Tworzenie klienta i wystawianie 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 są zawsze tworzone jako wersje robocze i wystawiane jako osobny, wyraźny krok — wystawienie przypisuje ustawowy numer faktury i czyni fakturę niezmienną, zgodnie z działaniem samej aplikacji.

Idempotencja

W przypadku żądania modyfikującego dane wyślij nagłówek Idempotency-Key (dowolny wygenerowany przez Ciebie ciąg znaków, zazwyczaj UUID). Ponowienie tego samego żądania z tym samym kluczem zwraca oryginalną odpowiedź zamiast wykonywania działania po raz drugi — bezpieczne w przypadku ponownych prób sieciowych i podwójnych kliknięć.

Limity liczby żądań

Żądania są ograniczane dla każdego klucza API. Odpowiedź po przekroczeniu limitu zwraca 429 z polem Retry-After, którego odpowiednikiem jest pole retryAfter w treści błędu.

Błędy

Każdy błąd jest zwracany jako {"error": {"code": "...", "message": "..."}}. Identyfikator zasobu należącego do innej organizacji zawsze zwraca 404, nigdy 403 — EUFactura nigdy nie potwierdza istnienia zasobu, zanim nie potwierdzi, że masz do niego dostęp.

Webhooki

Zarejestruj adres URL punktu końcowego i wybierz, które zdarzenia chcesz otrzymywać, w Ustawienia → Programiści: invoice.issued, invoice.payment_recorded, quote.converted oraz credit_note.issued. Każda dostawa to podpisane żądanie POST HTTPS:

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

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

Zweryfikuj je, obliczając HMAC-SHA256 ze znacznika czasu, dosłownej kropki i surowej treści żądania przy użyciu sekretu Twojego punktu końcowego, a następnie porównując wynik z wartością v1 — ten sam format t=...,v1=..., którego Stripe używa dla własnych webhooków, więc każdy posiadany już kod weryfikacji webhooków Stripe jest dobrym punktem wyjścia. Dostawy są ponawiane z narastającym opóźnieniem w przypadku niepowodzenia (do pięciu prób w ciągu około 12 godzin); Twój punkt końcowy powinien być idempotentny względem id ładunku.

Pytania

Skontaktuj się z nami pod adresem hello@eufactura.eu.