Documentazione API esterna V1

Converti documento fattura

Converti dati strutturati

Esegui polling dello stato task

Carica un documento fattura PDF, DOCX o TXT e avvia la conversione asincrona. Restituisce un task_id per il polling. I download PDF ibridi ZUGFeRD/Factur-X richiedono una sorgente PDF; per sorgenti DOCX/TXT richiedere risultati XML. Richiesta: multipart/form-data; file (binary, obbligatorio) — documento sorgente fattura PDF, DOCX o TXT; i vecchi DOC/RTF, immagini e altri file sono rifiutati; format (string, obbligatorio) — formato di output target; vedere la matrice dei formati sotto; profile (string, opzionale, consigliato per integrazioni deterministiche) — profilo di conformità esplicito. I default dipendono dal formato; i valori consentiti includono XRECHNUNG, PEPPOL, EN16931 e i profili ZUGFeRD/Factur-X supportati; jurisdiction (string, opzionale) — contesto di giurisdizione ISO 3166-1 alpha-2 esplicito usato per controlli di validazione/avviso; non sovrascrive il profilo; transaction_scope (string, opzionale) — contesto esplicito dell’ambito transazionale, ad esempio B2G; applicato al task in coda; delivery_channel (string, opzionale) — uno tra PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; applicato al task in coda; client_reference o external_invoice_id (string, opzionale) — riferimento fattura/job lato cliente restituito negli upload accettati e nelle risposte di stato task; source_system (string, opzionale) — etichetta dell’ERP o sistema di fatturazione upstream restituita negli upload accettati e nelle risposte di stato task; use_seller_master_data (boolean, opzionale) — se omesso vale il default del profilo tenant; false ignora i dati anagrafici venditore salvati per questa richiesta, true fornisce/usa i dati anagrafici venditore; seller_master_data (stringa oggetto JSON, opzionale) — dati venditore usati solo quando use_seller_master_data=true; supporta campi aziendali, indirizzo, fiscali, contatto e pagamento (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); ogni valore del profilo sostituisce il corrispondente valore estratto, i campi assenti dal profilo restano invariati e le differenze generano avvisi non bloccanti. Risposta: 202 Accepted.

Carica un PDF contenitore con dati fattura CSV, JSON, XML, XLSX o TXT e avvia la conversione asincrona da dati strutturati. Le parti data_file sono l’unica fonte semantica; il PDF non completa i campi fattura mancanti. Per ZUGFeRD/Factur-X viene usato come PDF contenitore, mentre per output orientati a XML viene conservato come artefatto PDF inviato. Usa una richiesta di conversione per fattura; ripeti data_file solo per export ERP divisi che descrivono la stessa fattura. Richiesta: multipart/form-data; pdf_file (binary, obbligatorio) — PDF contenitore usato per l’incorporamento ZUGFeRD/Factur-X e conservato per output orientati a XML; data_file (binary, obbligatorio, ripetibile) — dati fattura CSV, JSON, XML, XLSX o TXT usati come unica fonte semantica; .xls, PDF e file immagine sono rifiutati come data_file; ripeti per export header/righe divisi della stessa fattura; gli alias data_files e data_files[] sono accettati; dimensione totale dati strutturati — massimo 2 MB su tutte le parti data_file; format (string, obbligatorio) — formato output di destinazione; supporta XRECHNUNG, ZUGFERD, EN16931, UBL e CII; profile (string, opzionale, consigliato per integrazioni deterministiche) — profilo di conformità esplicito. Default in base al format; jurisdiction (string, opzionale) — contesto di giurisdizione ISO 3166-1 alpha-2 esplicito usato per controlli di validazione/avviso; non sovrascrive il profilo; transaction_scope (string, opzionale) — contesto esplicito dell’ambito transazionale, ad esempio B2G; applicato al task in coda; delivery_channel (string, opzionale) — uno tra PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; applicato al task in coda; client_reference o external_invoice_id (string, opzionale) — riferimento fattura/job lato cliente restituito negli upload accettati e nelle risposte di stato task; source_system (string, opzionale) — etichetta dell’ERP o sistema di fatturazione upstream restituita negli upload accettati e nelle risposte di stato task; use_seller_master_data (boolean, opzionale) — se omesso vale il default del profilo tenant; false ignora i dati anagrafici venditore salvati per questa richiesta, true fornisce/usa i dati anagrafici venditore; seller_master_data (stringa oggetto JSON, opzionale) — dati venditore usati solo quando use_seller_master_data=true; supporta campi aziendali, indirizzo, fiscali, contatto e pagamento (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); ogni valore del profilo sostituisce il corrispondente valore estratto, i campi assenti dal profilo restano invariati e le differenze generano avvisi non bloccanti. Risposta: 202 Accepted.

