/ docs
ProdottoConoscenzaSviluppatori
Piattaforma Control
Transform API: convertire il formato del documento

Convertire documenti tra formati di fatturazione elettronica senza invio tramite l'endpoint Transform.

Con la Transform API converte un documento da un formato di fatturazione elettronica a un altro, senza inviarlo o salvarlo nella PSB. È utile per testare le trasformazioni prima di andare in produzione, o per convertire manualmente documenti per partner che richiedono un formato specifico.

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

Invii il documento sorgente come body con content-type application/xml. Il parametro targetFormat contiene l'URN del formato di destinazione desiderato.

Come funziona?
  1. Upload: invii il documento XML all'endpoint con il formato di destinazione desiderato
  2. Rilevamento: la PSB rileva automaticamente il formato sorgente sulla base del contenuto XML
  3. Trasformazione: il documento viene convertito nel formato di destinazione specificato
  4. Risposta: il documento convertito viene restituito direttamente come XML

Se il rilevamento automatico del formato sorgente non riesce, può specificarlo esplicitamente tramite il parametro sourceFormat:

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

Da NLCIUS a 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

Da UBL a CII (Cross Industry Invoice):

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

Attenzione: effettui l'URL-encoding dei valori URN nei parametri query. Il carattere # deve essere codificato come %23.

Trasformazioni supportate

Non tutte le trasformazioni sono disponibili. La PSB supporta le stesse trasformazioni disponibili durante l'invio e la ricezione di documenti. Le trasformazioni più utilizzate includono conversioni tra UBL e CII, e tra diverse varianti regionali (NLCIUS, XRechnung, Factur-X).

Quali trasformazioni sono esattamente disponibili dipende dalla tabella di trasformazione attuale della PSB. Consulti psb.econnect.eu per la panoramica più aggiornata.

Gestione degli errori
Codice di statoSignificato200 OKTrasformazione riuscita, documento convertito nel body della risposta400 Bad RequestFormato sorgente non riconosciuto o trasformazione non supportata422 UnprocessableIl documento non può essere convertito (dati mancanti o non validi)
Quando utilizzarla?
  • Test prima della produzione: verifichi che i documenti vengano trasformati correttamente prima di mettere in produzione l'integrazione
  • Conversione manuale: converta documenti per partner che richiedono un formato diverso
  • Confronto: generi lo stesso documento in più formati per verificare il mapping

Tecnico: la Transform API non salva il documento e non attiva webhook. Il documento viene trasformato in memoria e restituito direttamente.

Consulti la specifica API completa su psb.econnect.eu per tutti i formati supportati e i valori URN.

Provi nell'API

Correlati
PreviousValidate API
NextPanoramica VPD