O tym dokumencie
Dokument przeznaczony jest dla integratorów, partnerów i deweloperów implementujących integracje z Symfonia KSeF Plus.
Dokument opisuje zmiany w API GraphQL Symfonia KSeF Plus niezbędne do pracy z KSeF API 2.0.
Ten przewodnik ułatwia proces migracji z KSeF API 1.0 na KSeF API 2.0. Ministerstwo Finansów wprowadziło nową wersję API wraz z nowym schematem faktur FA(3), co wymaga dostosowania integracji.
Symfonia KSeF Plus została zaprojektowana z myślą o kompatybilności wstecznej. Nasze API GraphQL zaktualizowano w sposób nienaruszający istniejących integracji (non-breaking):
•Istniejące zapytania (queries) i mutacje (mutations) działają bez zmian,
•Nowe pola i typy dodano jako rozszerzenia (additive changes),
•Twój kod działa bez modyfikacji, jeśli nie potrzebujesz funkcji API 2.0,
•Migrację można przeprowadzić stopniowo, według potrzeb biznesowych.
Pełna dokumentacja API GraphQL:
Jeśli integrujesz się od podstaw lub potrzebujesz szczegółowej dokumentacji wszystkich zapytań, mutacji i typów danych, zapoznaj się z pełną dokumentacją API GraphQL: Dokumentacja Symfonia KSeF Plus API.
Jeśli Twoja integracja korzysta wyłącznie z KSeF API 1.0 i nie wymaga obsługi faktur FA(3), obecnie nie są wymagane żadne zmiany.
Pamiętaj jednak, że wyłączenie KSeF API 1.0 planowane jest na koniec stycznia 2026 roku – do tego czasu zalecamy migrację rozwiązań do KSeF API 2.0.
Spis treści
3.Zmiany w modelach odpowiedzi
5.Porównanie FA(2) i FA(3) - materiał Ministerstwa Finansów
6.Model FA(2) vs FA(3) - szczegółowe różnice
Poniższa tabela prezentuje wszystkie zapytania GraphQL dostępne w Symfonia KSeF Plus. Kolumna "Status" wskazuje, czy zapytanie zostało zmienione w kontekście API 2.0. Większość zapytań pozostaje bez zmian lub otrzymała jedynie rozszerzenia additive (nowe opcjonalne pola).
Nazwa Query |
Status |
Zmiana kontraktu |
Opis i uwagi |
GetKSeFInvoiceDTO |
Legacy (V1) |
Bez zmian |
Pobiera fakturę w schemacie FA(1). Oznaczone jako @deprecated. Utrzymane dla kompatybilności wstecznej. |
GetKSeFInvoiceDTOV2 |
Active |
Bez zmian |
Pobiera fakturę w schemacie FA(2). Aktywnie wspierane. Domyślny wybór dla faktur FA(2). |
GetKSeFInvoiceDTOV3 |
NOWA (API 2.0) |
Pola specyficzne V3 |
Nowe query dla API 2.0. Pobiera faktury w schemacie FA(3). Zawiera nowe sekcje, m.in. załączniki (Zalaczniki). Jeśli chcesz obsługiwać faktury FA(3), użyj tego zapytania. |
GetKSeFSettings |
NOWA (API 2.0) |
- |
Nowe query dla API 2.0. Pobiera ustawienia użytkownika związane z KSeF (autoryzacja, uprawnienia, dane uwierzytelniające). Zastępuje część funkcjonalności GetUserPropertiesKSeF. |
GetEArchiveSettings |
NOWA (API 2.0) |
- |
Nowe query dla API 2.0. Pobiera ustawienia użytkownika związane z e-archiwum (automatyczne pobieranie, wysyłanie, walidacja białej listy, współdzielony dostęp, pole ApiVersion). Zastępuje część funkcjonalności GetUserPropertiesEArchive. |
GetInvoiceFileContentActionGroup |
Rozszerzone |
Dodany parametr InvoiceFormat: InvoiceFileType |
Zwraca zbiorczy dokument ZIP z fakturami. Nowy parametr InvoiceFormat pozwala wybrać format: PDF lub XML. Domyślnie: PDF. Opis zmieniony: "Zwraca zbiorczy dokument ZIP z fakturami PDF lub XML". |
IsDownloadInvoicesRunning |
Rozszerzone (API 2.0) |
Pole RunningBoundTypes |
Dodane pole RunningBoundTypes: [InvoiceBound] wskazujące, które typy faktur (Internal/External) są aktualnie pobierane. Umożliwia precyzyjne określenie trwających operacji pobierania. |
GetPackageStatistic |
Rozszerzone (API 2.0) |
Pola AskAdminForPackage, DateFrom |
Dodane pola: AskAdminForPackage: AskAdminForPackageResponse oraz DateFrom: DateTimeOffset. Pozwalają na lepszą kontrolę statystyk pakietów oraz ich dat początkowych. |
Pozostałe queries |
Bez zmian |
- |
Inne zapytania (GetInvoiceFileContentSingle, GetContractors, GetPermissionsKSeF, KSeFSessionInfo, etc.) działają bez zmian zarówno dla FA(2), jak i FA(3). |
Uwaga o filtrach: Wiele queries otrzymało rozszerzenia filtrów (np. SupplierTypes, ContractorSettings), ale są to usprawnienia ogólne systemu, a nie zmiany specyficzne dla migracji API 2.0.
Mutacje GraphQL umożliwiają modyfikację danych oraz wykonywanie operacji w KSeF. Poniższa tabela pokazuje, które mutacje zostały zmienione lub dodane w kontekście API 2.0.
Nazwa Mutation |
Status |
Zmiana pól wejściowych/wyjściowych |
Opis i uwagi |
SendToEArchiveBatchV3 |
NOWA (API 2.0) |
Obsługa FA(3) + rozszerzona walidacja |
Nowa mutacja dla API 2.0. Wysyła faktury FA(3) w trybie wsadowym. Zawiera rozszerzoną walidację zgodną z nowymi wymaganiami schematu FA(3) (w tym załączników). Użyj tej mutacji, jeśli wysyłasz faktury FA(3). |
SendToEArchiveBatchV2 |
Active |
Wsparcie FA(2) w trybie wsadowym |
Wysyła wiele faktur FA(2) do eArchiwum w trybie wsadowym (batch). Zalecane dla faktur FA(2). |
SendToEArchiveV2 |
Deprecated |
- |
Oznaczone jako @deprecated. Zastąpione przez SendToEArchiveBatchV2. W wersji FA(3) dostępne będzie jedynie SendToEArchiveBatchV3. Zalecane jest użycie mutacji batch dla lepszej wydajności. |
SetKSeFInvoiceDownloaded |
Rozszerzone (API 2.0) |
Dodane pole Overwrite: Boolean |
Ustawia status faktury jako pobranej. W API 2.0 dodano opcjonalny parametr Overwrite (domyślnie false), który pozwala na nadpisanie istniejącego statusu pobrania. Parametry otrzymały opisy: Downloaded - "Znacznik pobrania faktury", InvoiceId - "Identyfikator faktury". |
OverwriteKSeFInvoiceDownloaded |
Deprecated |
- |
Przestarzałe. Używaj SetKSeFInvoiceDownloaded z parametrem Overwrite=true. |
AskAdminForPackage |
NOWA (API 2.0) |
- |
Nowa mutacja. Pozwala na zażądanie dodatkowego pakietu od administratora. Zwraca typ AskAdminForPackageResponse. |
KSeFAutoFetchingInvoices |
Rozszerzone (API 2.0) |
Dodane opcjonalne pole downloadLimitDate: DateTimeOffset |
Konfiguruje automatyczne pobieranie faktur. API 2.0 pozwala określić datę graniczną pobierania (downloadLimitDate), co umożliwia precyzyjniejszą kontrolę zakresu pobieranych faktur. |
Pozostałe mutacje |
Active |
- |
Większość mutacji pozostaje bez zmian. Autoryzacja (AuthorizeInKSeF, AuthorizeInKSeFWithToken) oraz zarządzanie uprawnieniami działają tak samo dla API 1.0 i 2.0. |
Uwaga o odpowiedziach websocket: Wiele typów odpowiedzi websocket otrzymało dodatkowe pola (SimultaneousRunRelatedTypes, retryCount), ale są to usprawnienia ogólne mechanizmu notyfikacji, a nie zmiany specyficzne dla migracji API 2.0.
Modele odpowiedzi GraphQL zostały rozszerzone o nowe pola wymagane przez API 2.0. Wszystkie zmiany są additive – nie usunięto żadnych istniejących pól.
Typ GraphQL |
Pole |
Zmiana |
Opis |
Invoice |
SchemaVersion |
Rozszerzone wartości |
Może przyjąć nową wartość V13775 dla FA(3). System automatycznie rozpoznaje wersję schematu faktury. |
Invoice |
PermanentStorageDate |
Nowe pole (API 2.0) |
Nowe pole w API 2.0. Data trwałego przechowywania faktury w KSeF. Zwracane dla faktur przetworzonych w API 2.0. Umożliwia filtrowanie i sortowanie. |
EArchiveUserPropertiesType |
ApiVersion |
Nowe pole (API 2.0) |
Nowe pole wskazujące wersję API KSeF (1 lub 2) używaną przez system. Pozwala klientom dostosować logikę do używanej wersji API. |
GetPackageStatisticSegment |
AskAdminForPackage, DateFrom |
Nowe pola (API 2.0) |
Dodane pola: AskAdminForPackage: AskAdminForPackageResponse oraz DateFrom: DateTimeOffset. |
IsDownloadInvoicesRunningResult |
RunningBoundTypes |
Nowe pole (API 2.0) |
Nowe pole RunningBoundTypes: [InvoiceBound] wskazujące typy faktur aktualnie pobieranych (Internal/External). |
SetKSeFInvoiceDownloaded |
Overwrite |
Dodanie pola (API 2.0) |
Nowe pole wskazujące, czy operacja nadpisuje istniejący status. Opcjonalne, domyślnie false. |
Uwaga o innych polach: Wiele modeli otrzymało dodatkowe pola (np. ContractorSettings, pola filtrów), ale są to usprawnienia ogólne systemu, a nie zmiany specyficzne dla migracji API 2.0.
Poniżej znajdują się zmiany w typach wyliczeniowych (enum), które zostały rozszerzone w API 2.0.
Nazwa Enum |
Zmiana |
Opis |
KsefXsdVersion |
Dodana wartość V13775 (API 2.0) |
Nowa wartość wskazująca na schemat FA(3) używany w API 2.0. |
RolaPodmiotu3 |
Dodane wartości (API 2.0) |
Nowe wartości: CZLONEK_GRUPY_VAT_ODBIORCA, CZLONEK_GRUPY_VAT_WYSTAWCA, JEDNOSTKA_SAMORZADU_ODBIORCA, JEDNOSTKA_SAMORZADU_WYSTAWCA. Rozszerzają możliwości określenia roli podmiotu w fakturze FA(3). |
DownloadStateUserMessage |
Dodane wartości (API 2.0) |
Nowe wartości: PROCESSING_INVOICES, WAITING_FOR_K_SE_F. Lepsze odzwierciedlenie stanów procesu pobierania faktur w API 2.0. |
WebsocketNotificationType |
Dodane wartości (API 2.0) |
Nowe wartości: AUTO_FETCHING_INVOICES_BATCH, FETCHING_INVOICES_BATCH. Notyfikacje dedykowane dla operacji batch w API 2.0. |
InvoiceFileType |
NOWY enum |
Nowy typ wyliczeniowy z wartościami: PDF, XML. Używany w GetInvoiceFileContentActionGroup do określenia formatu eksportowanych faktur. |
Uwaga o innych enumach: Niektóre enumy otrzymały nowe wartości (np. AttachmentShareOperationType, WebsocketErrorType), ale są to usprawnienia ogólne systemu, a nie zmiany specyficzne dla migracji API 2.0.
Porównanie FA(2) i FA(3) - materiał Ministerstwa Finansów
Ministerstwo Finansów udostępnia szczegółową dokumentację techniczną nowych schematów faktur. Poniżej znajduje się oficjalny materiał porównawczy MF oraz dokumentacja GraphQL Symfonia dla typów FakturaV2 i FakturaV3.
Oficjalna dokumentacja Ministerstwa Finansów:
•Materiał porównawczy FA(2) i FA(3) – szczegółowe zestawienie zmian w strukturach faktur przygotowane przez MF
Dokumentacja GraphQL Symfonia KSeF Plus:
•Dokumentacja FakturaV3 (FA3) – schemat GraphQL dla faktury FA(3) w API Symfonia
•Dokumentacja FakturaV2 (FA2) – schemat GraphQL dla faktury FA(2) w API Symfonia
Dokumenty MF zawierają kompleksowe porównanie obiektów FA(2) i FA(3) na poziomie XSD oraz szczegółowe wyjaśnienia zmian w kontekście wymagań biznesowych i prawnych. Dokumentacja GraphQL Symfonia prezentuje struktury danych dostępne w naszym API.
Model FA(2) vs FA(3) - szczegółowe różnice
Poniższa tabela przedstawia mapowanie zmian w modelu faktury pomiędzy schematem V2 (FA2) a V3 (FA3). Zwróć uwagę na nowe typy obiektów oraz nowe pole Zalaczniki, które jest najważniejszą nowością w FA(3).
Sekcja faktury |
FakturaV2 (FA2) |
FakturaV3 (FA3) |
Opis zmian |
Wersja |
V2 |
V3 |
Zmiana wersji schematu. |
Sprzedawca |
Typ V2 |
Typ V3 |
Aktualizacja typu podmiotu sprzedawcy. Dodane nowe pola adresowe i identyfikacyjne. |
Nabywca |
Typ V2 |
Typ V3 |
Aktualizacja typu podmiotu nabywcy. Dodane nowe pola adresowe i identyfikacyjne. |
TrzeciPodmiot |
Lista V2 |
Lista V3 |
Aktualizacja typu dla podmiotów trzecich (np. pośrednicy, dostawcy). |
PodmiotUpowazniony |
Typ V2 |
Typ V2 |
Bez zmian. |
Naglowek |
Typ V2 |
Typ V3 |
Aktualizacja nagłówka faktury. Dodane nowe pola metadanych. |
Adnotacje |
Typ V2 |
Typ V2 |
Bez zmian. |
Korekta |
Typ V2 |
Typ V2 |
Bez zmian. Obsługa faktur korygujących pozostaje taka sama. |
PodsumowanieVat |
Lista |
Lista V3 |
Aktualizacja typu podsumowania VAT. Dodane nowe pola dla rozliczenia VAT w kontekście międzynarodowym. |
Wiersze |
Lista V2 |
Lista V3 |
Aktualizacja typu wierszy faktury. Dodane nowe pola opisowe pozycji. |
Rozliczenie |
Typ standardowy |
Typ standardowy |
Bez zmian. |
Platnosc |
Typ V2 |
Typ V3 |
Aktualizacja typu płatności. Dodane nowe formy płatności. |
WarunkiTransakcji |
Typ V2 |
Typ V3 |
Aktualizacja warunków transakcji. Dodane nowe pola związane z Incoterms i specyfiką handlu międzynarodowego. |
Zamowienie |
Typ V2 |
Typ V3 |
Aktualizacja informacji o zamówieniu. Dodane nowe pola referencyjne. |
Stopka |
Typ V2 |
Typ V2 |
Bez zmian. |
Zalaczniki |
Brak |
Lista V3 |
NOWOŚĆ! Faktury FA(3) mogą zawierać załączniki (np. dokumenty PDF, zdjęcia, schematy). Jest to najważniejsza zmiana strukturalna w schemacie V3. Wymaga uwzględnienia w procesach integracyjnych. |
Najważniejsza zmiana: Schemat FA(3) wprowadza sekcję Zalaczniki, która pozwala dołączać do faktury dokumenty towarzyszące w formacie binarnym (zakodowane Base64).
Podsumowanie
Migracja z KSeF API 1.0 do API 2.0 w ekosystemie Symfonia KSeF Plus została zaprojektowana jako proces nienaruszający istniejących integracji. Integracje, które korzystają wyłącznie z API 1.0 i nie wymagają obsługi nowego formatu faktur FA(3), mogą działać bez zmian. Należy jednak pamiętać, że bez migracji nie będą one współpracować z KSeF API 2.0. Nowe funkcjonalności, w tym obsługa faktur FA(3), są dostępne wyłącznie w API 2.0 poprzez nowe zapytania i mutacje GraphQL. Dodatkowo, w związku z planowanym wyłączeniem KSeF API 1.0 na koniec stycznia 2026 roku, zalecana jest migracja rozwiązań do API 2.0 przed tym terminem.
Wsparcie techniczne: W przypadku pytań dotyczących migracji lub problemów z integracją, skontaktuj się z naszym zespołem wsparcia technicznego. Udostępniamy również dokumentację API GraphQL ze szczegółowymi przykładami zapytań i mutacji.