Esegui il polling dello stato corrente di un task di conversione. Restituisce pending, processing, completed o failed. I task completati includono diagnostica result_artifacts, così i client possono vedere quali artefatti XML/PDF sono disponibili, in cache e provati dalla validazione. I payload dei task completati possono includere voci aggiuntive _processing_warnings e _validation_warnings con ID delle regole SOURCE_CONTEXT_* quando le evidenze della fonte erano indisponibili, sospette o troncate; trattale come segnali di revisione, non come errori. Quando è failed, la risposta include un campo error con il motivo dell’errore. Richiesta: nessuno (GET); task_id (path, obbligatorio) — UUID restituito dall’endpoint di conversione; include_validation_report_html (query, opzionale) — true o false (default false); con true la risposta di stato include il report di validazione HTML sanificato dell’artefatto rigoroso corrente quando disponibile. Risposta: 200 OK.

Scarica il file generato (XML o PDF). La sintassi del risultato corrisponde al formato originale del task: XRECHNUNG/EN16931/UBL restituiscono UBL XML, CII/ZUGFERD restituiscono CII XML, e ZUGFERD + download=pdf restituisce un PDF/A-3 ibrido. Per altri formati, download=pdf può restituire un PDF renderizzato. Download ripetuti possono essere serviti da artefatti generati in cache quando la prova di validazione è ancora attuale. Durante l’elaborazione questo endpoint restituisce 202 TASK_NOT_READY; i problemi di validazione bloccanti restituiscono 422 VALIDATION_FAILED, le dipendenze non disponibili ma ripetibili restituiscono 503 e i fallimenti degli invarianti degli artefatti restituiscono 500, sempre senza corpo file. Richiesta: nessuno (GET); task_id (path, obbligatorio) — UUID restituito dall’endpoint di conversione; download (query, obbligatorio) — xml o pdf. Risposta: 200 OK.

Download the validation report tied to the current validated result artifact. The report is available only after strict conversion has produced a cached artifact with current validation proof, and returns 404 when no report is bound to the delivered artifact. Richiesta: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Risposta: 200 OK.

When seller master data is enabled, every supplied profile value replaces the corresponding extracted seller or payment value. Fields absent from the profile remain unchanged. Source differences are non-blocking review warnings.

Recupero di documentazione; nessuna modifica al comportamento a runtime. Il catalogo errori ora documenta codici di errore runtime prima non documentati, tra cui API_CREDIT_SERVICE_UNAVAILABLE, TASK_NOT_FOUND, INVALID_CLIENT_METADATA, INVALID_SELLER_MASTER_DATA, PROFILE_MISMATCH, ZUGFERD_SOURCE_PDF_REQUIRED, VALIDATION_REPORT_NOT_FOUND, VALIDATION_REPORT_FAILED, INVALID_QUERY_PARAMETER e METHOD_NOT_ALLOWED. I client che analizzano le risposte di errore tramite il campo code leggibile da macchina non richiedono modifiche; i client basati su un elenco fisso di codici devono aggiungere i valori appena documentati. Date del changelog corrette: il supporto per sorgenti DOCX/TXT è stato rilasciato il 2026-06-30, non il 2026-07-06.

I payload dei task completati possono includere voci aggiuntive _processing_warnings e _validation_warnings con ID delle regole SOURCE_CONTEXT_* quando le evidenze della fonte erano indisponibili, sospette o troncate prima dell’estrazione. Tratta le voci SOURCE_CONTEXT_* come segnali di revisione per la gestione delle eccezioni lato cliente; i download di artefatti rigorosi restano governati dalla prova di validazione e dai controlli sugli artefatti.

