KSeF API duplikaty faktur – wykrywanie i unikanie
Wykrywanie duplikatów w KSeF
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 zintegrowanego z KSeF.
W przeciwieństwie do wersji 1.0, gdzie duplikaty były sprawdzane tylko w kontekście jednej sesji, w wersji 2.0 duplikaty są sprawdzane globalnie w całym systemie KSeF, niezależnie od sesji.
Instrukcja krok po kroku
1. Zrozumienie identyfikacji unikalności
Zrozum, że unikalność faktury jest określana przez kombinację trzech pól: NIP sprzedawcy (Podmiot1:NIP), RodzajFaktury oraz numer faktury (P_2). Te same wartości tych trzech pól oznaczają duplikat, niezależnie od innych danych faktury.
2. Sprawdzenie przed wysłaniem
Przed wysłaniem faktury sprawdź, czy faktura o tych samych wartościach (NIP, RodzajFaktury, P_2) nie została już wysłana do KSeF. Użyj endpointu POST /api/v2/invoices/query, aby sprawdzić istniejące faktury, lub sprawdź lokalną bazę danych, jeśli masz synchronizację z KSeF.
3. Obsługa błędu 440
Obsłuż błąd 440 (Duplikat faktury) w aplikacji: nie ponawiaj wysyłki tej samej faktury, sprawdź, czy faktura została już wysłana i ma numer KSeF, zaktualizuj lokalną bazę danych o informacje z KSeF, poinformuj użytkownika o duplikacie.
4. Unikanie duplikatów po awarii
Po awarii systemu zsynchronizuj dane z KSeF przed ponownym wysłaniem faktur. Użyj endpointu GET /api/v2/sessions, aby pobrać listę sesji, następnie sprawdź faktury w każdej sesji. Przed ponownym wysłaniem sprawdź, czy faktura nie została już wysłana (błąd 440 chroni przed duplikatami).
Najczęstsze problemy i rozwiązania
Błąd 440 Duplikat faktury
Błąd 440 oznacza, że faktura o tych samych wartościach (NIP sprzedawcy, RodzajFaktury, numer faktury P_2) została już wysłana do KSeF. Sprawdź, czy faktura została już wysłana i ma numer KSeF. Nie ponawiaj wysyłki tej samej faktury. Zaktualizuj lokalną bazę danych o informacje z KSeF.
Jak sprawdzić, czy faktura została już wysłana?
Użyj endpointu POST /api/v2/invoices/query, aby sprawdzić istniejące faktury za zakres dat. Możesz również sprawdzić faktury w konkretnej sesji używając GET /api/v2/sessions/{referenceNumber}/invoices. Przed wysłaniem sprawdź lokalną bazę danych, jeśli masz synchronizację z KSeF.
Duplikaty po awarii systemu
Po awarii systemu zsynchronizuj dane z KSeF przed ponownym wysłaniem faktur. Użyj endpointu GET /api/v2/sessions, aby pobrać listę sesji, następnie sprawdź faktury w każdej sesji. Przed ponownym wysłaniem sprawdź, czy faktura nie została już wysłana. System wykrywa duplikaty i zwraca błąd 440, co chroni przed podwójnym wystawieniem.
Różnice między KSeF 1.0 a 2.0
W wersji 1.0 duplikaty były sprawdzane tylko w kontekście jednej sesji. W wersji 2.0 duplikaty są sprawdzane globalnie w całym systemie KSeF, niezależnie od sesji. Próba ponownego wysłania tej samej faktury (NIP, RodzajFaktury, P_2) spowoduje błąd 440, nawet jeśli faktura była wysłana w innej sesji.
Identyfikacja unikalności faktury
Unikalność faktury jest określana przez kombinację trzech pól: NIP sprzedawcy (Podmiot1:NIP), RodzajFaktury oraz numer faktury (P_2). Te same wartości tych trzech pól oznaczają duplikat, niezależnie od innych danych faktury (kwoty, daty, pozycje). Unikalność jest utrzymywana przez 10 pełnych lat w systemie KSeF.
Błąd 440 Duplikat faktury
Błąd 440 jest zwracany, gdy system wykryje duplikat faktury (te same wartości: NIP, RodzajFaktury, P_2). Błąd zawiera informacje o duplikacie i może zawierać numer KSeF faktury, jeśli został już nadany. Nie ponawiaj wysyłki tej samej faktury - zaktualizuj lokalną bazę danych o informacje z KSeF.
Sprawdzanie duplikatów przed wysłaniem
Przed wysłaniem faktury sprawdź, czy faktura o tych samych wartościach nie została już wysłana: użyj endpointu POST /api/v2/invoices/query dla faktur za zakres dat, sprawdź faktury w konkretnej sesji (GET /api/v2/sessions/{referenceNumber}/invoices), sprawdź lokalną bazę danych, jeśli masz synchronizację z KSeF. Sprawdzanie przed wysłaniem zmniejsza liczbę błędów 440.
Duplikaty po awarii systemu
Po awarii systemu zsynchronizuj dane z KSeF przed ponownym wysłaniem faktur. Użyj endpointu GET /api/v2/sessions, aby pobrać listę sesji, następnie sprawdź faktury w każdej sesji. Przed ponownym wysłaniem sprawdź, czy faktura nie została już wysłana. System wykrywa duplikaty i zwraca błąd 440, co chroni przed podwójnym wystawieniem, nawet po awarii systemu.
FAQ
Jak KSeF wykrywa duplikaty faktur?
KSeF wykrywa duplikaty na podstawie kombinacji trzech pól: NIP sprzedawcy (Podmiot1:NIP), RodzajFaktury oraz numer faktury (P_2). Te same wartości tych trzech pól oznaczają duplikat. W przypadku duplikatu system zwraca błąd 440 (Duplikat faktury). Unikalność jest utrzymywana przez 10 pełnych lat.
Co oznacza błąd 440?
Błąd 440 oznacza, że faktura o tych samych wartościach (NIP sprzedawcy, RodzajFaktury, numer faktury P_2) została już wysłana do KSeF. Nie ponawiaj wysyłki tej samej faktury. Sprawdź, czy faktura została już wysłana i ma numer KSeF. Zaktualizuj lokalną bazę danych o informacje z KSeF.
Jak sprawdzić, czy faktura została już wysłana?
Użyj endpointu POST /api/v2/invoices/query, aby sprawdzić istniejące faktury za zakres dat. Możesz również sprawdzić faktury w konkretnej sesji używając GET /api/v2/sessions/{referenceNumber}/invoices. Przed wysłaniem sprawdź lokalną bazę danych, jeśli masz synchronizację z KSeF.
Czy duplikaty są sprawdzane globalnie?
Tak, w KSeF API 2.0 duplikaty są sprawdzane globalnie w całym systemie KSeF, niezależnie od sesji. Próba ponownego wysłania tej samej faktury (NIP, RodzajFaktury, P_2) spowoduje błąd 440, nawet jeśli faktura była wysłana w innej sesji. W wersji 1.0 duplikaty były sprawdzane tylko w kontekście jednej sesji.
Jak uniknąć duplikatów po awarii systemu?
Po awarii systemu zsynchronizuj dane z KSeF przed ponownym wysłaniem faktur. Użyj endpointu GET /api/v2/sessions, aby pobrać listę sesji, następnie sprawdź faktury w każdej sesji. Przed ponownym wysłaniem sprawdź, czy faktura nie została już wysłana. System wykrywa duplikaty i zwraca błąd 440, co chroni przed podwójnym wystawieniem.