# 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, attendi l'elaborazione asincrona e poi recupera il risultato generato. Invia una fattura PDF a un singolo endpoint e Invoice-Converter gestisce estrazione, validazione e generazione dell’output. L’endpoint del risultato restituisce il file generato solo dopo il superamento dei gate di validazione; altrimenti restituisce 422 VALIDATION_FAILED. > **Stato: self-service**: Percorso base: /api/v1. Ultimo allineamento 2026-05-23. ## Funzionalità principali - Un solo endpoint per la conversione da PDF a XML - Estrazione dei dati fattura assistita dall’IA - Validazione automatica EN 16931 e KoSIT - Formati di output XRechnung, ZUGFeRD, 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) - [API Playground](/developer-api/playground) ## Avvio rapido Tre chiamate API completano una conversione. L’endpoint di conversione è servito su /api/v1 e richiede autenticazione. ### POST /api/v1/invoices:convert (In sviluppo) Converti PDF in e-fattura strutturata ### GET /api/v1/tasks/{task_id} (In sviluppo) Esegui polling dello stato task ### GET /api/v1/tasks/{task_id}/result (In sviluppo) Scarica risultato conversione ## Richiedi accesso alla beta chiusa - Crea un account e apri il profilo. - Acquista crediti API prepagati o usa un piano Enterprise con accesso API incluso. - Crea una chiave API 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://invoice-converter.com/api/v1`. - Usa lo stesso host API di produzione per tutto il traffico pilota: `https://invoice-converter.com/api/v1`. - Durante l’onboarding usa richieste fixture a basso volume; le conversioni accettate consumano crediti API. - 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 `2-5 secondi`: `GET /api/v1/tasks/{task_id}` finché lo stato è `completed` o `failed`. - Scaricamento: `GET /api/v1/tasks/{task_id}/result` e salva `X-Correlation-ID` più `X-Validation-Proof-Id` se presente. - Per output PDF ZUGFeRD, invia `format=ZUGFERD`; l’endpoint result restituisce di default il PDF ibrido. ## Esempi comuni di payload - `XRECHNUNG`: invia `format=XRECHNUNG`; è il default quando format è omesso. - `ZUGFERD`: invia `format=ZUGFERD` per un PDF ibrido EN16931 ZUGFeRD/Factur-X. - `UBL`: invia `format=UBL` per XML UBL EN16931. - `CII`: invia `format=CII` per XML CII EN16931. ## Header richiesti - Authorization: Bearer ## Regole di autenticazione L’accesso API è self-service. Crea le chiavi API dal profilo, usale come Bearer token e acquista crediti API prepagati per automatizzare le conversioni. - Le chiavi sono scoped per tenant e usano il prefisso `icp_`. - Crea, ruota e revoca le chiavi API dal profilo quando l’accesso External API è abilitato. 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 hours`. ## 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 (In sviluppo) Carica una fattura PDF e avvia la conversione asincrona. Restituisce una task_id per il polling. Richiesta: multipart/form-data. Risposta: 202 Accepted. ### GET /api/v1/tasks/{task_id} (In sviluppo) Esegui il polling dello stato corrente di un task di conversione. Restituisce pending, processing, completed o failed. Quando è failed, la risposta include un campo error con il motivo dell’errore. Richiesta: nessuno (GET). Risposta: 200 OK. ### GET /api/v1/tasks/{task_id}/result (In sviluppo) Scarica il file generato. I task ZUGFERD restituiscono per impostazione predefinita un PDF ibrido EN16931 ZUGFeRD/Factur-X; gli altri formati restituiscono XML. Download ripetuti possono essere serviti da artefatti generati in cache. Se restano problemi di validazione bloccanti, questo endpoint restituisce 422 VALIDATION_FAILED senza corpo file. Richiesta: nessuno (GET). 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 | PDF/A-3 ibrido EN16931 di default; XML CII con download=xml | ZUGFeRD 2.4 / Factur-X 1.08 | application/pdf o application/xml | .pdf / .xml | | 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-05-08 Aggiunti crediti External API prepagati per tenant non Enterprise. Documentato 402 INSUFFICIENT_API_CREDITS per tenant senza fatturazione Enterprise o crediti prepagati. Confermato che i replay idempotenti non consumano crediti API aggiuntivi. Richieste di conversione semplificate a file più formato; la configurazione dell’estrazione è gestita server-side. ### 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 | Acquista almeno 10 crediti API prepagati o usa la fatturazione Enterprise | | 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 | | 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 | | 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 | | PROFILE_MISMATCH | 422 | No | Invoice CustomizationID conflicts with the selected public format | | 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`. - 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. ## Limiti di frequenza e payload Rate limit per chiave e vincoli di dimensione payload si applicano a tutte le chiamate API. Le richieste negate non consumano quota. - Le quote endpoint-aware sono ponderate per costo. Convert usa la quota base del piano (default `30/min` e `500/hour`), mentre gli endpoint di polling usano quote con peso inferiore. - Leggi i limiti effettivi da `X-RateLimit-Limit-Minute` e `X-RateLimit-Limit-Hour` nelle risposte. - Dimensione massima upload PDF: `20 MB` - 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`, `403`, `409`, `413`). ## Ciclo di vita del task e conservazione - Task completed e failed restano disponibili per `10 minutes` dopo lo stato terminale. - Il processing va in timeout dopo `5 minutes`; i task bloccati sono marcati automaticamente `failed`. - Le chiavi di idempotenza scadono dopo `24 hours`. - I contatori rate-limit si azzerano su una finestra mobile. ## Modello di supporto - Supporto in orario lavorativo. - Obiettivo prima risposta: 1 giorno lavorativo. ## 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)%2520%0D%0A2)%2520%0D%0A3)%2520%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.