OpenAPI - co to jest? Definicja pojęcia KSeF
Co to jest OpenAPI?
OpenAPI (dawniej znany jako Swagger) to standard specyfikacji interfejsów programistycznych (API) w formacie YAML lub JSON. OpenAPI opisuje strukturę API: jakie endpointy są dostępne, jakie parametry przyjmują, jakie dane zwracają, jakie są kody błędów.
W kontekście KSeF, dokumentacja API 2.0 jest dostępna w formacie OpenAPI. Oznacza to, że: możesz przeglądać dokumentację interaktywną (Swagger UI) w przeglądarce, możesz testować endpointy bezpośrednio w dokumentacji, możesz automatycznie generować kod klienta dla różnych języków programowania, możesz łatwo zrozumieć strukturę API i wymagania.
Dokumentacja OpenAPI KSeF API 2.0 jest dostępna pod adresem ksef-test.mf.gov.pl/docs/v2/ i zawiera pełny opis wszystkich endpointów, parametrów, przykładów żądań i odpowiedzi.
Jak korzystać z dokumentacji OpenAPI KSeF?
Dokumentacja OpenAPI KSeF jest dostępna w formie interaktywnej strony (Swagger UI), gdzie możesz: przeglądać wszystkie endpointy API, zobaczyć parametry każdego endpointu, zobaczyć przykłady żądań i odpowiedzi, testować endpointy bezpośrednio w przeglądarce (wymaga uwierzytelniania), pobrać pełną specyfikację OpenAPI w formacie JSON. Dokumentacja jest dostępna pod adresem ksef-test.mf.gov.pl/docs/v2/ i jest aktualizowana wraz z wprowadzaniem zmian w API.
Zalety OpenAPI
OpenAPI oferuje wiele zalet: interaktywna dokumentacja - możesz testować API bezpośrednio w przeglądarce, automatyczne generowanie kodu - narzędzia mogą generować kod klienta dla różnych języków programowania, łatwe zrozumienie API - dokumentacja jest czytelna i dobrze zorganizowana, standardowy format - OpenAPI jest standardem używanym przez wiele systemów, aktualizacje - dokumentacja jest zawsze aktualna (jest generowana z kodu API). Dzięki OpenAPI integracja z KSeF API jest znacznie prostsza.
OpenAPI vs tradycyjna dokumentacja
OpenAPI: interaktywna (można testować endpointy), automatycznie generowana (zawsze aktualna), standardowy format (można użyć narzędzi), zawiera przykłady, łatwa do zrozumienia. Tradycyjna dokumentacja: statyczna (tylko do czytania), może być nieaktualna, różne formaty, wymaga ręcznego utrzymania. OpenAPI jest nowoczesnym standardem, który znacznie ułatwia pracę z API.
FAQ
Gdzie znajdę dokumentację OpenAPI KSeF?
Dokumentacja OpenAPI KSeF API 2.0 jest dostępna pod adresem 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. Możesz też pobrać pełną specyfikację OpenAPI w formacie JSON.
Czy mogę testować API w dokumentacji OpenAPI?
Tak, dokumentacja OpenAPI KSeF zawiera interaktywny interfejs (Swagger UI), gdzie możesz testować endpointy bezpośrednio w przeglądarce. Aby testować endpointy, musisz: mieć dostęp do środowiska testowego KSeF, mieć odpowiednie dane uwierzytelniające (token lub certyfikat), zalogować się w interfejsie dokumentacji. Pamiętaj, że testujesz w środowisku testowym, więc nie ma to wpływu na rzeczywiste dane podatkowe.
Czy mogę wygenerować kod z dokumentacji OpenAPI?
Tak, możesz użyć narzędzi do generowania kodu z dokumentacji OpenAPI. Popularne narzędzia to: Swagger Codegen, OpenAPI Generator, Postman (może importować OpenAPI i generować kod). Możesz wygenerować kod klienta dla różnych języków programowania (Java, C#, Python, JavaScript, itd.) na podstawie dokumentacji OpenAPI KSeF. Pamiętaj, że oficjalne SDK KSeF (dla Java i C#) są już dostępne i są zalecane zamiast generowania własnego kodu.
Czy dokumentacja OpenAPI jest zawsze aktualna?
Tak, dokumentacja OpenAPI KSeF jest generowana automatycznie z kodu API, więc jest zawsze aktualna. Gdy MF wprowadza zmiany w API, dokumentacja OpenAPI jest automatycznie aktualizowana. To jedna z głównych zalet OpenAPI - nie ma problemu z nieaktualną dokumentacją.