# Documentazione API esterna V1

Pacchetto documentale tecnico per implementazione e revisione API self-service. Questa pagina riassume il contratto API esterno, il modello di accesso e i vincoli di integrazione.

## Panoramica

Pacchetto documentale tecnico per implementazione e revisione API self-service. Questa pagina riassume il contratto API esterno, il modello di accesso e i vincoli di integrazione.

L'API accetta upload multipart, restituisce risposte JSON e usa codici di stato HTTP standard con autenticazione Bearer. Invia una fattura PDF o dati fattura strutturati, attendi l'elaborazione asincrona e poi recupera il risultato generato.

Invia una fattura PDF o dati fattura strutturati a un endpoint di conversione. Invoice-Converter avvia un task asincrono per estrazione, validazione e generazione degli artefatti. L’endpoint del risultato restituisce un file solo quando l’artefatto richiesto è validato, controllato e pronto; durante l’elaborazione restituisce 202 TASK_NOT_READY, mentre i problemi di validazione bloccanti restituiscono 422 VALIDATION_FAILED.

> **Stato: accesso approvato**: Percorso base: /api/v1. Ultimo allineamento 2026-06-29.

## Funzionalità principali

- Endpoint di upload per fatture PDF e dati fattura strutturati
- Estrazione dei dati fattura assistita dall’IA
- Validazione automatica EN 16931 e KoSIT
- Formati di output XRechnung, ZUGFeRD, EN16931, UBL e CII
- Elaborazione asincrona con polling, fatture piccole in circa 30 secondi e fatture più grandi fino a 1-2 minuti
- Scritture idempotenti per retry sicuri

## Artefatti di consegna

Scarica gli artefatti di integrazione leggibili da macchina per la Developer API.

- [OpenAPI JSON](/developer-api/v1/openapi.json)
- [Collezione Postman](/developer-api/v1/postman.json)

## Avvio rapido

Tre chiamate API completano una conversione. L’endpoint di conversione è servito su /api/v1 e richiede autenticazione.

### POST /api/v1/invoices:convert (Live)
Converti PDF in e-fattura strutturata

### POST /api/v1/invoices:convert-structured (Live)
Converti dati strutturati

### GET /api/v1/tasks/{task_id} (Live)
Esegui polling dello stato task

## Ottieni accesso API

- Crea un account e richiedi accesso API.
- Usa crediti API prepagati per test approvati o fatturazione Enterprise tramite order form per l’uso in produzione.
- Dopo l’approvazione, crea una chiave API live dalla sezione accesso API.
- Esegui la prima richiesta con credenziali server-side, poi monitora l’uso e ruota le chiavi dal profilo.

## URL base e chiavi API

- URL di base di produzione: `https://www.invoice-converter.com/api/v1`.
- Le chiavi live usano l’host di produzione e il prefisso `icp_...`.
- Esegui richieste di onboarding e validazione con chiavi live approvate prima di inviare volumi di produzione.
- Tratta le chiavi come secret server-side. Non inserirle in client browser o mobile.

## Prima richiesta riuscita

Usa questa sequenza come percorso minimo dopo aver creato una chiave API.

- Caricamento: `POST /api/v1/invoices:convert` con `Authorization`, `Idempotency-Key`, `file=@invoice.pdf` e `format=XRECHNUNG`.
- Esegui polling ogni `10-15 secondi`: `GET /api/v1/tasks/{task_id}` finché lo stato è `completed` o `failed`.
- Scaricamento: `GET /api/v1/tasks/{task_id}/result?download=xml` e salva `X-Correlation-ID` per il tracciamento del supporto.
- Per output PDF ZUGFeRD, richiedi `format=ZUGFERD` nel convert e `download=pdf` nel result.
- Per input strutturato, chiama `POST /api/v1/invoices:convert-structured` con `pdf_file=@invoice.pdf`, `data_file=@invoice-data.json` e il `format` di destinazione.
- Invia opzionalmente `client_reference` o `external_invoice_id` e `source_system` per la riconciliazione ERP.
- Per export ERP divisi di una fattura, ripeti `data_file`; per più fatture, avvia un task per fattura con una propria idempotency key.
- Salva `result_artifacts` dalla risposta di stato per vedere se gli artefatti XML/PDF sono validati, in cache o ancora non disponibili per dipendenze.

