Fakturnia Developers Szybki start Dokumentacja API English

Narzędzia

API to zwykły REST + JSON z pełną specyfikacją OpenAPI 3, więc możesz pracować w dowolnym języku i narzędziu. Poniżej to, co przygotowaliśmy: kolekcja Postman, CLI do szybkich sprawdzeń i przepis na wygenerowanie typowanego klienta.

Specyfikacja OpenAPI

Kanoniczny kontrakt API to /openapi.json (wersje językowe: /openapi.pl.json, /openapi.en.json). Zawiera każdy endpoint, schematy żądań i odpowiedzi z przykładami, kody błędów, nagłówki i wymagane scope'y. Ta sama specyfikacja zasila dokumentację API i interaktywny Swagger.

Wygeneruj klienta w swoim języku

Wygeneruj klienta z OpenAPI, na przykład narzędziem openapi-generator:

# Python
openapi-generator generate \
  -i https://developers.fakturnia.pl/openapi.json \
  -g python -o ./fakturnia-python

# PHP, C#, Java, Go, TypeScript: zmień -g na php, csharp, java, go, typescript-fetch

Możesz też po prostu skorzystać bezpośrednio z fetch / requests. Zobacz Szybki start oraz dokumentację API, aby poznać dokładne kształty danych. Przy własnym kliencie pamiętaj o trzech rzeczach z przewodników: buforowaniu tokenu (Uwierzytelnianie), nagłówku Idempotency-Key przy zapisach (Idempotentność) i ponowieniach 429 po Retry-After (Limity zapytań).

Kolekcja Postman

Zaimportuj gotową kolekcję Postman: wszystkie endpointy pogrupowane według zasobów, z przykładowymi treściami żądań wziętymi wprost ze specyfikacji. Kolekcja zawiera żądanie Authentication → get access token, którego skrypt testowy zapisuje token do zmiennej kolekcji, dzięki czemu każde kolejne żądanie jest uwierzytelniane automatycznie.

Jak użyć:

  1. Zaimportuj https://developers.fakturnia.pl/fakturnia.postman_collection.json do Postmana.
  2. Ustaw zmienne kolekcji client_id oraz client_secret.
  3. Uruchom raz Authentication → get access token, a następnie wywołuj dowolny endpoint.
  4. Aby testować na sandboxie, zmień zmienne baseUrl i tokenUrl na ich odpowiedniki z sandbox.api.fakturnia.pl.

Wiersz poleceń: CLI fakturnia

Niewielka, bezzależnościowa nakładka powłoki na curl, która sama pobiera, buforuje i dołącza token bearer. Przydatna do szybkich sprawdzeń i skryptów.

curl -fsSL https://developers.fakturnia.pl/fakturnia.sh -o fakturnia && chmod +x fakturnia

export FAKTURNIA_CLIENT_ID=client_...
export FAKTURNIA_CLIENT_SECRET=secret_...
export FAKTURNIA_ENV=sandbox            # lub: production

./fakturnia GET  /documents/
./fakturnia POST /documents/ '{"documentType":"FakturaVAT","issueDate":"2026-06-10","buyer":{"identifierType":"nip","nip":"5261040828","name":"Acme Corp Sp. z o.o.","street":"Marszałkowska 1","postalCode":"00-001","city":"Warszawa","countryCode":"PL"},"products":[{"name":"Usługa","unitOfMeasure":"szt.","quantity":1,"netPrice":100,"vatRate":23}],"paymentMethodId":6,"paymentStatusId":1,"paymentDeadlineDate":"2026-06-24"}'

Domyślnie działa na sandboxie, na produkcję przełącz się świadomie. Wywołania POST/PUT/PATCH z treścią otrzymują automatyczny nagłówek Idempotency-Key.

Dla agentów AI

Plik /skill.md to przenośna instrukcja w formacie Agent Skills, a /llms-full.txt cały korpus dokumentacji w jednym pliku. Szczegóły na stronie Dla agentów i botów.

Asystent działający na koncie użytkownika łączy się przez serwer MCP: ChatGPT, Claude i Claude Code, Gemini, Mistral Vibe (dawniej Le Chat), Perplexity, GitHub Copilot, Cursor albo Windsurf. Zamiast konta API jest logowanie OAuth 2.1, narzędzia są ograniczone do uprawnień użytkownika, a faktury wystawia się w prowadzonej ścieżce z podglądem.