I fallimenti dei prerequisiti rigorosi ZUGFeRD (campi obbligatori mancanti per la generazione ibrida) ora falliscono come 422 VALIDATION_FAILED con gli ID delle regole bloccanti invece di un 503 ritentabile; indirizzali a un flusso di correzione dati, non a un ciclo di retry. Per i formati solo XML (XRECHNUNG, EN16931, UBL, CII) il rendering PDF è ora un artefatto di comodità best effort: download=xml resta autorevole e disponibile sui task completati, mentre download=pdf può risultare non disponibile se il rendering è fallito dopo l’emissione dell’XML. Le conversioni con conflitti di fonte bloccanti non risolti ora falliscono come 422 VALIDATION_FAILED con voci blocking_source_conflict invece di emettere un artefatto.

POST /api/v1/invoices:convert ora accetta documenti sorgente fattura PDF, DOCX e TXT nel campo file. I vecchi file DOC, RTF, immagini e altre sorgenti non supportate sono rifiutati prima dell’avvio della conversione. I download PDF ibridi ZUGFeRD/Factur-X richiedono ancora una sorgente PDF; usa download XML per conversioni da sorgenti DOCX/TXT. Aggiunta l’opzione include_validation_report_html=true su GET /api/v1/tasks/{task_id} per includere inline il report di validazione HTML sanificato quando disponibile. Gli upload di conversione ora accettano su entrambi gli endpoint i campi opzionali use_seller_master_data e seller_master_data, così i tenant approvati possono attivare dati anagrafici venditore salvati o limitati alla richiesta.

Aggiunto GET /api/v1/tasks/{task_id}/validation-report?download=html|xml per recuperare il report di validazione legato alla prova dell’artefatto risultato rigoroso corrente. Le risposte del report di validazione espongono gli header ID task, SHA-256 dell’artefatto, ID prova di validazione, ID prova del report, tipo di contenuto del report e ID di correlazione.

L’accesso External API è ora documentato come accesso approvato invece di creazione non controllata delle chiavi. Chiarito che nessuno SLA formale, credito di servizio o penale contrattuale si applica salvo accordo in un order form. format è ora obbligatorio su entrambi gli endpoint di conversione; valori mancanti restituiscono 400 FORMAT_REQUIRED e valori non supportati 422 INVALID_FORMAT. download è ora obbligatorio sulle richieste task-result; valori mancanti restituiscono 400 DOWNLOAD_FORMAT_REQUIRED e valori non supportati 400 INVALID_DOWNLOAD_FORMAT. Gli upload di conversione ora accettano client_reference/external_invoice_id e source_system per la riconciliazione lato cliente. Le risposte di conversione accettata e stato task ora includono status_url, primary_result_format, primary_result_url e i campi di riconciliazione inviati.

La conversione strutturata ora accetta tutti i formati di output pubblici: XRECHNUNG, ZUGFeRD, EN16931, UBL e CII. La conversione strutturata ora accetta parti data_file ripetibili e gli alias data_files e data_files[] per export ERP suddivisi. I bundle strutturati multi-file devono descrivere esattamente una fattura e falliscono subito se gli ID fattura del bundle sono mancanti o in conflitto. Chiarito che più documenti fattura devono essere inviati come task di conversione separati, ciascuno con la propria idempotency key.

Aggiunto POST /api/v1/invoices:convert-structured per conversione da dati strutturati con PDF contenitore e CSV/JSON/XML/XLSX/TXT sui formati output supportati. Documentato che i dati strutturati sono l’unica fonte semantica su questo endpoint; il PDF viene usato per l’incorporamento ibrido. Artefatti OpenAPI e Postman aggiornati per la conversione strutturata.

Aggiunti crediti External API prepagati per tenant non Enterprise. Documentato 402 INSUFFICIENT_API_CREDITS per tenant approvati senza fatturazione Enterprise tramite order form o crediti prepagati. Confermato che i replay idempotenti non consumano crediti API aggiuntivi. Chiarito che il routing del modello External API V1 è gestito lato server, mentre profilo e contesto di consegna restano controllati dal chiamante.

Download task-result resi fedeli al formato per output CII e ZUGFERD. Aggiunto riuso di artefatti risultato in cache per download XML/PDF ripetuti dello stesso task. Quote di polling allineate a bucket rate-limit ponderati e scoped per endpoint.

Aggiunte risposte di errore API più chiare e coerenti su tutti gli endpoint. Opzioni convert ampliate e comportamento download XML/PDF documentato per i risultati task. Sicurezza retry migliorata con requisiti di idempotenza e validazione più rigidi. Artefatti OpenAPI/Postman aggiornati al comportamento API corrente.