# Fakturnia Developers

> Oficjalna dokumentacja deweloperska zewnętrznego API REST Fakturnia: uwierzytelnianie, fakturowanie, KSeF, webhooki, MCP i maszynowo czytelna dokumentacja OpenAPI.

- Base URL: https://prod.api.fakturnia.pl/external/v1
- OpenAPI: https://developers.fakturnia.pl/openapi.json
- Full text: https://developers.fakturnia.pl/llms-full.txt
- Agent skill: https://developers.fakturnia.pl/skill.md
- Postman collection: https://developers.fakturnia.pl/fakturnia.postman_collection.json
- CLI (curl wrapper): https://developers.fakturnia.pl/fakturnia.sh
- MCP server (ChatGPT, Claude, Claude Code): https://prod.api.fakturnia.pl/mcp (docs: https://developers.fakturnia.pl/docs/mcp)

## Dokumentacja
- [Szybki start](https://developers.fakturnia.pl/docs/quickstart): 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.
- [Uwierzytelnianie](https://developers.fakturnia.pl/docs/authentication): API Fakturnia korzysta z uwierzytelniania w modelu **OAuth 2.0 client credentials**. Aplikacja wymienia parę `client_id` / `client_secret` na krótko żyjący **token Bearer** (JWT), a następnie dołącza ten token do każdego żądania.
- [Typy dokumentów i kwoty](https://developers.fakturnia.pl/docs/documents): To strona, którą warto przeczytać, zanim zaczniesz budować obsługę fakturowania. Wyjaśnia ona, **jakie typy dokumentów istnieją**, **co przesyłasz** oraz dokładnie **jak obliczane są kwoty**, co do grosza. Poprawne wyliczenia pieniężne to sedno sprawy, dlatego reguły są opisane precyzyjnie.
- [Tworzenie dokumentów](https://developers.fakturnia.pl/docs/creating-documents): To kompletny przewodnik po `POST /external/v1/documents`, jedynym endpoincie, którego potrzebujesz, aby wystawić fakturę, proformę, zaliczkę, rozliczenie, korektę lub zamówienie. Opisuje każde pole żądania, sposób ustalania stron transakcji, logikę zależną od typu dokumentu oraz adnotacje KSeF. Reguły obliczeń kwot i pełną mapę typów znajdziesz w [Typy dokumentów i kwoty](/docs/documents); tutaj skupiamy się na tym, **jak zbudować poprawne żądanie**.
- [Wysyłka faktur do KSeF](https://developers.fakturnia.pl/docs/ksef): Wystawienie faktury i wysłanie jej do KSeF (Krajowego Systemu e‑Faktur) to **dwa osobne kroki**. Najpierw tworzysz dokument, potem go wysyłasz. Nie ma jednego wywołania, które tworzy i wysyła naraz, i jest to celowe: dzięki temu możesz utworzyć, sprawdzić lub zwalidować dokument, zanim stanie się prawną e‑fakturą.
- [Korygowanie dokumentów](https://developers.fakturnia.pl/docs/correcting-documents): Korekty wystawiasz tym samym endpointem co inne dokumenty, `POST /external/v1/documents`, podając jeden z trzech typów:
- [Połączenie KSeF](https://developers.fakturnia.pl/docs/ksef-connection): Zanim wyślesz pierwszą fakturę do KSeF, konto musi mieć skonfigurowane połączenie: certyfikat, którym Fakturnia uwierzytelnia się w KSeF w imieniu Twojej firmy. Ta strona opisuje zarządzanie tym połączeniem przez API. Samą wysyłkę faktur opisuje [Wysyłka do KSeF](/docs/ksef).
- [Powiązania z zamówieniami](https://developers.fakturnia.pl/docs/external-references): Jeśli integrujesz Fakturnię ze sklepem lub innym systemem sprzedaży, możesz powiązać dokument z zamówieniem w Twoim systemie. Powiązanie jest widoczne w aplikacji i pozwala odróżnić dokumenty wystawione przez integrację od tych wystawionych ręcznie.
- [Kontrahenci](https://developers.fakturnia.pl/docs/clients): Kontrahent to nabywca lub odbiorca na Twoich dokumentach. API udostępnia pełny CRUD pod `/clients`, a przy [tworzeniu dokumentów](/docs/creating-documents) możesz wskazać kontrahenta po `id` zamiast przesyłać jego dane za każdym razem.
- [Produkty](https://developers.fakturnia.pl/docs/products): Produkty i usługi to katalog pozycji, z których korzystasz przy wystawianiu dokumentów. API udostępnia pełny CRUD pod `/products`.
- [Ustawienia](https://developers.fakturnia.pl/docs/settings): Endpoint `/settings` pozwala odczytać i zmienić ustawienia konta, które wpływają na dokumenty wystawiane przez API: format daty oraz numerację dokumentów.
- [Magazyn](https://developers.fakturnia.pl/docs/warehouse): Moduł magazynowy prowadzi stany towarów metodą księgi ruchów: stan produktu to suma przyjęć i wydań. Przez API zarządzasz magazynami, wystawiasz dokumenty magazynowe (WZ, PZ, PW, RW, MM), rejestrujesz korekty stanów, pobierasz raport stanów na dowolny dzień i wystawiasz dokumenty WZ do faktur sprzedaży.
- [Pracownicy i uprawnienia](https://developers.fakturnia.pl/docs/employees): Konto pracownicze to osobna tożsamość logowania (własny email i hasło), która pracuje na danych konta głównego. Właściciel nadaje pracownikowi uprawnienia z zamkniętego rejestru, np. tylko podgląd dokumentów albo pełne wystawianie faktur. Przez API możesz zautomatyzować zakładanie takich kont, np. przy wdrażaniu nowego pracownika w systemie HR.
- [Dokumenty cykliczne](https://developers.fakturnia.pl/docs/recurring-rules): Reguła cykliczna to szablon dokumentu połączony z harmonogramem. Raz skonfigurowana, sama wystawia faktury (tryb `AUTO`), przygotowuje szkice do akceptacji (`DRAFT`) albo tylko przypomina o wystawieniu (`REMINDER`). Przez API odczytasz stan reguł i historię generacji oraz wstrzymasz lub wznowisz regułę, np. gdy klient zrezygnuje z abonamentu w Twoim systemie.
- [Konta pocztowe](https://developers.fakturnia.pl/docs/email-accounts): Konto Fakturnia może wysyłać dokumenty e-mailem z własnej skrzynki właściciela zamiast z adresu systemowego. Skrzynki podłącza się w aplikacji (Inne → Konta pocztowe): SMTP z hasłem albo Gmail i Outlook przez OAuth. Przez API sprawdzisz, które skrzynki są podłączone i w jakim są stanie. To wszystko: **podłączanie, weryfikacja i edycja odbywają się wyłącznie w aplikacji**, bo wymagają hasła albo zgody OAuth, których integracja nie powinna przechowywać.
- [Historia i aktywność](https://developers.fakturnia.pl/docs/activity): Wszystko, co dzieje się na koncie, zostaje w dziennikach: kto wystawił dokument, kiedy poszedł mailem, czy KSeF go przyjął, kto oznaczył zapłatę, jakie ruchy przeszły przez magazyn, kiedy logował się pracownik. Przez API czytasz te dzienniki na cztery sposoby, w zależności od tego, o co pytasz.
- [Dane firmy po NIP](https://developers.fakturnia.pl/docs/company-lookup): Endpoint `/company/nip-lookup` pobiera dane polskiej firmy z rejestru GUS. Użyj go, żeby automatycznie uzupełnić dane [kontrahenta](/docs/clients) albo nabywcy przy [tworzeniu dokumentu](/docs/creating-documents), zamiast prosić użytkownika o ręczne przepisywanie.
- [Błędy](https://developers.fakturnia.pl/docs/errors): API używa standardowych kodów statusu HTTP oraz **spójnej koperty błędu**. Każdy błąd zawiera stabilny, czytelny maszynowo `message` (kod błędu) oraz, gdy ma to znaczenie, szczegóły w `errors`.
- [Słowniki](https://developers.fakturnia.pl/docs/dictionaries): Wszystkie wartości enumów potrzebne przy tworzeniu dokumentów zwraca jeden endpoint:
- [Limity zapytań](https://developers.fakturnia.pl/docs/rate-limits): API stosuje limity zapytań, aby zapewnić szybkość i równe traktowanie. Limity są liczone dla aplikacji (konta API), którą identyfikuje token, a nie dla adresu IP. Są najbardziej restrykcyjne dla kosztownych endpointów:
- [Kolejka renderowania PDF](https://developers.fakturnia.pl/docs/pdf-download-queue): `GET /documents/{id}/download` renderuje PDF faktury po stronie serwera. Renderowanie obciąża procesor, więc działa w niewielkiej puli wątków roboczych z ograniczoną kolejką. Pod dużym obciążeniem kolejka może się zapełnić. Gdy tak się stanie, API **nie** każe Ci czekać ani nie kończy żądania timeoutem. Odpowiada natychmiast kodem `429` z kodem błędu `WAIT_PDF_QUEUE`, informując, że należy ponowić zapytanie za chwilę.
- [Paginacja](https://developers.fakturnia.pl/docs/pagination): Endpointy zwracające listy (`GET /documents`, `GET /clients`, `GET /products`, `GET /recurring-rules`, `GET /recurring-rules/{id}/history`, `GET /webhooks/{id}/deliveries`, `GET /documents/{id}/history`, `GET /warehouse/movements`) są paginowane za pomocą parametrów zapytania:
- [Idempotentność](https://developers.fakturnia.pl/docs/idempotency): Wywołania sieciowe kończą się niepowodzeniem w niejednoznaczny sposób: żądanie przekracza limit czasu, ale czy dokument został utworzony? Klucze idempotentności pozwalają **bezpiecznie ponawiać** modyfikujące żądania bez tworzenia duplikatów.
- [Webhooki](https://developers.fakturnia.pl/docs/webhooks): Webhooki wysyłają zdarzenia na Twój serwer w momencie, gdy coś się wydarzy, dzięki czemu nie musisz odpytywać API. Rejestrujesz endpoint HTTPS, wybierasz zdarzenia, weryfikujesz podpis przy każdej dostawie i szybko odpowiadasz kodem `2xx`. Webhooki, jak całe REST API, wymagają planu MAX: zdarzenia są wysyłane tylko wtedy, gdy konto ma aktywny plan MAX i co najmniej jedną aktywną aplikację API.
- [Narzędzia](https://developers.fakturnia.pl/docs/tools): 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.
- [Dla agentów, botów i robotów indeksujących](https://developers.fakturnia.pl/docs/agents): Ta dokumentacja została zaprojektowana z myślą o **maszynowej czytelności w pierwszej kolejności**. Jeśli jesteś modelem LLM, autonomicznym agentem, robotem indeksującym lub generatorem kodu, wszystko, czego potrzebujesz, jest dostępne w ustrukturyzowanych, czytelnych formatach. Nigdy nie powinieneś analizować wyrenderowanego kodu HTML ani wykonywać JavaScriptu.
- [Serwer MCP: faktury z ChatGPT, Claude, Gemini i innych asystentów AI](https://developers.fakturnia.pl/docs/mcp): Fakturnia udostępnia serwer **MCP (Model Context Protocol)**, dzięki któremu asystent AI pracuje bezpośrednio na koncie użytkownika: wystawia faktury, sprawdza płatności, wyszukuje kontrahentów, odczytuje stany magazynowe i wysyła dokumenty do KSeF. Serwer działa z ChatGPT, Claude i Claude Code, Gemini, Mistral Vibe (dawniej Le Chat), Perplexity, GitHub Copilot, Cursor i Windsurf, a także z innymi klientami MCP i z własnym agentem. Użytkownik łączy asystenta w aplikacji jednym logowaniem (OAuth 2.1), a każda zmiana danych przechodzi przez podgląd i potwierdzenie w rozmowie.
- [Dziennik zmian](https://developers.fakturnia.pl/docs/changelog): API jest wersjonowane w ścieżce (`/external/v1`). Zmiany łamiące zgodność są wprowadzane w nowej wersji głównej; zmiany addytywne (nowe pola, nowe punkty końcowe, nowe parametry opcjonalne) są udostępniane w ramach `v1`. Nieznane pola odpowiedzi należy traktować jako zgodne w przód: pomijaj te, których nie rozpoznajesz.

## Materiały referencyjne
- [Dokumentacja API](https://developers.fakturnia.pl/api)
- [Specyfikacja OpenAPI](https://developers.fakturnia.pl/openapi.json)