API

Dzięki API programy firmy wymieniają dane same: faktura z KSeF trafia do księgowości, a zamówienie ze sklepu do magazynu, bez przepisywania. Przy wyborze wykonawcy i dostawcy oprogramowania zapytaj o klucze, limity i zmiany wersji.

Jak to działa?

1. Dostawca publikuje adres usługi i dokumentację. Wywołujesz go zwykle przez internet: wysyłasz zapytanie na adres z poleceniem (pobierz, dodaj, zmień), a dane idą w formacie JSON, czyli tekście o prostej, ustalonej budowie.
2. Program uwierzytelnia się kluczem API z ustawień konta albo tokenem dostępu, który dostaje po zalogowaniu i który jest ważny krótko.
3. Serwer odpowiada kodem (sukces, błąd po Twojej stronie, błąd po stronie serwera) i danymi.
4. Gdy zapytań jest za dużo, serwer zwraca kod 429. Program czeka tyle, ile podaje nagłówek Retry-After, i próbuje ponownie.
5. Dostawca czasem zmienia API i podaje to w numerze wersji oraz w historii zmian. Integracja musi to śledzić.

Klucz API czy token?

Klucz API to stały sekret, który obowiązuje do jego unieważnienia, więc ten, kto go zdobędzie, może go używać. Token dostępu jest krótkotrwały, a często ma też zakres uprawnień, na przykład tylko odczyt. Token KSeF jest czymś pośrednim: służy do zalogowania się, po czym program dostaje token dostępu ważny kilkanaście minut.

Przykład z praktyki

Program księgowy firmy pobiera faktury z KSeF przez API. Raz ustawia się w nim token z uprawnieniem do przeglądania faktur. Co jakiś czas program prosi KSeF o nowe faktury, zapisuje je w swojej bazie i dalej pracuje na tej kopii. Dzięki temu nikt nie pobiera faktur ręcznie z aplikacji Ministerstwa Finansów.

Kiedy ma sens, a kiedy nie?

API ma sens, gdy dwa programy mają wymieniać dane regularnie i bez człowieka albo gdy dane są potrzebne od razu, na zapytanie. Gdy chodzi o reakcję na zdarzenie, na przykład opłacone zamówienie, mniej zapytań zużyje webhook, czyli powiadomienie wysyłane przez dostawcę samo. Przy rzadkiej wymianie, na przykład raz w miesiącu, wystarczy eksport i import pliku. Różne sposoby łączenia programów opisujemy przy haśle integracja systemów.

Integracje przez API, także z narzędziami Microsoft 365, budujemy w ramach automatyzacji. Napisz, które programy mają wymieniać dane. Po krótkiej rozmowie dostaniesz plan prac i wycenę.

Opisz swoją integrację

Na co uważać?

Limity zapytań

Każdy dostawca ma własne limity. W KSeF lista faktur ma w dokumentacji limit 20 zapytań na godzinę dla pary NIP i adresu IP, a powtarzane przekroczenia mogą skończyć się blokadą. API Arkuszy Google dopuszcza 300 odczytów na minutę na projekt. Limity się zmieniają, więc zapytaj wykonawcę, jak program je liczy i co robi po błędzie 429.

Klucze to hasła

Klucz nie należy do kodu, repozytorium, arkusza ani maila. Trzymaj go w magazynie sekretów albo w zmiennych środowiskowych, a w razie wycieku wymień. Dla każdej integracji zrób osobny klucz, żeby dało się odciąć jedną bez psucia reszty. Google zaleca, żeby nie podawać klucza w adresie URL, bo łatwo wtedy o wyciek.

Wersje i zmiany

Dostawca może zmienić API. W KSeF między kwietniem a czerwcem 2026 na produkcję weszły 4 wydania API, a wycofanie pola authenticationMethod zaplanowano na 16.11.2026 (historia zmian). Zapytaj wykonawcę, kto śledzi te zmiany i kto poprawia integrację, gdy dostawca coś wycofa.

Pytania i odpowiedzi

Czym jest klucz API?

To stały sekret wydawany w ustawieniach konta, który program wysyła z każdym zapytaniem. Zwykły klucz nie potwierdza, kto pyta: wiąże zapytanie z projektem, do którego liczą się limity i rachunek (Google Cloud).

Co oznacza błąd 429 w programie?

Program wysłał za dużo zapytań w krótkim czasie i serwer go zatrzymał (RFC 6585). Odpowiedź ma często nagłówek Retry-After z liczbą sekund do odczekania. Program powinien poczekać, a nie ponawiać zapytania od razu.

Czy za korzystanie z API trzeba płacić?

Zależy od dostawcy. Część interfejsów jest w cenie licencji albo bezpłatna, część rozlicza się za użycie. Zapytaj dostawcę o model rozliczenia i limity, zanim wykonawca zbuduje na nim integrację.

Zobacz też

• Webhook
• Integracja systemów
• Token KSeF

Artykuły, w których pojawia się to pojęcie

• Skrzynka e-Doręczeń w firmie: kto ją odbiera i gdzie trafia pismo
• Jak podłączyć KSeF do własnych narzędzi: token, certyfikat, API
• Ile kosztuje automatyzacja jednego procesu w małej firmie
• Maile z formularza trafiają do spamu: SPF, DKIM i DMARC po kolei
• Ile kosztuje portal klienta dla firmy usługowej: widełki i zakres