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. L’XML fattura incorporato viene ignorato per impostazione predefinita; imposta use_embedded_xml=true solo se l’integrazione lo accetta come fonte primaria di estrazione. 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, confrontato senza distinzione tra maiuscole e minuscole. Ogni formato ha un insieme chiuso di valori accettati e un solo default: XRECHNUNG → [XRECHNUNG] (default XRECHNUNG); EN16931 → [EN16931] (default EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (default EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (default EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (default ZUGFERD_EN16931). ZUGFERD, FACTURX, FACTUR-X e FACTUR_X sono alias di ZUGFERD_EN16931; ZUGFERD-XRECHNUNG è alias di ZUGFERD_XRECHNUNG. Un valore fuori dall’insieme accettato restituisce 422 OUTPUT_PROFILE_CONFLICT; un nome di profilo non riconosciuto restituisce 422 INVALID_PROFILE con details.allowed_profiles; 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; email_input (testo libero, opzionale, solo sorgenti PDF) — istruzioni del cliente in qualsiasi lingua, fino a 10.000 caratteri, inviate senza marcatori di blocco e-mail; tutti i passaggi di estrazione e correzione AI le ricevono separatamente dal testo sorgente della fattura; non combinabile con use_embedded_xml=true, fa parte dell’identità della richiesta usata per l’idempotenza e non è supportata da invoices:convert-structured; la validazione standard della fattura resta valida; 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; electronic_address e electronic_address_scheme devono essere forniti insieme oppure entrambi omessi; use_embedded_xml (boolean, opzionale, default false) — l’XML Factur-X, ZUGFeRD o XRechnung incorporato viene ignorato salvo valore esplicito true; usare solo se l’integrazione accetta l’XML incorporato come fonte primaria di estrazione. 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, confrontato senza distinzione tra maiuscole e minuscole. Ogni formato ha un insieme chiuso di valori accettati e un solo default: XRECHNUNG → [XRECHNUNG] (default XRECHNUNG); EN16931 → [EN16931] (default EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (default EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (default EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (default ZUGFERD_EN16931). Un valore fuori dall’insieme accettato restituisce 422 OUTPUT_PROFILE_CONFLICT; un nome di profilo non riconosciuto restituisce 422 INVALID_PROFILE con details.allowed_profiles; 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; electronic_address e electronic_address_scheme devono essere forniti insieme oppure entrambi omessi. Risposta: 202 Accepted.

Esegui il polling dello stato corrente di un task di conversione. Restituisce pending (accettato e in coda, non ancora avviato), processing, completed o failed. Rate limit 10/min e 120/hour: è il vincolo determinante per il polling: attendi circa 20 secondi dopo il 202 accettato prima della prima chiamata, poi distanzia le chiamate (20s, 30s, 45s, 60s e da lì 60s) e fermati su 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; su un task completato download=xml è l’artefatto atteso come disponibile, non garantito. Download ripetuti possono essere serviti da artefatti generati in cache quando la prova di validazione è ancora attuale. Durante l’elaborazione questo endpoint restituisce un 202 con l’envelope di errore standard ({"code":"TASK_NOT_READY","message":"Strict conversion is still processing. No validated artifact is available yet.","correlation_id":"<uuid>"}); i problemi di validazione bloccanti restituiscono 422 VALIDATION_FAILED, le dipendenze non disponibili ma ripetibili restituiscono 503, i fallimenti di conversione definitivi restituiscono 500 TASK_FAILED con il motivo in details.code e i fallimenti degli invarianti degli artefatti restituiscono 500 INTERNAL_ARTIFACT_INVARIANT_FAILED, sempre senza corpo file. I download riusciti riportano X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status e X-Validator-Bundle-Id; X-Task-Id non è impostato su questo endpoint. Rate limit 10/min e circa 134/hour. Richiesta: nessuno (GET); task_id (path, obbligatorio) — UUID restituito dall’endpoint di conversione; download (query, obbligatorio) — xml o pdf. Risposta: 200 OK.

Scarica il report dell’artefatto risultato validato corrente. Il report è disponibile solo dopo che la conversione rigorosa ha salvato un artefatto con prova aggiornata; in caso contrario l’endpoint restituisce 202 o 404. Gli header della risposta identificano l’artefatto e la prova del report. X-Artifact-Sha256 indica l’artefatto risultato, non il file del report. Rate limit: 10/min e 120/ora. Richiesta: nessuno (GET); task_id (percorso, obbligatorio) — UUID restituito da un endpoint di conversione; download (query, opzionale) — html o xml. Risposta: 200 OK.

seller_master_data ora tratta electronic_address ed electronic_address_scheme come una coppia opzionale. Fornire entrambi i campi oppure ometterli entrambi; una coppia incompleta restituisce 400 INVALID_SELLER_MASTER_DATA.

Correzione della documentazione prezzi: 1.000 crediti prepagati costano 400 EUR (0,40 EUR per credito). I pacchetti da 100, 200 e 500 crediti restano a 50, 100 e 250 EUR. I prezzi applicati e gli acquisti esistenti non cambiano.

La conversione dei documenti ora ignora per impostazione predefinita l’XML fattura incorporato. Imposta use_embedded_xml=true solo se l’integrazione accetta esplicitamente l’XML incorporato come fonte primaria di estrazione. L’importazione e-mail ignora sempre l’XML fattura incorporato. La modifica di use_embedded_xml cambia l’hash di idempotenza della richiesta; usa un nuovo Idempotency-Key quando modifichi questa opzione.

Quando i dati anagrafici del venditore compilano un campo, i flag di estrazione restanti restano visibili ma non bloccano più l’import e-mail rigoroso o l’External API. Acquirente, righe, imposta, consegna, scadenza, sconto, causale, campi profilo non compilati e valori non validi restano bloccanti.

Enterprise è diventato disponibile con acquisto diretto a 50 EUR/mese o 420 EUR/anno. Enterprise include 100 conversioni Email/API condivise al mese; le conversioni aggiuntive usano crediti prepagati da 0,40–0,50 EUR. Le chiavi API non richiedono più approvazione manuale.

Pubblicati il catalogo errori attuale e le regole di retry per codice. Uno stato 500 non è automaticamente ritentabile; controlla code, details.code e details.retryable. Documentate entrambe le forme di details per 402 INSUFFICIENT_API_CREDITS e i diversi percorsi di recupero per gli errori 409 di idempotenza. Pubblicati gli header di prova del report, la conservazione di 24 ore, i timeout dei task e i rate limit per endpoint. Pubblicata la tabella chiusa formato/profilo e corrette le indicazioni per download, METHOD_NOT_ALLOWED e PROFILE_MISMATCH.

La conversione API ora rifiuta una sorgente confermata con più fatture tramite l’errore definitivo MULTIPLE_INVOICES_IN_DOCUMENT. Dividi i file multi-fattura confermati. Un segnale incerto restituisce invece 422 VALIDATION_FAILED per il controllo.

I dati anagrafici venditore abilitati ora sostituiscono i valori estratti corrispondenti del venditore o del pagamento. I campi assenti dal profilo lasciano invariati i valori estratti; le differenze restano avvisi di controllo non bloccanti.

Sostituito dal 2026-07-26: i dati anagrafici venditore ora sostituiscono i valori estratti corrispondenti invece di compilare solo quelli mancanti.

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.

I dati fattura inviati sono ora la fonte dati per l’output ibrido ZUGFeRD; la pulizia deterministica e la normalizzazione fiscale restano attive. I task falliscono quando il progresso si arresta o al limite di 15 minuti, non dopo un timeout fisso di cinque minuti.

Gli errori di salvataggio del tracciamento uso non bloccano una risposta validata pronta né addebitano un credito extra; gli eventi falliti vanno in coda per la riconciliazione.

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.

Gli artefatti XML rigorosi e PDF ibridi hanno ricevuto dati interni di parità; usa result_artifacts per disponibilità e stato di validazione. La base URL di produzione documentata è diventata https://www.invoice-converter.com/api/v1.

GET /api/v1/tasks/{task_id}/result esegue solo il recupero; non genera, ripara o valida file. I task rigorosi terminano solo dopo il salvataggio di un artefatto validato; una prova attuale mancante produce un errore chiuso. La conversione External API è fissa sull’emissione rigorosa, senza bozze o esclusione degli avvisi. Lo stato del task ha ricevuto la diagnostica result_artifacts e i valori delivery_channel documentati.

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.

Lo stato del task ha ricevuto la diagnostica di disponibilità degli artefatti XML/PDF. I download rigorosi restituiscono file solo dopo i controlli server dell’artefatto.

I download riusciti hanno ricevuto una prova di validazione server per l’artefatto restituito. Dipendenze di validazione o prova mancanti restituiscono 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE. I download in cache sono riutilizzati solo finché la prova di validazione salvata resta aggiornata.

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.