## Esempi comuni di payload

- `XRECHNUNG`: invia `format=XRECHNUNG`.
- `ZUGFERD`: invia `format=ZUGFERD`; usa `download=pdf` nel result per l’output ibrido PDF/A-3.
- `Input strutturato`: invia `pdf_file` più una o più parti `data_file`; i formati dati accettati sono CSV, JSON, XML, XLSX e TXT, con qualsiasi formato di destinazione supportato. Le parti data_file devono contenere tutti i dati obbligatori; il PDF non completa i campi mancanti.
- `Più fatture`: invia richieste convert separate e traccia ogni `task_id` restituito; le parti `data_file` ripetute servono solo per export divisi della stessa fattura.
- `UBL`: invia `format=UBL`; per integrazioni deterministiche imposta un `profile` esplicito come `PEPPOL`, `XRECHNUNG` o `EN16931`.
- `CII`: invia `format=CII`; per integrazioni deterministiche imposta un `profile` esplicito come `EN16931`.

## Header richiesti

- Authorization: Bearer <api_key>

## Regole di autenticazione

L’accesso API richiede approvazione. Gli account approvati possono creare chiavi API dal profilo, usarle come Bearer token e usare crediti prepagati per test approvati o fatturazione Enterprise tramite order form per la produzione.

- Le chiavi sono credenziali live scoped per tenant per account approvati. Il prefisso di produzione corrente è `icp_...`.
- Crea, ruota e revoca le chiavi API dal profilo dopo l’attivazione dell’accesso API. Copia subito le nuove chiavi perché il valore in chiaro viene mostrato una sola volta.
- Chiave mancante o non valida restituisce `401`.
- Le chiamate a `/api/v1` ricevono automaticamente `X-Correlation-ID` se omesso.
- Le chiamate di scrittura richiedono `Idempotency-Key`; mantieni stabile questo valore nei retry.
- Usa integrazione server-to-server dal tuo backend. L’accesso da browser-origin è limitato in produzione.

## Contratto di idempotenza

- Invia un `Idempotency-Key` a ogni chiamata di scrittura.
- Le chiavi di idempotenza devono corrispondere a `[A-Za-z0-9._:-]+` ed essere lunghe al massimo 200 caratteri.
- Se fornisci una tua chiave, stessa chiave + payload identico restituisce la risposta in cache.
- Stessa chiave + payload diverso restituisce `409 IDEMPOTENCY_CONFLICT`.
- Le chiavi di idempotenza scadono dopo `24 ore`.

## Riferimento endpoint

Tutti gli endpoint sono disponibili su /api/v1. I timeout emergono come 504 e altri errori temporanei di connettività come 502; gli ID di correlazione aiutano il supporto a seguire le richieste end-to-end.

### POST /api/v1/invoices:convert (Live)
Carica una fattura PDF e avvia la conversione asincrona. Restituisce un task_id per il polling. Richiesta: multipart/form-data; file (binary, obbligatorio) — file fattura PDF; 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. Risposta: 202 Accepted.

### POST /api/v1/invoices:convert-structured (Live)
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. Risposta: 202 Accepted.

### GET /api/v1/tasks/{task_id} (Live)
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. 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. Risposta: 200 OK.

### GET /api/v1/tasks/{task_id}/result (Live)
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.

### GET /api/v1/tasks/{task_id}/validation-report (Live)
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.

## Matrice dei formati di output

| Formato | Sintassi | Versione / Profilo | Content-Type | Estensione |
| --- | --- | --- | --- | --- |
| XRECHNUNG | UBL 2.1 XML | XRechnung 3.0.2 | application/xml | .xml |
| ZUGFERD | CII XML (download=xml) / PDF/A-3 ibrido (download=pdf) | ZUGFeRD 2.4 / Factur-X 1.08 | application/xml o application/pdf | .xml / .pdf |
| EN16931 | UBL 2.1 XML | EN 16931 | application/xml | .xml |
| UBL | UBL 2.1 XML | OASIS UBL 2.1 | application/xml | .xml |
| CII | UN/CEFACT CII XML | D16B | application/xml | .xml |

