Fakturnia Developers Szybki start Dokumentacja API English

Szybki start

Wystaw swoją pierwszą fakturę przez API Fakturnia w około pięć minut. Uzyskasz token dostępu, utworzysz nabywcę i fakturę w jednym wywołaniu oraz pobierzesz PDF.

Adres bazowy. API ma dwa środowiska. Endpointy w tej dokumentacji są względne wobec adresu bazowego wybranego środowiska:

  • Produkcja — https://prod.api.fakturnia.pl/external/v1 (faktury są prawdziwe i trafiają do KSeF ze skutkiem prawnym).
  • Środowisko testowe (sandbox) — https://sandbox.api.fakturnia.pl/external/v1 (do nauki i testów, bez skutków prawnych).

0. Zacznij od środowiska testowego (sandbox)

Zanim cokolwiek uruchomisz na produkcji, zacznij od sandboxa. To pełnoprawna, odizolowana kopia Fakturni, w której możesz testować integrację — łącznie z wysyłką faktur do KSeF — bez żadnych skutków prawnych ani podatkowych. Jest to szczególnie istotne, gdy Twój kod pisze (albo współtworzy) LLM: najpierw potwierdź, że wszystko działa w sandboxie, a dopiero potem przełącz się na produkcję.

  1. Załóż osobne konto w środowisku testowym pod adresem https://sandbox.app.fakturnia.pl. Konto produkcyjne nie działa w sandboxie — to dwa odrębne światy z osobnymi danymi.
  2. Wygeneruj sandboxowe dane API (Inne → Integracje → REST API) na tym koncie testowym. Otrzymasz client_id i client_secret, które działają wyłącznie wobec https://sandbox.api.fakturnia.pl.
  3. Podłącz testowy certyfikat KSeF. Aby przetestować wysyłkę do KSeF, potrzebujesz certyfikatu ze środowiska testowego KSeF, a nie produkcyjnego — certyfikat produkcyjny nie zadziała wobec https://sandbox.api.fakturnia.pl. Zaloguj się na testowy podmiot w portalu testowym Ministerstwa Finansów https://ap-test.ksef.mf.gov.pl/web/, wygeneruj certyfikat i podłącz go do swojego konta sandboxowego (Ustawienia → KSeF).

Gdy integracja działa w sandboxie, przełączenie na produkcję sprowadza się do zmiany adresu bazowego na https://prod.api.fakturnia.pl oraz użycia produkcyjnych danych API i produkcyjnego certyfikatu KSeF.

1. Uzyskaj dane uwierzytelniające API

REST API jest modułem planu MAX: konto, na którym tworzysz aplikację API, potrzebuje aktywnego planu MAX (nowe konto ma 14-dniowy okres próbny MAX, więc w sandboxie zaczniesz od razu). Bez planu endpoint tokenu odpowiada 403 access_denied.

Utwórz aplikację API na swoim koncie Fakturnia (Inne → Integracje → REST API). Otrzymasz client_id i client_secret oraz wybierzesz scope'y (zakresy uprawnień), z których aplikacja może korzystać (na przykład documents:create, documents:read).

Traktuj client_secret jak hasło. Nigdy nie umieszczaj go w przeglądarce, aplikacji mobilnej ani w publicznym repozytorium. Pracujesz z agentem AI? Wyklucz plik z sekretami z jego zasięgu, żeby nie trafił na zewnętrzne serwery.

2. Wymień dane uwierzytelniające na token dostępu

API korzysta z przepływu OAuth 2.0 client-credentials. Wymień swoje client_id / client_secret na krótkotrwały token typu bearer (JWT).

curl -s https://prod.api.fakturnia.pl/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "client_5c62e069...",
    "client_secret": "secret_..."
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:create documents:read clients:create"
}

Wysyłaj token w nagłówku Bearer przy każdym żądaniu:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...

Zobacz Uwierzytelnianie, aby poznać buforowanie tokenów, ich rotację oraz pełną listę scope'ów.

3. Utwórz swoją pierwszą fakturę

Nie musisz najpierw tworzyć nabywcy. Przekaż osadzony obiekt buyer, a Fakturnia odnajdzie lub utworzy kontrahenta za Ciebie. Sprzedawca jest zawsze pobierany z profilu Twojej firmy.

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f1d6e-0b2a-4a1e-9b1a-2a4e9b1a2a4e" \
  -d '{
    "documentType": "FakturaVAT",
    "issueDate": "2026-06-04",
    "buyer": {
      "nip": "5261040828",
      "name": "Acme Corp Sp. z o.o.",
      "street": "Marszałkowska 1",
      "postalCode": "00-001",
      "city": "Warszawa",
      "countryCode": "PL"
    },
    "products": [
      { "name": "Usługa programistyczna", "unitOfMeasure": "szt.", "quantity": 1, "netPrice": 100, "vatRate": 23 }
    ],
    "paymentMethodId": 6,
    "paymentStatusId": 1,
    "paymentDeadlineDate": "2026-06-18"
  }'

Każda odpowiedź jest opakowana w spójną kopertę:

{
  "success": true,
  "data": {
    "document": {
      "id": "681a3b2c4d5e6f7a8b9c0d1e",
      "documentNumber": "FV/1/06/2026",
      "documentType": "FakturaVAT",
      "grossSum": 123,
      "netSum": 100,
      "vatSum": 23,
      "products": [
        { "name": "Usługa programistyczna", "quantity": 1, "netPrice": 100, "netValue": 100, "amountOfVat": 23, "grossValue": 123, "vatRate": 23 }
      ]
    }
  },
  "message": "DOCUMENT_CREATED",
  "executionTime": 142
}

Ty przesyłasz ceny, a API wykonuje obliczenia. Przekaż netPrice lub grossPrice oraz vatRate; backend wyliczy netValue, amountOfVat i grossValue co do grosza. Dokładne reguły opisano w Typy dokumentów i kwoty.

Więcej szczegółów i porad znajdziesz w Tworzenie dokumentów: każde pole żądania, ustalanie nabywcy i odbiorcy, adnotacje oraz logika dla każdego typu dokumentu.

4. Pobierz PDF

curl -s -L https://prod.api.fakturnia.pl/external/v1/documents/681a3b2c4d5e6f7a8b9c0d1e/download \
  -H "Authorization: Bearer $TOKEN" -o invoice.pdf

5. (Opcjonalnie) Wyślij ją do KSeF

Jeśli Twoje konto ma skonfigurowane połączenie z KSeF, prześlij fakturę do Krajowego Systemu e‑Faktur:

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/documents/681a3b2c4d5e6f7a8b9c0d1e/send-to-ksef \
  -H "Authorization: Bearer $TOKEN"

Wywołanie od razu zwraca ksefNumber, gdy KSeF działa szybko, w przeciwnym razie status processing. Jak prawidłowo poczekać na wynik — seria odpytań, webhook document.sentToKSeF i limit zapytań — opisuje Wysyłka do KSeF.

Następne kroki