ProductKennisDevelopers
Platform Control
Transform API: documentformaat converteren

Documenten converteren tussen e-factuurformaten zonder te verzenden via het Transform endpoint.

Met de Transform API converteer je een document van het ene e-factuurformaat naar het andere, zonder het te verzenden of op te slaan in de PSB. Dat is handig om transformaties te testen voordat je live gaat, of om handmatig documenten om te zetten voor partners die een specifiek formaat vereisen.

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

Stuur het brondocument als body mee met content-type application/xml. De targetFormat-parameter bevat de URN van het gewenste doelformaat.

Hoe werkt het?
  1. Upload: stuur het XML-document naar het endpoint met het gewenste doelformaat
  2. Detectie: de PSB detecteert automatisch het bronformaat op basis van de XML-inhoud
  3. Transformatie: het document wordt geconverteerd naar het opgegeven doelformaat
  4. Response: het geconverteerde document wordt direct geretourneerd als XML

Als de automatische detectie van het bronformaat niet lukt, kun je het expliciet opgeven via de sourceFormat-parameter:

POST /api/v1/generic/transform?targetFormat={URN}&sourceFormat={URN}
Voorbeelden

Van NLCIUS naar 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

Van UBL naar CII (Cross Industry Invoice):

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

Let op: URL-encode de URN-waarden in de queryparameters. Het #-teken moet worden geencodeerd als %23.

Ondersteunde transformaties

Niet alle transformaties zijn beschikbaar. De PSB ondersteunt dezelfde transformaties als bij het verzenden en ontvangen van documenten. De meest gebruikte transformaties omvatten conversies tussen UBL en CII, en tussen verschillende regionale varianten (NLCIUS, XRechnung, Factur-X).

Welke transformaties precies beschikbaar zijn, hangt af van de actuele transformatietabel van de PSB. Raadpleeg psb.econnect.eu voor het meest recente overzicht.

Foutafhandeling
StatuscodeBetekenis200 OKTransformatie geslaagd, geconverteerd document in response body400 Bad RequestBronformaat niet herkend of transformatie niet ondersteund422 UnprocessableDocument kan niet worden geconverteerd (ontbrekende of ongeldige data)
Wanneer gebruiken?
  • Testen voor productiegang: controleer of je documenten correct worden getransformeerd voordat je de integratie live zet
  • Handmatige conversie: converteer documenten voor partners die een ander formaat vereisen
  • Vergelijking: genereer hetzelfde document in meerdere formaten om de mapping te verifiëren

Technisch: De Transform API slaat het document niet op en triggert geen webhooks. Het document wordt in-memory getransformeerd en direct geretourneerd.

Veelgestelde vragen
Welke formaattransformaties ondersteunt de Transform API?

De Transform API ondersteunt dezelfde transformaties als bij het reguliere verzenden en ontvangen via de PSB. De meest gebruikte conversies zijn tussen UBL en CII, en tussen regionale varianten zoals NLCIUS, XRechnung en Factur-X. Het exacte overzicht van beschikbare transformaties vind je op psb.econnect.eu.

Wordt het document opgeslagen na een transformatie?

Nee, het document wordt volledig in-memory getransformeerd en direct als XML geretourneerd. Er vindt geen opslag plaats in de PSB en er worden geen webhooks getriggerd.

Wat gebeurt er als het bronformaat niet automatisch wordt herkend?

Als de automatische detectie niet lukt, kun je het bronformaat expliciet meegeven via de sourceFormat-parameter. Geef de URN van het bronformaat mee naast de targetFormat-parameter. Wordt het formaat ook dan niet herkend, dan retourneert de API een 400 Bad Request.

Bekijk de volledige API-specificatie op psb.econnect.eu voor alle ondersteunde formaten en URN-waarden.

Probeer het in de API

Gerelateerd
PreviousValidate API
NextVPD-overzicht