Integracja KSeF API z systemami ERP to kluczowy krok w kierunku pełnej automatyzacji procesów księgowych. W tym praktycznym przewodniku wyjaśniamy, jak połączyć Krajowy System e-Faktur z Twoim systemem ERP, jakie metody API są dostępne oraz jak zaimplementować wymianę danych w czasie rzeczywistym.
W tym artykule:
Czym jest API KSeF?
API KSeF (Application Programming Interface) to oficjalny interfejs programistyczny udostępniony przez Ministerstwo Finansów, który umożliwia systemom ERP bezpośrednią komunikację z Krajowym Systemem e-Faktur. Dzięki API przedsiębiorcy mogą automatyzować procesy wysyłki i odbioru faktur bez konieczności ręcznego logowania się do aplikacji webowej.
API KSeF oparte jest na architekturze REST (Representational State Transfer), co zapewnia prostotę integracji i szerokie wsparcie w większości nowoczesnych języków programowania i frameworków. Komunikacja odbywa się za pomocą protokołu HTTPS z wykorzystaniem formatu JSON lub XML dla danych wejściowych i wyjściowych.
Główne zalety API KSeF:
- Automatyzacja: Eliminacja ręcznych operacji przy wysyłce i odbiorze faktur
- Szybkość: Przetwarzanie faktur w czasie rzeczywistym
- Skalowalność: Obsługa dużych wolumenów transakcji bez degradacji wydajności
- Integracja: Bezpośrednie połączenie z systemami ERP, CRM i innymi aplikacjami
- Monitoring: Pełna kontrola nad statusami faktur i historią operacji
Dostępne metody API KSeF
API KSeF oferuje szereg metod umożliwiających kompleksową obsługę fakturowania elektronicznego. Poniżej przedstawiamy najważniejsze endpointy dostępne w systemie:
Metody dla wystawcy faktur:
| Metoda | Endpoint | Opis |
|---|---|---|
| POST | /api/invoice/send | Wysyłka faktury do KSeF |
| GET | /api/invoice/status/{ksefNumber} | Sprawdzenie statusu faktury |
| GET | /api/invoice/details/{ksefNumber} | Pobranie szczegółów faktury |
| PUT | /api/invoice/cancel/{ksefNumber} | Anulowanie faktury |
| GET | /api/invoice/pdf/{ksefNumber} | Pobranie faktury w formacie PDF |
Metody dla nabywcy:
| Metoda | Endpoint | Opis |
|---|---|---|
| GET | /api/inbox/list | Lista faktur w skrzynce odbiorczej |
| GET | /api/inbox/invoice/{ksefNumber} | Pobranie konkretnej faktury |
| POST | /api/inbox/acknowledge | Potwierdzenie odbioru faktury |
| GET | /api/inbox/search | Wyszukiwanie faktur po parametrach |
Autentykacja i bezpieczeństwo
Dostęp do API KSeF wymaga odpowiedniej autentykacji, która zapewnia bezpieczeństwo danych podatników i chroni system przed nieautoryzowanym dostępem.
Sposoby autentykacji:
- Token API: Unikalny token przypisany do każdego podatnika, generowany w panelu KSeF
- Certyfikat kwalifikowany: Elektroniczny podpis kwalifikowany lub pieczęć firmowa
- Profil zaufany: Autentykacja przez system Profilu Zaufanego ePUAP
- Token OAuth 2.0: Nowoczesny standard autentykacji dla aplikacji trzecich
Zabezpieczenia API:
- Szyfrowanie TLS 1.3: Wszystkie komunikaty są szyfrowane protokołem HTTPS
- Rate limiting: Ograniczenie liczby zapytań na minutę (1000 req/min dla standardowego dostępu)
- IP whitelisting: Możliwość ograniczenia dostępu do określonych adresów IP
- Logowanie operacji: Pełna historia wszystkich operacji API dostępna w panelu
- Token rotation: Wymuszana rotacja tokenów co 90 dni
Wysyłka faktur przez API
Wysyłka faktury do KSeF przez API to proces wieloetapowy, który obejmuje przygotowanie danych, walidację, wysyłkę i potwierdzenie odbioru.
Proces wysyłki faktury krok po kroku:
- Przygotowanie faktury: Wygenerowanie pliku XML zgodnego ze schematem FA_VAT lub FA_VAT_E
- Walidacja lokalna: Sprawdzenie poprawności struktury XML przed wysyłką
- Wysyłka: Wywołanie metody POST /api/invoice/send z treścią faktury
- Odbiór odpowiedzi: System zwraca numer KSeF lub komunikat błędu
- Potwierdzenie: Opcjonalne pobranie UPO (Urzędowe Poświadczenie Odbioru)
Odbiór faktur od dostawców
Odbiór faktur przez API KSeF umożliwia automatyczne pobieranie dokumentów od dostawców bezpośrednio do systemu ERP. Proces ten można zautomatyzować, ustawiając regularne zapytania do API lub wykorzystując webhooki.
Proces odbioru faktur:
- Sprawdzenie skrzynki: Wywołanie GET /api/inbox/list w celu pobrania listy nowych faktur
- Pobranie faktury: Wywołanie GET /api/inbox/invoice/{ksefNumber} dla każdej nowej faktury
- Konwersja: Przekształcenie XML FA_VAT na format zrozumiały dla ERP
- Import: Zapisanie faktury w module księgowym systemu ERP
- Potwierdzenie: Wywołanie POST /api/inbox/acknowledge w celu oznaczenia faktury jako odebranej
Automatyczny odbiór faktur:
Dla maksymalnej automatyzacji zaleca się skonfigurowanie zadania cron, które co godzinę będzie sprawdzało skrzynkę KSeF i automatycznie importowało nowe faktury do ERP. Dzięki temu księgowość zawsze ma aktualne dane o zobowiązaniach.
Integracja KSeF API z Odoo
Odoo oferuje natywne wsparcie dla KSeF poprzez moduł l10n_pl_edi, który implementuje komunikację z API KSeF bez konieczności pisania dodatkowego kodu.
Konfiguracja KSeF API w Odoo:
- Zainstaluj moduł l10n_pl_edi z repozytorium Odoo
- Przejdź do Ustawienia → Księgowość → KSeF Integration
- Wprowadź token API uzyskany z panelu KSeF
- Skonfiguruj certyfikat do podpisywania faktur (opcjonalnie)
- Ustaw domyślne parametry wysyłki (schemat FA_VAT/FA_VAT_E)
- Przeprowadź test połączenia z środowiskiem testowym KSeF
Automatyzacja w Odoo:
Po skonfigurowaniu integracji, Odoo automatycznie:
- Wysyła faktury do KSeF po ich zatwierdzeniu
- Pobiera faktury od dostawców co godzinę (konfigurowalne)
- Aktualizuje statusy faktur w czasie rzeczywistym
- Generuje raporty zgodności z KSeF
- Archiwizuje kopie faktur i potwierdzeń
Kody błędów i ich obsługa
API KSeF zwraca szczegółowe kody błędów, które umożliwiają szybką identyfikację i naprawę problemów. Poniżej znajduje się lista najczęstszych kodów błędów:
| Kod | Opis | Rozwiązanie |
|---|---|---|
| 400 | Bad Request - nieprawidłowa struktura XML | Sprawdź zgodność ze schematem FA_VAT |
| 401 | Unauthorized - nieprawidłowy token | Sprawdź ważność tokenu API |
| 403 | Forbidden - brak uprawnień | Sprawdź uprawnienia podatnika |
| 404 | Not Found - faktura nie istnieje | Sprawdź numer KSeF |
| 409 | Conflict - faktura już istnieje | Sprawdź czy faktura nie została już wysłana |
| 429 | Too Many Requests - limit przekroczony | Zaczekaj i spróbuj ponownie |
| 500 | Internal Server Error - błąd KSeF | Skontaktuj się z pomocą techniczną |
Obsługa błędów w kodzie:
Zaleca się implementację mechanizmu retry z exponential backoff dla kodów 429 i 500, oraz szczegółowego logowania błędów dla celów diagnostycznych.
FAQ - Najczęściej zadawane pytania
Przeczytaj również:
Potrzebujesz integracji KSeF API?
Zintegruj KSeF z Twoim systemem ERP i zautomatyzuj procesy księgowe. Bezpłatna konsultacja.
Umów rozmowę →