/ docs
ProduktWiedzaDeweloperzy
Platforma Control
Transform API: konwersja formatu dokumentu

Konwersja dokumentów między formatami e-faktur bez wysyłki przez endpoint Transform.

Za pomocą Transform API mogą Państwo przekonwertować dokument z jednego formatu e-faktur na inny, bez jego wysyłania ani zapisywania w PSB. Jest to przydatne do testowania transformacji przed uruchomieniem produkcyjnym lub do ręcznej konwersji dokumentów dla partnerów wymagających określonego formatu.

Endpoint
POST /api/v1/generic/transform?targetFormat={URN}

Dokument źródłowy wysyła się jako body z content-type application/xml. Parametr targetFormat zawiera URN żądanego formatu docelowego.

Jak to działa?
  1. Upload: wysyłka dokumentu XML do endpointu z żądanym formatem docelowym
  2. Wykrywanie: PSB automatycznie wykrywa format źródłowy na podstawie zawartości XML
  3. Transformacja: dokument jest konwertowany do określonego formatu docelowego
  4. Odpowiedź: przekonwertowany dokument jest bezpośrednio zwracany jako XML

Jeśli automatyczne wykrycie formatu źródłowego nie powiedzie się, można go jawnie określić za pomocą parametru sourceFormat:

POST /api/v1/generic/transform?targetFormat={URN}&sourceFormat={URN}
Przykłady

Z NLCIUS do Peppol BIS Billing V3:

POST /api/v1/generic/transform?targetFormat=urn:cen.eu:en16931:2017%23compliant%23urn:fdc:peppol.eu:2017:poacc:billing:3.0

Z UBL do CII (Cross Industry Invoice):

POST /api/v1/generic/transform?targetFormat=urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100

Uwaga: wartości URN w parametrach zapytania należy zakodować w URL. Znak # musi być zakodowany jako %23.

Obsługiwane transformacje

Nie wszystkie transformacje są dostępne. PSB obsługuje te same transformacje, które są dostępne podczas wysyłania i odbierania dokumentów. Najczęściej stosowane transformacje obejmują konwersje między UBL i CII oraz między różnymi wariantami regionalnymi (NLCIUS, XRechnung, Factur-X).

Dokładnie dostępne transformacje zależą od aktualnej tabeli transformacji PSB. Aktualny przegląd dostępny jest na psb.econnect.eu.

Obsługa błędów
Kod statusuZnaczenie200 OKTransformacja udana, przekonwertowany dokument w ciele odpowiedzi400 Bad RequestFormat źródłowy nierozpoznany lub transformacja nieobsługiwana422 UnprocessableDokument nie może zostać przekonwertowany (brakujące lub nieprawidłowe dane)
Kiedy stosować?
  • Testy przed produkcją: sprawdzenie, czy dokumenty są prawidłowo transformowane przed uruchomieniem integracji produkcyjnej
  • Ręczna konwersja: konwersja dokumentów dla partnerów wymagających innego formatu
  • Porównanie: generowanie tego samego dokumentu w wielu formatach w celu weryfikacji mapowania

Techniczne: Transform API nie zapisuje dokumentu i nie wyzwala webhooków. Dokument jest transformowany w pamięci i bezpośrednio zwracany.

Pełna specyfikacja API dostępna jest na psb.econnect.eu ze wszystkimi obsługiwanymi formatami i wartościami URN.

Wypróbuj w API

Powiązane
PreviousValidate API
NextPrzegląd VPD