## Registro modifiche

Modifiche API esterne più recenti.

### 2026-06-02
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.

### 2026-06-01
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.

### 2026-05-27
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.

### 2026-05-08
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.

### 2026-03-06
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.

### 2026-02-23
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.

### 2026-02-20
Risposte di stato semplificate verso output focalizzato sullo status. Validazione invii IndexNow e controlli autenticazione rafforzati. Controlli accesso API e comportamento request-limiting in produzione rafforzati.

## Contratto errori

| Codice | HTTP | Ripetibile | Note |
| --- | --- | --- | --- |
| AUTHENTICATION_REQUIRED | 401 | No | Bearer token mancante/vuoto |
| INVALID_API_KEY | 401 | No | Chiave API non trovata, revocata o scaduta |
| INSUFFICIENT_API_CREDITS | 402 | No | Usa crediti di test prepagati approvati o fatturazione Enterprise tramite order form |
| IDEMPOTENCY_KEY_REQUIRED | 400 | No | Endpoint di scrittura chiamato senza Idempotency-Key |
| INVALID_IDEMPOTENCY_KEY | 400 | No | La chiave di idempotenza ha formato non valido |
| IDEMPOTENCY_CONFLICT | 409 | No | Stessa chiave usata con hash richiesta diverso |
| IDEMPOTENCY_IN_PROGRESS | 409 | Sì | Retry sicuro più tardi con stessa chiave/payload |
| FORMAT_REQUIRED | 400 | No | Richiesta di conversione senza il format obbligatorio |
| INVALID_FORMAT | 422 | No | Formato di conversione non supportato |
| CLIENT_REFERENCE_CONFLICT | 400 | No | client_reference ed external_invoice_id sono diversi |
| DOWNLOAD_FORMAT_REQUIRED | 400 | No | Richiesta task-result senza la query download obbligatoria |
| INVALID_DOWNLOAD_FORMAT | 400 | No | La query download del task-result deve essere xml o pdf |
| AUTH_SERVICE_UNAVAILABLE | 503 | Sì | Backend auth non disponibile |
| RATE_LIMIT_SERVICE_UNAVAILABLE | 503 | Sì | Backend rate-limit non disponibile |
| RATE_LIMITED | 429 | Sì | Rispettare Retry-After e header quota |
| BAD_REQUEST | 400 | No | JSON non valido o parametro path UUID non valido |
| PAYLOAD_TOO_LARGE | 413 | No | Oltre il limite dimensione upload |
| INVALID_UPLOAD | 400 | No | Lettura/parsing upload non riusciti |
| UPLOAD_FAILED | 4xx/5xx | Condizionale | Correggi opzioni request non valide; retry solo per casi 5xx transitori |
| TASK_NOT_READY | 202 | Sì | Eseguire di nuovo polling per completamento async |
| VALIDATION_FAILED | 422 | No | Restano problemi di validazione bloccanti; correggi i dati fattura prima di riprovare |
| AUTHORITATIVE_VALIDATION_UNAVAILABLE | 503 | Sì | Validazione autorevole, persistenza della prova o dipendenza di generazione ibrida non disponibile; riprova più tardi |
| TASK_STATUS_FAILED | 4xx/5xx | Condizionale | Retry se la condizione del servizio è transitoria |
| TASK_RESULT_FAILED | 4xx/5xx | Condizionale | Retry se la condizione del servizio è transitoria |
| XML_GENERATION_FAILED | 500 | Sì | Errore transitorio di generazione XML o timeout |
| PDF_GENERATION_FAILED | 500 | Sì | Errore transitorio di generazione PDF o timeout |
| ARTIFACT_GENERATION_RERUN_REQUIRED | 503 | No | Generazione artifact rigorosa non riuscita dopo i retry server-side; avvia una nuova conversione dopo il ripristino della dipendenza |
| ZUGFERD_SOURCE_PDF_INCOMPATIBLE | 422 | No | La generazione PDF ibrida rigorosa non può incorporare l’XML nel PDF sorgente caricato |
| OUTPUT_PROFILE_REQUIRED | 422 | No | Un endpoint o contesto di richiesta correlato richiede un profilo esplicito per un contratto di output generico |
| OUTPUT_PROFILE_CONFLICT | 422 | No | Il profilo contraddice il formato di output selezionato o la variante esplicita |
| PROXY_ERROR | 502/504 | Sì | Errore temporaneo di connettività (504 per timeout) |

