KSeF API odzyskiwanie danych po awarii systemu

Po awarii systemu zintegrowanego z KSeF konieczna jest synchronizacja danych z systemem KSeF. API 2.0 oferuje mechanizmy do odzyskiwania informacji o wysłanych fakturach i sesjach.

Odzyskiwanie danych po awarii

W przypadku awarii systemu zintegrowanego z KSeF, gdy dane lokalne zostały utracone, konieczna jest synchronizacja z systemem KSeF, aby odtworzyć informacje o wysłanych fakturach i sesjach.

KSeF API 2.0 oferuje endpointy do listowania sesji (GET /api/v2/sessions) oraz pobierania faktur za zakres dat (POST /api/v2/invoices/query), co umożliwia odtworzenie stanu po awarii.

System wykrywa duplikaty faktur na podstawie kombinacji: NIP sprzedawcy, RodzajFaktury i numer faktury (P_2). Próba ponownego wysłania tej samej faktury spowoduje błąd 440 (Duplikat faktury), co chroni przed podwójnym wystawieniem.

Instrukcja krok po kroku

1. Pobierz listę sesji

Wywołaj endpoint GET /api/v2/sessions, aby pobrać listę wszystkich sesji (interaktywnych i wsadowych) w określonym zakresie dat. Lista zawiera numery referencyjne sesji, daty utworzenia i statusy.

2. Pobierz faktury z sesji

Dla każdej sesji z listy wywołaj GET /api/v2/sessions/{referenceNumber}/invoices, aby pobrać listę faktur wysłanych w danej sesji wraz z ich statusami i numerami KSeF.

3. Pobierz faktury za zakres dat

Alternatywnie użyj endpointu POST /api/v2/invoices/query, aby pobrać faktury za określony zakres dat. Endpoint pozwala na filtrowanie faktur według różnych kryteriów (data, NIP, status).

4. Synchronizuj dane lokalne

Porównaj pobrane dane z KSeF z danymi lokalnymi (jeśli dostępne) i zsynchronizuj stan. Zaktualizuj lokalną bazę danych o informacje o fakturach, które zostały wysłane do KSeF, ale nie są w lokalnym systemie.

5. Unikaj duplikatów

Przed ponownym wysłaniem faktury sprawdź, czy nie została już wysłana do KSeF. System wykrywa duplikaty na podstawie NIP sprzedawcy, RodzajFaktury i numeru faktury (P_2). Próba ponownego wysłania spowoduje błąd 440.

Najczęstsze problemy i rozwiązania

Nie mam numerów referencyjnych sesji po awarii

Użyj endpointu GET /api/v2/sessions, aby pobrać listę wszystkich sesji w określonym zakresie dat. Lista zawiera numery referencyjne sesji, które możesz użyć do pobrania szczegółów i faktur z każdej sesji.

Jak sprawdzić, które faktury zostały już wysłane?

Użyj endpointu POST /api/v2/invoices/query, aby pobrać faktury za określony zakres dat. Endpoint zwraca listę faktur wraz z ich statusami i numerami KSeF. Porównaj pobrane faktury z lokalną bazą danych, aby zidentyfikować brakujące wpisy.

Czy mogę ponownie wysłać fakturę, która została już wysłana?

Nie, system KSeF wykrywa duplikaty na podstawie kombinacji: NIP sprzedawcy, RodzajFaktury i numer faktury (P_2). Próba ponownego wysłania tej samej faktury spowoduje błąd 440 (Duplikat faktury). System chroni przed podwójnym wystawieniem faktur.

Faktura jest w trakcie przetwarzania w KSeF

Faktury w trakcie przetwarzania mogą nie być widoczne w wynikach zapytania POST /api/v2/invoices/query, dopóki nie zostaną przetworzone. Sprawdź status sesji (GET /api/v2/sessions/{referenceNumber}) i faktur w sesji (GET /api/v2/sessions/{referenceNumber}/invoices), aby zobaczyć faktury w trakcie przetwarzania.

Listowanie sesji

Endpoint GET /api/v2/sessions pozwala na pobranie listy wszystkich sesji (interaktywnych i wsadowych) w określonym zakresie dat. Lista zawiera numery referencyjne sesji, daty utworzenia, typy sesji i statusy. Endpoint jest dostępny od wersji API 2.0 i umożliwia odzyskanie informacji o sesjach po awarii systemu.

Pobieranie faktur z sesji

Endpoint GET /api/v2/sessions/{referenceNumber}/invoices zwraca listę faktur wysłanych w danej sesji wraz z ich statusami, numerami KSeF i metadanymi. Endpoint pozwala na szczegółowe sprawdzenie, które faktury zostały wysłane w konkretnej sesji i jaki jest ich aktualny status w systemie KSeF.

Zapytanie o faktury za zakres dat

Endpoint POST /api/v2/invoices/query pozwala na pobranie faktur za określony zakres dat z możliwością filtrowania według różnych kryteriów (data, NIP, status). Endpoint zwraca faktury, które zostały już przetworzone przez system KSeF. Faktury w trakcie przetwarzania mogą nie być widoczne w wynikach.

Wykrywanie duplikatów

System KSeF wykrywa duplikaty faktur na podstawie kombinacji trzech pól: NIP sprzedawcy (Podmiot1:NIP), RodzajFaktury oraz numer faktury (P_2). W przypadku duplikatu system zwraca błąd 440 (Duplikat faktury). Unikalność faktury jest utrzymywana przez 10 pełnych lat. Mechanizm chroni przed podwójnym wystawieniem faktur, również po awarii systemu.

FAQ

Jak odzyskać dane po awarii systemu zintegrowanego z KSeF?

Użyj endpointu GET /api/v2/sessions, aby pobrać listę wszystkich sesji w określonym zakresie dat. Następnie dla każdej sesji pobierz listę faktur (GET /api/v2/sessions/{referenceNumber}/invoices) lub użyj endpointu POST /api/v2/invoices/query, aby pobrać faktury za zakres dat. Porównaj pobrane dane z lokalną bazą i zsynchronizuj stan.

Czy mogę sprawdzić, które faktury zostały już wysłane do KSeF?

Tak, użyj endpointu POST /api/v2/invoices/query, aby pobrać faktury za określony zakres dat. Endpoint zwraca listę faktur wraz z ich statusami i numerami KSeF. Możesz również sprawdzić faktury w konkretnej sesji używając GET /api/v2/sessions/{referenceNumber}/invoices.

Co zrobić, jeśli nie mam numerów referencyjnych sesji?

Czy mogę ponownie wysłać fakturę po awarii?

System KSeF wykrywa duplikaty na podstawie kombinacji: NIP sprzedawcy, RodzajFaktury i numer faktury (P_2). Próba ponownego wysłania tej samej faktury spowoduje błąd 440 (Duplikat faktury), co chroni przed podwójnym wystawieniem. Przed ponownym wysłaniem sprawdź, czy faktura nie została już wysłana.

Jak synchronizować dane lokalne z KSeF?

Pobierz listę sesji (GET /api/v2/sessions) i faktury z każdej sesji (GET /api/v2/sessions/{referenceNumber}/invoices) lub użyj zapytania o faktury (POST /api/v2/invoices/query). Porównaj pobrane dane z lokalną bazą danych i zaktualizuj lokalny system o brakujące informacje o fakturach wysłanych do KSeF.