KSeF API query metadata – problemy z filtrowaniem faktur po dacie
Filtrowanie faktur przez query/metadata
Endpoint POST /invoices/query/metadata umożliwia wyszukiwanie faktur na podstawie różnych kryteriów, w tym zakresu dat, typu podmiotu i innych parametrów. Pola subjectType i dateRange są wymagane w każdym zapytaniu, a maksymalny dozwolony zakres dat wynosi 3 miesiące.
Parametr dateRange.dateType przyjmuje jedną z trzech wartości: Issue (data wystawienia faktury, zapisana w samej fakturze XML), Invoicing (data przyjęcia faktury do przetwarzania przez KSeF) lub PermanentStorage (data trwałego zapisu faktury w repozytorium KSeF). Nie ma osobnego typu dla "daty nabycia" - to częste błędne założenie.
Parametr subjectType określa typ podmiotu w kontekście wyszukiwania i musi być zapisany dokładnie w formie: Subject1 (podmiot wystawiający fakturę - sprzedawca), Subject2 (podmiot przyjmujący fakturę - nabywca), Subject3 (podmiot trzeci), SubjectAuthorized (podmiot upoważniony). Wielkość liter ma znaczenie - wartości muszą zaczynać się wielką literą.
Typowe problemy z filtrowaniem: faktury nie są widoczne w wynikach mimo że istnieją w KSeF (prawdopodobnie użyto niewłaściwego dateType - data wystawienia różni się od daty przyjęcia lub zapisu), przekroczony maksymalny zakres 3 miesięcy, nieprawidłowa wielkość liter w subjectType lub dateType (API oczekuje PascalCase, np. Subject1, Issue).
Instrukcja krok po kroku
1. Ustal, po jakiej dacie chcesz filtrować
KSeF rozróżnia trzy typy dat: datę wystawienia faktury (zapisaną w samym dokumencie XML), datę przyjęcia faktury do przetwarzania przez KSeF oraz datę trwałego zapisu w repozytorium. Zdecyduj, która z nich odpowiada Twojemu przypadkowi użycia, zanim ustawisz filtr.
2. Użyj poprawnego dateType
Wybierz odpowiedni dateType w parametrze dateRange: Issue dla daty wystawienia faktury, Invoicing dla daty przyjęcia faktury do przetwarzania przez KSeF, PermanentStorage dla daty trwałego zapisu w repozytorium KSeF. Nie istnieje typ "acquisition" (data nabycia) - to częsty błąd wynikający z mylnego skojarzenia z terminologią podatkową.
3. Ustaw poprawny zakres dat
Ustaw zakres dat (from i to) w parametrze dateRange zgodnie z wybranym dateType. Maksymalny dozwolony okres to 3 miesiące (w strefie UTC lub Europe/Warsaw). Format daty: ISO 8601, np. "2026-01-06T17:21:08+00:00" (dopuszczalne są też warianty z sufiksem Z lub bez offsetu, interpretowane jako czas lokalny Europe/Warsaw).
4. Wybierz odpowiedni subjectType
Wybierz odpowiedni subjectType zgodnie z kontekstem, pamiętając o wielkości liter (PascalCase): 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 upoważnionego. 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 wybrany dateType odpowiada temu, czego szukasz, czy zakres dat nie przekracza 3 miesięcy, czy subjectType jest zgodny z kontekstem i zapisany poprawną wielkością liter, 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ź, czy wybrany dateType (Issue, Invoicing lub PermanentStorage) odpowiada temu, czego szukasz - to trzy różne daty i faktura może mieścić się w zakresie dla jednej, a nie mieścić się dla innej. Sprawdź też, czy zakres dat nie przekracza dozwolonego maksimum 3 miesięcy, oraz czy subjectType jest zgodny z kontekstem logowania i zapisany poprawną wielkością liter (np. Subject1, nie subject1).
Różnica między datą wystawienia, przyjęcia i trwałego zapisu
dateType: Issue to data wystawienia faktury zapisana w samym dokumencie XML. dateType: Invoicing to data przyjęcia faktury do przetwarzania przez KSeF. dateType: PermanentStorage to data trwałego zapisu faktury w repozytorium KSeF. Te trzy daty mogą się różnić dla tej samej faktury - wybierz dateType odpowiadający Twojemu przypadkowi użycia.
Który subjectType użyć?
Wybierz subjectType zgodnie z kontekstem, pamiętając o wielkości liter: 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.
Format daty w dateRange
Format daty w parametrze dateRange (from i to) to ISO 8601, np. "2026-01-06T17:21:08+00:00". Dopuszczalne są warianty z sufiksem Z (UTC), z jawnym offsetem lub bez offsetu (interpretowane jako czas lokalny Europe/Warsaw). Upewnij się, że zakres nie przekracza 3 miesięcy i obejmuje datę odpowiadającą wybranemu dateType.
Trzy typy dat w dateRange
Parametr dateRange.dateType przyjmuje jedną z trzech wartości: Issue (data wystawienia faktury, zapisana w fakturze XML), Invoicing (data przyjęcia faktury do przetwarzania przez KSeF) lub PermanentStorage (data trwałego zapisu faktury w repozytorium KSeF). Te trzy daty mogą się różnić dla tej samej faktury. Jeśli faktura nie pojawia się w wynikach, sprawdź w pierwszej kolejności, czy wybrany dateType odpowiada dacie, której faktycznie szukasz.
Parametry filtrowania
dateRange (wymagany): obiekt z polami dateType (Issue, Invoicing lub PermanentStorage), from (data początkowa, wymagana) i to (data końcowa, opcjonalna - domyślnie bieżący czas UTC), oba w formacie ISO 8601; maksymalny dozwolony zakres to 3 miesiące. subjectType (wymagany): typ podmiotu w kontekście wyszukiwania - Subject1 (sprzedawca), Subject2 (nabywca), Subject3 (podmiot trzeci), SubjectAuthorized (podmiot upoważniony); wartości są wrażliwe na wielkość liter (PascalCase). Dodatkowo dostępne są opcjonalne filtry, m.in. ksefNumber, invoiceNumber, sellerNip, buyerIdentifier, currencyCodes, invoicingMode, amount - zgodnie z dokumentacją OpenAPI.
Typowe błędy
Użycie niewłaściwego dateType: Issue, Invoicing i PermanentStorage to trzy różne daty - wybór złej powoduje brak wyników mimo że faktura istnieje. Nieprawidłowa wielkość liter: subjectType i dateType wymagają PascalCase (np. Subject1, Issue), nie małych liter. Przekroczony zakres dat: maksymalny dozwolony okres to 3 miesiące. Nieprawidłowy format daty: format daty musi być ISO 8601 (np. "2026-01-06T17:21:08+00:00"). Brak uprawnień: upewnij się, że masz uprawnienie InvoiceRead do odczytu faktur w danym kontekście.
Przykładowe zapytanie
Przykładowe zapytanie do POST /invoices/query/metadata: {"subjectType": "Subject1", "dateRange": {"dateType": "PermanentStorage", "from": "2026-01-06T00:00:00+00:00", "to": "2026-01-08T23:59:59+00:00"}}. To zapytanie wyszukuje faktury, w których jesteś sprzedawcą (Subject1), z datą trwałego zapisu w KSeF w podanym zakresie. Jeśli zależy Ci na dacie wystawienia z dokumentu, zamień dateType na Issue.
FAQ
Dlaczego faktury nie są widoczne w wynikach filtrowania?
Sprawdź, czy wybrany dateType (Issue, Invoicing lub PermanentStorage) odpowiada dacie, której faktycznie szukasz - to trzy różne daty, które mogą różnić się dla tej samej faktury. Sprawdź też, czy zakres dat nie przekracza dozwolonego maksimum 3 miesięcy, czy subjectType i dateType są zapisane poprawną wielkością liter (PascalCase, np. Subject1, Issue) oraz czy masz uprawnienia do odczytu faktur (InvoiceRead).
Jaka jest różnica między datą wystawienia, przyjęcia i trwałego zapisu?
dateType: Issue to data wystawienia faktury zapisana w dokumencie XML. dateType: Invoicing to data przyjęcia faktury do przetwarzania przez KSeF. dateType: PermanentStorage to data trwałego zapisu faktury w repozytorium KSeF. Wybierz dateType odpowiadający Twojemu przypadkowi użycia - nie istnieje osobny typ daty nabycia.
Który subjectType użyć do filtrowania?
Wybierz subjectType zgodnie z kontekstem, pamiętając o wielkości liter: 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.
Jak sprawdzić datę wystawienia faktury?
Datę wystawienia faktury znajdziesz w fakturze XML (pole P_1) lub w metadanych zwróconych przez dateType: Issue. Możesz też pobrać pojedynczą fakturę przez endpoint GET /invoices/ksef/{ksefNumber} i sprawdzić datę wystawienia w XML.
Format daty w dateRange
Format daty w parametrze dateRange (from i to) to ISO 8601, np. "2026-01-06T17:21:08+00:00". Dopuszczalne są warianty z sufiksem Z (UTC), z jawnym offsetem lub bez offsetu (interpretowane jako czas lokalny Europe/Warsaw). Maksymalny dozwolony zakres to 3 miesiące.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.