KSeF API query metadata – problemy z filtrowaniem faktur po dacie
POST /api/v2/invoices/query/metadata wymaga zrozumienia różnicy między datą wystawienia faktury (issueDate) a datą wysłania do KSeF. Filtrowanie po dateType: "issue" używa daty wystawienia, nie daty wysłania.Filtrowanie faktur przez query/metadata
Endpoint POST /api/v2/invoices/query/metadata umożliwia wyszukiwanie faktur na podstawie różnych kryteriów, w tym zakresu dat, typu podmiotu i innych parametrów. Filtrowanie po dacie wymaga zrozumienia różnicy między datą wystawienia faktury (issueDate) a datą wysłania do KSeF.
Parametr dateType: "issue" filtruje faktury po dacie wystawienia (issueDate), która jest zapisana w fakturze XML, a nie po dacie wysłania do KSeF. Jeśli faktura została wystawiona wcześniej niż wysłana, może nie być widoczna w wynikach filtrowania po dacie wysłania.
Parametr subjectType określa typ podmiotu w kontekście wyszukiwania: subject1 (podmiot wystawiający fakturę), subject2 (podmiot przyjmujący fakturę), subject3 (podmiot trzeci), subjectAuthorized (podmiot uprawniony). Wybór subjectType zależy od kontekstu, w którym jesteś zalogowany.
Typowe problemy z filtrowaniem: faktury nie są widoczne w wynikach mimo że istnieją w KSeF (prawdopodobnie data wystawienia jest inna niż data wysłania), nieprawidłowy zakres dat (użycie daty wysłania zamiast daty wystawienia), nieprawidłowy subjectType (niezgodny z kontekstem logowania).
Instrukcja krok po kroku
1. Sprawdź datę wystawienia faktury
Przed filtrowaniem sprawdź datę wystawienia faktury (issueDate) w fakturze XML lub w metadanych faktury. Data wystawienia może różnić się od daty wysłania do KSeF. Użyj daty wystawienia w parametrze dateRange, jeśli używasz dateType: "issue".
2. Użyj poprawnego dateType
Wybierz odpowiedni dateType w parametrze dateRange: "issue" dla daty wystawienia faktury (issueDate), "acquisition" dla daty nabycia, inne typy dat zgodnie z dokumentacją API. Pamiętaj, że dateType: "issue" używa daty wystawienia z faktury, nie daty wysłania do KSeF.
3. Ustaw poprawny zakres dat
Ustaw zakres dat (from i to) w parametrze dateRange, uwzględniając datę wystawienia faktury, nie datę wysłania. Jeśli faktura została wystawiona wcześniej niż wysłana, użyj daty wystawienia w zakresie. Format daty: ISO 8601 (np. "2026-01-06T17:21:08.022Z").
4. Wybierz odpowiedni subjectType
Wybierz odpowiedni subjectType zgodnie z kontekstem: "subject1" jeśli jesteś wystawcą faktury (logujesz się w kontekście NIP wystawcy), "subject2" jeśli jesteś nabywcą faktury (logujesz się w kontekście NIP nabywcy), "subject3" dla podmiotu trzeciego, "subjectAuthorized" dla podmiotu uprawnionego. Sprawdź, czy subjectType jest zgodny z kontekstem, w którym jesteś zalogowany.
5. Zweryfikuj wyniki
Po wykonaniu zapytania zweryfikuj wyniki. Jeśli faktury nie są widoczne, sprawdź: czy data wystawienia faktury mieści się w zakresie dat, czy subjectType jest zgodny z kontekstem, czy masz uprawnienia do odczytu faktur (InvoiceRead), czy faktury rzeczywiście istnieją w KSeF (sprawdź pojedynczą fakturę po numerze KSeF).
Najczęstsze problemy i rozwiązania
Faktury nie są widoczne w wynikach mimo że istnieją w KSeF
Sprawdź datę wystawienia faktury (issueDate), nie datę wysłania. Jeśli używasz dateType: "issue", zakres dat musi obejmować datę wystawienia faktury. Jeśli faktura została wystawiona wcześniej niż wysłana, użyj daty wystawienia w zakresie dat. Sprawdź również, czy subjectType jest zgodny z kontekstem logowania.
Różnica między datą wystawienia a datą wysłania
Data wystawienia (issueDate) to data zapisana w fakturze XML, która może być wcześniejsza niż data wysłania do KSeF. Parametr dateType: "issue" filtruje po dacie wystawienia, nie po dacie wysłania. Użyj daty wystawienia w zakresie dat, jeśli używasz dateType: "issue".
Który subjectType użyć?
Wybierz subjectType zgodnie z kontekstem: "subject1" jeśli jesteś wystawcą faktury (logujesz się w kontekście NIP wystawcy), "subject2" jeśli jesteś nabywcą faktury (logujesz się w kontekście NIP nabywcy). Sprawdź, czy subjectType jest zgodny z kontekstem, w którym jesteś zalogowany. Jeśli nie jesteś pewien, spróbuj obu opcji.
Format daty w dateRange
Format daty w parametrze dateRange (from i to) to ISO 8601 (np. "2026-01-06T17:21:08.022Z"). Upewnij się, że format daty jest poprawny i że zakres dat obejmuje datę wystawienia faktury (jeśli używasz dateType: "issue"). Sprawdź również strefę czasową (UTC vs lokalna).
Różnica między datą wystawienia a datą wysłania
Data wystawienia (issueDate) to data zapisana w fakturze XML, która może być wcześniejsza niż data wysłania do KSeF. Parametr dateType: "issue" w dateRange filtruje faktury po dacie wystawienia, nie po dacie wysłania. Jeśli faktura została wystawiona wcześniej niż wysłana, może nie być widoczna w wynikach filtrowania po dacie wysłania. Zawsze używaj daty wystawienia w zakresie dat, jeśli używasz dateType: "issue".
Parametry filtrowania
dateRange: obiekt z polami dateType (typ daty: "issue", "acquisition", itd.), from (data początkowa w formacie ISO 8601), to (data końcowa w formacie ISO 8601). subjectType: typ podmiotu w kontekście wyszukiwania - "subject1" (wystawca), "subject2" (nabywca), "subject3" (podmiot trzeci), "subjectAuthorized" (podmiot uprawniony). Inne parametry: zgodnie z dokumentacją OpenAPI mogą być dostępne dodatkowe parametry filtrowania (NIP kontrahenta, typ faktury, itd.).
Typowe błędy
Użycie daty wysłania zamiast daty wystawienia: jeśli używasz dateType: "issue", zakres dat musi obejmować datę wystawienia faktury, nie datę wysłania. Nieprawidłowy subjectType: subjectType musi być zgodny z kontekstem logowania (NIP wystawcy vs NIP nabywcy). Nieprawidłowy format daty: format daty musi być ISO 8601 (np. "2026-01-06T17:21:08.022Z"). Brak uprawnień: upewnij się, że masz uprawnienie InvoiceRead do odczytu faktur w danym kontekście.
Przykładowe zapytanie
Przykładowe zapytanie do POST /api/v2/invoices/query/metadata: {"subjectType": "subject1", "dateRange": {"dateType": "issue", "from": "2026-01-06T00:00:00Z", "to": "2026-01-08T23:59:59Z"}}. To zapytanie wyszukuje faktury wystawione (subject1) w zakresie dat wystawienia od 6 do 8 stycznia 2026. Pamiętaj, że zakres dat musi obejmować datę wystawienia faktury, nie datę wysłania.
FAQ
Dlaczego faktury nie są widoczne w wynikach filtrowania?
Sprawdź datę wystawienia faktury (issueDate), nie datę wysłania. Jeśli używasz dateType: "issue", zakres dat musi obejmować datę wystawienia faktury. Jeśli faktura została wystawiona wcześniej niż wysłana, użyj daty wystawienia w zakresie dat. Sprawdź również, czy subjectType jest zgodny z kontekstem logowania i czy masz uprawnienia do odczytu faktur.
Jaka jest różnica między datą wystawienia a datą wysłania?
Data wystawienia (issueDate) to data zapisana w fakturze XML, która może być wcześniejsza niż data wysłania do KSeF. Parametr dateType: "issue" filtruje po dacie wystawienia, nie po dacie wysłania. Zawsze używaj daty wystawienia w zakresie dat, jeśli używasz dateType: "issue".
Który subjectType użyć do filtrowania?
Wybierz subjectType zgodnie z kontekstem: "subject1" jeśli jesteś wystawcą faktury (logujesz się w kontekście NIP wystawcy), "subject2" jeśli jesteś nabywcą faktury (logujesz się w kontekście NIP nabywcy). Sprawdź, czy subjectType jest zgodny z kontekstem, w którym jesteś zalogowany. Jeśli nie jesteś pewien, spróbuj obu opcji.
Jak sprawdzić datę wystawienia faktury?
Data wystawienia faktury (issueDate) jest zapisana w fakturze XML w polu P_1 (DataWytworzeniaFa) lub w metadanych faktury. Możesz pobrać fakturę przez endpoint GET /api/v2/invoices/ksef/{ksefNumber} i sprawdzić datę wystawienia w XML lub w metadanych. Użyj tej daty w zakresie dateRange, jeśli używasz dateType: "issue".
Format daty w dateRange
Format daty w parametrze dateRange (from i to) to ISO 8601 (np. "2026-01-06T17:21:08.022Z"). Upewnij się, że format daty jest poprawny i że zakres dat obejmuje datę wystawienia faktury (jeśli używasz dateType: "issue"). Sprawdź również strefę czasową (UTC vs lokalna) - zaleca się używanie UTC.