TaxLayer
Technika2026-11-138 min czytaniaprzez TaxLayer Team

E-faktura przez API: automatyczna konwersja i walidacja CSV i XML do ZUGFeRD, XRechnung i PEPPOL

Obowiązek e-faktury najmocniej dotyka firmy z dużą liczbą faktur. Kto miesięcznie wystawia setki lub tysiące faktur, nie może ich przesyłać, sprawdzać i pobierać pojedynczo. Jednocześnie nie każdy ERP ma moduł e-faktury, a własne oprogramowanie musiałoby samo generować ZUGFeRD, XRechnung i PEPPOL, utrzymywać je w aktualnej wersji i sprawdzać pod kątem oficjalnych reguł. API wypełnia tę lukę: Państwa oprogramowanie dostarcza dane, a interfejs zwraca sprawdzone e-faktury. Ten poradnik pokazuje, jak to działa i na co zwracać uwagę przy wyborze.

> Krótka odpowiedź: API e-faktury przyjmuje dane faktur z Państwa systemu i zwraca gotowe pliki w formacie ZUGFeRD, XRechnung lub PEPPOL. Najbardziej niezawodne są dane ustrukturyzowane (CSV lub XML), ponieważ żadne wartości nie są zgadywane. Decydujące jest to, aby każdy plik był przed wydaniem sprawdzony pod kątem EN 16931 i reguł KoSIT. API TaxLayer oferuje w tym celu cztery punkty końcowe (status, konwersja CSV, konwersja XML, walidacja) i jest zawarte w taryfie Enterprise.

Dlaczego API zamiast pracy ręcznej

E-faktura to ustrukturyzowany zbiór danych zgodny z EN 16931. Ręczne jego tworzenie zajmuje na fakturę tylko kilka minut, ale przy dużych ilościach to dni w miesiącu. Dochodzą źródła błędów: nieprawidłowe kody jednostek, brakujące wymagane dane dla XRechnung, różnice zaokrągleń w zestawieniu podatku. API automatyzuje całą drogę:

  • Państwa system eksportuje dane faktur, na przykład nocą jako plik CSV.
  • Mały skrypt wysyła plik do interfejsu.
  • API generuje dla każdej faktury plik PDF ZUGFeRD, XRechnung lub PEPPOL.
  • Każdy plik jest sprawdzany, zanim wróci do Państwa. Błędne faktury wracają z uzasadnieniem zamiast jako nieprawidłowy plik.

Dzięki temu Państwa proces fakturowania pozostaje taki, jaki jest, a na końcu otrzymują Państwo prawidłową e-fakturę.

Jakie dane wejściowe: CSV, XML czy PDF

Najważniejsze pytanie przy automatyzacji brzmi, w jakiej formie dane są dostępne.

Dane wejścioweTypowe źródłoNiezawodność
CSVeksport z ERP, system magazynowy, arkuszbardzo wysoka, wartości są przejmowane dokładnie
XML (UBL, CII)istniejące e-faktury, nowoczesne systemybardzo wysoka, odczyt oparty na regułach
PDFwydruk faktury z dowolnych systemówdobra, ale tylko z weryfikacją przez człowieka

CSV to najprostsza droga dla systemów bez modułu e-faktury. Prawie każdy ERP potrafi wyeksportować faktury jako tabelę. W szablonie TaxLayer każda pozycja znajduje się w osobnym wierszu, a dane nagłówkowe (sprzedawca, nabywca, płatność) powtarzają się w każdym wierszu. Jeden plik może zawierać wiele faktur, pogrupowanych według numeru faktury.

XML opłaca się, gdy e-faktury już istnieją i ma się zmienić tylko format. Typowy przypadek to XRechnung dla urzędu, którą klient chce dodatkowo mieć jako czytelny plik PDF ZUGFeRD, albo faktura ZUGFeRD, która ma zostać wysłana przez sieć PEPPOL. UBL (XRechnung, PEPPOL BIS) i CII (ZUGFeRD, Factur-X) są odczytywane na podstawie reguł, bez AI.