## Errori comuni e cosa fare

- Riprova con backoff: `429`, `500`, `502`, `503`, `504`.
- Correggi request o dati sorgente: `400`, `409`, `413`, `422`.
- Correggi accesso o credenziali: `401`, `403`.
- Conferma approvazione, crediti di test prepagati o fatturazione Enterprise tramite order form: `402 INSUFFICIENT_API_CREDITS`.
- Continua il polling più tardi: `202 TASK_NOT_READY`.
- Per `422 VALIDATION_FAILED`, mostra il campo, l’ID della regola e la correzione proposta a una persona incaricata della revisione prima di riprovare con dati fattura corretti.
- Per `503 AUTHORITATIVE_VALIDATION_UNAVAILABLE`, recupera più tardi lo stesso risultato task; non è stato consegnato alcun artefatto non verificato.

## Limiti di frequenza e payload

Rate limit per chiave e vincoli di dimensione payload si applicano a tutte le chiamate API. Le conversioni rifiutate non consumano crediti API prepagati; i rate limit sono calcolati separatamente per endpoint.

- I limiti per endpoint sono ponderati per costo. Entrambi gli endpoint di upload usano la quota base del piano (default `30/min` e `500/hour`); il polling task è attualmente almeno `10/min` e `120/hour` di default, e i download result sono attualmente almeno `10/min` e circa `134/hour` di default.
- Leggi i limiti effettivi da `X-RateLimit-Limit-Minute` e `X-RateLimit-Limit-Hour` nelle risposte.
- Dimensione massima upload PDF: `20 MB`
- Dimensione massima upload dati strutturati: `2 MB` totali su tutte le parti `data_file`.
- Dimensione massima payload JSON: `1 MB`
- Le risposte rate-limit includono `Retry-After`, `X-RateLimit-Limit-Minute` e `X-RateLimit-Limit-Hour`.

## Guida ai tentativi

- Usa backoff esponenziale con jitter.
- Riprova solo classi transitorie (`429`, `500`, `502`, `503`, `504`) usando dove possibile stesso payload e idempotency key.
- Non riprovare alla cieca errori di validazione o contratto (`400`, `401`, `402`, `403`, `409`, `413`, `422`).

## Ciclo di vita del task e conservazione

- I task completati (completed) e falliti (failed) restano disponibili per `10 minuti` dopo lo stato terminale.
- Il processing va in timeout dopo `5 minuti`; i task bloccati sono marcati automaticamente `failed`.
- Le chiavi di idempotenza scadono dopo `24 ore`.
- I contatori rate-limit si azzerano su una finestra mobile.

## Modello di supporto

- Supporto in orario lavorativo con sforzi commercialmente ragionevoli.
- Nessuno SLA formale, credito di servizio o impegno sui tempi di risposta salvo accordo in un order form.

## Invia feedback tecnico

Condividi con il nostro team domande di implementazione, rischi e richieste di modifica del contratto.

- [Invia feedback via email](mailto:contact@invoice-converter.com?subject=Feedback%20revisione%20tecnica%20API%20esterna%20V1&body=Ciao%20team%20Invoice-Converter%2C%0D%0A%0D%0AAbbiamo%20revisionato%20la%20documentazione%20API%20esterna%20V1%20e%20abbiamo%20i%20seguenti%20feedback%3A%0D%0A%0D%0A1)%20%0D%0A2)%20%0D%0A3)%20%0D%0A%0D%0ACordiali%20saluti%2C)

## Usare Postman e OpenAPI

- Importa la collezione Postman e imposta `baseUrl`, `apiKey` e una nuova variabile `idempotencyKey`.
- Esegui la collezione in ordine: convert, polling stato, poi fetch result.
- Usa OpenAPI JSON per generare client tipizzati, ma copri upload file, polling e gestione del risultato binario con test di integrazione.
- Registra `X-Correlation-ID` nei log così il supporto può tracciare le richieste end-to-end.