KSeF API problemy z namespace XML – prefix tns: w fakturach
Problemy z namespace XML w fakturach KSeF
Faktury pobierane z KSeF API mogą występować w dwóch różnych formatach namespace XML: z prefixem tns: (np. <tns:Faktura xmlns:tns="http://crd.gov.pl/wzor/2025/06/25/13775/">) oraz bez prefixu z domyślną przestrzenią nazw (np. <Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">).
Oba formaty są poprawne zgodnie ze specyfikacją XML i XSD, ale różne systemy generujące faktury mogą używać różnych formatów. Prefix tns: (target namespace) jest powszechnie używany w schematach XSD do odwoływania się do elementów z docelowej przestrzeni nazw.
Parser XML musi obsługiwać oba formaty, aby poprawnie przetwarzać wszystkie faktury z KSeF. Niektóre biblioteki XML mogą wymagać dodatkowej konfiguracji do obsługi namespace z prefixami.
Problem z namespace może wystąpić zarówno przy pobieraniu faktur z KSeF, jak i przy generowaniu faktur do wysłania. Ważne jest, aby parser był odporny na różne formaty namespace.
Instrukcja krok po kroku
1. Zidentyfikuj format namespace w fakturze
Sprawdź deklarację namespace w elemencie głównym faktury. Faktura może mieć: prefix tns: z xmlns:tns="http://crd.gov.pl/wzor/2025/06/25/13775/" (format z prefixem) lub domyślną przestrzeń nazw xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/" (format bez prefixu). Oba formaty są poprawne.
2. Skonfiguruj parser do obsługi namespace
Skonfiguruj parser XML do obsługi namespace. Większość bibliotek XML (lxml, XmlDocument, javax.xml) obsługuje namespace, ale może wymagać dodatkowej konfiguracji. Upewnij się, że parser rozpoznaje zarówno elementy z prefixem tns: jak i bez prefixu, jeśli przestrzeń nazw jest zadeklarowana jako domyślna.
3. Użyj zapytań XPath z namespace
Jeśli używasz XPath do wyszukiwania elementów, upewnij się, że zapytania uwzględniają namespace. Zarejestruj namespace w parserze (np. namespaceManager w .NET, NamespaceContext w Java) i używaj prefixów w zapytaniach XPath. Alternatywnie, użyj zapytań z pełną ścieżką namespace (local-name() i namespace-uri()).
4. Obsłuż oba formaty w kodzie
Zaimplementuj obsługę obu formatów namespace w kodzie parsowania. Sprawdź, czy element główny ma prefix tns: czy używa domyślnej przestrzeni nazw, i odpowiednio dostosuj zapytania XPath lub dostęp do elementów. Możesz użyć funkcji sprawdzających namespace elementu niezależnie od formatu.
5. Przetestuj parser na różnych formatach
Przetestuj parser na fakturach w obu formatach namespace. Pobierz przykładowe faktury z KSeF i sprawdź, czy parser poprawnie obsługuje oba formaty. Zweryfikuj, czy wszystkie elementy są poprawnie odczytywane niezależnie od formatu namespace.
Najczęstsze problemy i rozwiązania
Parser nie rozpoznaje elementów z prefixem tns:
Skonfiguruj parser XML do obsługi namespace. Zarejestruj namespace w parserze (np. namespaceManager w .NET, NamespaceContext w Java) i używaj prefixów w zapytaniach XPath. Alternatywnie, użyj zapytań z pełną ścieżką namespace (local-name() i namespace-uri()). Sprawdź dokumentację biblioteki XML dotyczącą obsługi namespace.
Niektóre faktury mają tns:, a inne nie
To normalne - różne systemy generujące faktury mogą używać różnych formatów namespace. Oba formaty są poprawne zgodnie ze specyfikacją XML. Parser musi obsługiwać oba formaty. Zaimplementuj sprawdzanie formatu namespace i odpowiednie dostosowanie zapytań XPath lub dostępu do elementów.
XPath nie znajduje elementów z namespace
Upewnij się, że zapytania XPath uwzględniają namespace. Zarejestruj namespace w parserze i używaj prefixów w zapytaniach (np. //tns:Faktura zamiast //Faktura). Alternatywnie, użyj zapytań z pełną ścieżką namespace używając local-name() i namespace-uri() (np. //*[local-name()='Faktura' and namespace-uri()='http://crd.gov.pl/wzor/2025/06/25/13775/']).
Jak sprawdzić, który format namespace jest używany?
Sprawdź deklarację namespace w elemencie głównym faktury. Jeśli element główny ma prefix tns: (np. <tns:Faktura xmlns:tns="...">), to używany jest format z prefixem. Jeśli element główny nie ma prefixu, ale ma xmlns="..." (np. <Faktura xmlns="...">), to używana jest domyślna przestrzeń nazw. Oba formaty są poprawne.
Formaty namespace w fakturach KSeF
Faktury KSeF mogą występować w dwóch formatach namespace: z prefixem tns: - <tns:Faktura xmlns:tns="http://crd.gov.pl/wzor/2025/06/25/13775/"> (wszystkie elementy mają prefix tns:), bez prefixu z domyślną przestrzenią nazw - <Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/"> (elementy nie mają prefixu, ale przestrzeń nazw jest zadeklarowana jako domyślna). Oba formaty są poprawne zgodnie ze specyfikacją XML i XSD. Prefix tns: (target namespace) jest powszechnie używany w schematach XSD.
Obsługa namespace w parserach XML
Większość bibliotek XML obsługuje namespace, ale może wymagać dodatkowej konfiguracji: .NET - użyj XmlNamespaceManager do rejestracji namespace i użyj prefixów w zapytaniach XPath, Java - użyj NamespaceContext do rejestracji namespace, Python lxml - namespace są obsługiwane automatycznie, ale możesz użyć prefixów w zapytaniach XPath. Sprawdź dokumentację biblioteki XML dotyczącą obsługi namespace.
Zapytania XPath z namespace
Jeśli używasz XPath do wyszukiwania elementów, upewnij się, że zapytania uwzględniają namespace. Z prefixem: zarejestruj namespace w parserze (np. namespaceManager.AddNamespace("tns", "http://crd.gov.pl/wzor/2025/06/25/13775/")) i używaj prefixów w zapytaniach (np. //tns:Faktura/tns:Naglowek). Bez prefixu: użyj zapytań z pełną ścieżką namespace używając local-name() i namespace-uri() (np. //*[local-name()='Faktura' and namespace-uri()='http://crd.gov.pl/wzor/2025/06/25/13775/']).
Najlepsze praktyki
Zaimplementuj obsługę obu formatów namespace w parserze. Sprawdź format namespace w elemencie głównym faktury i odpowiednio dostosuj zapytania XPath lub dostęp do elementów. Użyj funkcji sprawdzających namespace elementu niezależnie od formatu. Przetestuj parser na fakturach w obu formatach. Rozważ normalizację namespace przed parsowaniem (opcjonalnie) - konwersja do jednego formatu może ułatwić parsowanie, ale nie jest wymagana, ponieważ oba formaty są poprawne.
FAQ
Dlaczego niektóre faktury mają prefix tns:, a inne nie?
Różne systemy generujące faktury mogą używać różnych formatów namespace. Format z prefixem tns: (np. <tns:Faktura>) i format bez prefixu z domyślną przestrzenią nazw (np. <Faktura xmlns="...">) są oba poprawne zgodnie ze specyfikacją XML. Parser musi obsługiwać oba formaty.
Jak obsłużyć oba formaty namespace w parserze?
Skonfiguruj parser XML do obsługi namespace. Zarejestruj namespace w parserze (np. namespaceManager w .NET, NamespaceContext w Java) i używaj prefixów w zapytaniach XPath. Alternatywnie, użyj zapytań z pełną ścieżką namespace (local-name() i namespace-uri()). Sprawdź format namespace w elemencie głównym faktury i odpowiednio dostosuj zapytania.
XPath nie znajduje elementów z namespace - co robić?
Upewnij się, że zapytania XPath uwzględniają namespace. Zarejestruj namespace w parserze i używaj prefixów w zapytaniach (np. //tns:Faktura zamiast //Faktura). Alternatywnie, użyj zapytań z pełną ścieżką namespace używając local-name() i namespace-uri() (np. //*[local-name()='Faktura' and namespace-uri()='http://crd.gov.pl/wzor/2025/06/25/13775/']).
Czy mogę normalizować namespace przed parsowaniem?
Możesz normalizować namespace przed parsowaniem (konwersja do jednego formatu), ale nie jest to wymagane, ponieważ oba formaty są poprawne. Normalizacja może ułatwić parsowanie, ale dodaje dodatkowy krok przetwarzania. Zaleca się, aby parser obsługiwał oba formaty bezpośrednio.
Który format namespace jest zalecany?
Oba formaty są poprawne i akceptowane przez KSeF. Format z prefixem tns: jest powszechnie używany w schematach XSD, ale format bez prefixu z domyślną przestrzenią nazw jest również poprawny. Ważne jest, aby parser obsługiwał oba formaty, ponieważ faktury z KSeF mogą występować w obu formatach.
Powiązane tematy
Przydatne serwisy
Status KSeF
Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.