Endpoint - co to jest? Definicja pojęcia KSeF
Co to jest endpoint?
Endpoint to adres URL (Uniform Resource Locator), pod którym dostępna jest określona funkcjonalność w API. Można to porównać do adresu strony internetowej - każda strona ma swój adres, a każda operacja w API ma swój endpoint.
W kontekście KSeF API, endpointy są zorganizowane logicznie według funkcjonalności: /api/v2/auth/* - uwierzytelnianie i autoryzacja, /api/v2/sessions/* - zarządzanie sesjami (interaktywne i wsadowe), /api/v2/invoices/* - operacje na fakturach, /api/v2/permissions/* - zarządzanie uprawnieniami, /api/v2/operations/* - sprawdzanie statusu operacji.
Każdy endpoint wymaga odpowiedniej metody HTTP (GET, POST, PUT, DELETE) i może wymagać danych w żądaniu (np. faktura w formacie XML) oraz autoryzacji (token JWT).
Przykłady endpointów w KSeF API
Przykłady endpointów w KSeF API 2.0: POST /api/v2/auth/challenge - pobranie wyzwania do uwierzytelniania, POST /api/v2/auth/xades-signature - uwierzytelnianie przez podpis XAdES, POST /api/v2/sessions/online - otwarcie sesji interaktywnej, POST /api/v2/sessions/online/{referenceNumber}/invoices/ - wysłanie faktury, GET /api/v2/invoices/{invoiceNumber} - pobranie faktury, GET /api/v2/operations/{referenceNumber} - sprawdzenie statusu operacji. Każdy endpoint ma określoną funkcję i wymaga odpowiednich danych oraz uprawnień.
Jak używać endpointów?
Aby użyć endpointu w KSeF API: 1) Uwierzytelnij się i uzyskaj token JWT (accessToken), 2) Przygotuj żądanie HTTP z odpowiednią metodą (GET, POST, itd.), 3) Dodaj token autoryzacyjny w nagłówku żądania, 4) Jeśli endpoint wymaga danych (np. faktura), dodaj je w ciele żądania, 5) Wyślij żądanie do odpowiedniego adresu URL endpointu, 6) Odbierz odpowiedź i przetwórz ją. Większość programistów używa bibliotek HTTP w swoim języku programowania lub oficjalnych SDK KSeF, które upraszczają ten proces.
Dokumentacja endpointów
Dokumentacja wszystkich endpointów KSeF API 2.0 jest dostępna w formacie OpenAPI (Swagger) na stronie ksef-test.mf.gov.pl/docs/v2/. Dokumentacja zawiera: opis każdego endpointu, wymagane parametry, format danych wejściowych i wyjściowych, przykłady żądań i odpowiedzi, kody błędów. Możesz też testować endpointy bezpośrednio w dokumentacji interaktywnej.
FAQ
Czy muszę znać wszystkie endpointy?
Nie, jeśli używasz oficjalnego SDK KSeF (dla Java lub C#), nie musisz znać szczegółów endpointów - biblioteka ukrywa te szczegóły i udostępnia proste funkcje. Jeśli integrujesz się bezpośrednio z API, powinieneś zapoznać się z dokumentacją endpointów, które chcesz użyć.
Gdzie znajdę listę wszystkich endpointów?
Lista wszystkich endpointów KSeF API 2.0 jest dostępna w dokumentacji OpenAPI na stronie ksef-test.mf.gov.pl/docs/v2/. Dokumentacja jest interaktywna - możesz przeglądać endpointy, zobaczyć ich parametry i nawet testować je bezpośrednio w przeglądarce.
Czy endpointy się zmieniają?
Endpointy w KSeF API są stabilne i nie powinny się zmieniać bez powiadomienia. Jeśli MF wprowadza zmiany, są one ogłaszane z wyprzedzeniem w dokumentacji. Wersja API (v2) jest częścią adresu endpointu, więc nowe wersje API będą miały nowe endpointy (np. /api/v3/…), a stare pozostaną dostępne dla kompatybilności wstecznej.
Czy mogę testować endpointy?
Tak, możesz testować endpointy w środowisku testowym KSeF dostępnym pod adresem ksef-test.mf.gov.pl. Dokumentacja OpenAPI zawiera interaktywny interfejs, gdzie możesz testować endpointy bezpośrednio w przeglądarce. Pamiętaj, że do testowania potrzebujesz odpowiednich danych uwierzytelniających (token lub certyfikat).