PDF to dane wejściowe, które obiecują najwięcej wygody, a dają najmniej pewności. Nowoczesna AI bardzo dobrze odczytuje dane faktur z plików PDF, ale nie bezbłędnie. Zamieniona cyfra w kwocie lub błędnie rozpoznana stawka podatku trafiłaby w przeciwnym razie niesprawdzona do prawnie wiążącej faktury. TaxLayer dlatego świadomie oferuje PDF tylko w aplikacji internetowej, z etapem weryfikacji przed wydaniem i w partii do 50 faktur (Enterprise Plus: 70). Dlaczego sam plik PDF nie jest e-fakturą, wyjaśnia artykuł Excel i PDF nie są e-fakturą.

Walidacja: element, o którym wielu zapomina

E-faktura jest e-fakturą dopiero wtedy, gdy spełnia reguły. Dla Niemiec są to EN 16931, a dla XRechnung dodatkowo niemieckie reguły biznesowe (BR-DE), na przykład numer telefonu i adres e-mail sprzedawcy. Te reguły sprawdza Koordinierungsstelle für IT-Standards (KoSIT) za pomocą oficjalnego zestawu reguł, którego używają także publiczni odbiorcy faktur.

W przypadku API proszę zwrócić uwagę na cztery punkty:

  • Walidacja przed wydaniem: każdy wygenerowany plik powinien przechodzić przez pełny zestaw reguł, nie tylko przez schemat XML.
  • Automatycznie znaczy automatycznie: nawet najlepsza walidacja potwierdza tylko formę. W TaxLayer wszystkie kontrole przebiegają maszynowo i nie ma kontroli ręcznej; za treść (kwoty, stawki podatku, odbiorcę) odpowiadają Państwo jak dotychczas sami.
  • Fail-closed: jeśli usługa walidacji jest niedostępna, API nie może wydać niesprawdzonego pliku. API TaxLayer odpowiada wtedy kodem 503 i niczego nie nalicza; Państwa skrypt po prostu ponawia zapytanie.
  • Zrozumiałe błędy: zamiast „nieprawidłowe” potrzebują Państwo kodu reguły i komunikatu, na przykład BR-DE-6 dla brakującego numeru telefonu. Kody można sprawdzić w spisie kodów błędów XRechnung.

Punkt końcowy walidacji przydaje się także przy fakturach przychodzących: zanim faktura dostawcy trafi do księgowości, pokazuje, czy spełnia reguły. Dla pojedynczych plików dostępny jest dodatkowo bezpłatny walidator w przeglądarce.

Bezpieczeństwo i ochrona danych

API faktur przetwarza wrażliwe dane. Warto zapytać o:

  • Zarządzanie kluczami: klucze API powinny być przechowywane wyłącznie jako hash i dawać się w każdej chwili unieważnić. W TaxLayer klucz widoczny jest jednorazowo przy tworzeniu; unieważniony klucz natychmiast przestaje działać.
  • Brak dostępu z przeglądarki: klucze należą na serwer. API TaxLayer nie wysyła nagłówków CORS, więc wywołania ze stron internetowych nie są możliwe.
  • Przechowywanie: pliki faktur nie powinny być zapisywane. Dziennik dostępu powinien zawierać tylko dane techniczne.
  • Lokalizacja: przetwarzanie w UE, w TaxLayer we Frankfurcie.

Jak wygląda wywołanie

Wywołanie to proste zapytanie HTTP: wysyłają Państwo plik CSV metodą POST na /v1/convert/csv?format=xrechnung i wpisują swój klucz w nagłówku Authorization: Bearer tlk_…. W curl to jedna linijka, w Pythonie lub Node.js około dziesięciu.

