# Fakturnia Developers

> Oficjalna dokumentacja deweloperska zewnętrznego API REST Fakturnia: uwierzytelnianie, fakturowanie, KSeF, webhooki, SDK 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

## 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:
- [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 dla poszczególnych pól 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ń w przeliczeniu na aplikację, aby zapewnić szybkość i równe traktowanie. Limity są najbardziej restrykcyjne dla kosztownych endpointów:
- [Paginacja](https://developers.fakturnia.pl/docs/pagination): Endpointy zwracające listy (`GET /documents`, `GET /clients`, `GET /products`) 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.
- [Webhooks](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. Zarejestruj endpoint HTTPS, weryfikuj podpis przy każdym dostarczeniu i szybko odpowiadaj kodem `2xx`.
- [SDK i biblioteki](https://developers.fakturnia.pl/docs/sdk): Oficjalny klient jest w pełni typowany i generowany z tej samej specyfikacji OpenAPI, która zasila tę witrynę, dzięki czemu kształty żądań i odpowiedzi nie mogą rozjechać się z API. Sprawia on, że nieprawidłowe ładunki stają się **niemożliwe do skompilowania**.
- [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.
- [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)