Odpowiedź jest w formacie JSON: dla każdej faktury gotowy plik (XML jako tekst lub PDF ZUGFeRD jako Base64) oraz lista faktur, których nie udało się wygenerować, z podaniem przyczyny. Na Państwa limit liczą się tylko pomyślnie wygenerowane faktury. Wszystkie punkty końcowe, parametry, kody błędów i przykłady w Node.js i Pythonie znajdą Państwo w dokumentacji API.

Lista kontrolna na start

  1. Proszę sprawdzić, czy Państwa system potrafi eksportować faktury jako CSV lub XML.
  2. Proszę pobrać szablon CSV z dokumentacji i przypisać do niego swoje kolumny.
  3. Dla XRechnung proszę uzupełnić Leitweg-ID lub referencję nabywcy, telefon, e-mail, kod pocztowy i miejscowość sprzedawcy oraz kod pocztowy, miejscowość i adres e-mail lub numer USt-IdNr. nabywcy.
  4. Proszę utworzyć w koncie w sekcji „API (Beta)” klucz i przetestować go wywołaniem statusu.
  5. Proszę wysłać pierwszy plik i przeanalizować pole errors, zanim przejdą Państwo na przebieg nocny.

---

E-faktura nie musi być projektem z własnym programowaniem. Dzięki API TaxLayer Państwa system dostarcza dane, a Państwo otrzymują z powrotem sprawdzone pliki ZUGFeRD, XRechnung i PEPPOL. API jest zawarte w Enterprise i Enterprise Plus i jest obecnie dostępne jako beta. Pytania prosimy kierować na info@taxlayer.de.

Najczęściej zadawane pytania

Czym jest API e-faktury?

Interfejsem programistycznym, do którego Państwa oprogramowanie wysyła dane faktur i który zwraca gotowe e-faktury w wybranym formacie, na przykład ZUGFeRD, XRechnung lub PEPPOL. Oszczędzają Państwo własny generator, aktualizowanie wersji formatów i utrzymanie walidatora.

Jakie dane wejściowe najlepiej nadają się do automatyzacji?

Dane ustrukturyzowane, czyli CSV lub XML. Wartości są przejmowane dokładnie, nic nie trzeba zgadywać. Dane z plików PDF można wprawdzie odczytywać za pomocą AI, ale nie jest to wolne od błędów i wymaga etapu weryfikacji przez człowieka.

Jak upewnić się, że wygenerowana e-faktura jest prawidłowa?

Każdy plik powinien być przed wydaniem sprawdzony oficjalnymi regułami, czyli EN 16931, a dla XRechnung dodatkowo niemieckimi regułami BR-DE. API TaxLayer sprawdza każdy plik regułami walidacyjnymi KoSIT i wydaje tylko pliki, które przeszły walidację.

Czy za pomocą API mogę też sprawdzać faktury od dostawców?

Tak. Punkt końcowy walidacji przyjmuje XML (UBL lub CII) oraz pliki PDF ZUGFeRD i zwraca wynik z kodami reguł, na przykład BR-CO-15 dla nieprawidłowej sumy łącznej. Dzięki temu błędne faktury przychodzące wychodzą na jaw przed zaksięgowaniem.

Ile kosztuje API TaxLayer?

Jest zawarte w taryfach Enterprise i Enterprise Plus. Konwersje są wliczane do tego samego miesięcznego limitu co w aplikacji internetowej, a walidacje mają własny limit dzienny.

Czy potrzebuję umiejętności programistycznych?

Odrobinę. Wywołanie to proste zapytanie HTTP, które można wysłać za pomocą curl, krótkiego skryptu w Pythonie lub Node.js albo z wielu systemów ERP. Dokumentacja zawiera przykłady do skopiowania.

Konwertuj swoje faktury PDF teraz

Wypróbuj TaxLayer za darmo – 2 konwersje miesięcznie, bez karty kredytowej.

Rozpocznij