Documentazione API esterna V1

Funzionalità principali#

Usa questi punti come controlli pratici per questa sezione.

• 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.

Avvio rapido#

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

Ottieni accesso API#

Usa questi punti come controlli pratici per questa sezione.

• 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#

Usa questi punti come controlli pratici per questa sezione.

• 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#

Usa questi punti come controlli pratici per questa sezione.

• 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#

Usa questi punti come controlli pratici per questa sezione.

• 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#

Usa questi punti come controlli pratici per questa sezione.

• 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.

Matrice dei formati di output#

Registro modifiche#

Modifiche API esterne più recenti.

Contratto errori#

Errori comuni e cosa fare#

Usa questi punti come controlli pratici per questa sezione.

• 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 questi punti come controlli pratici per questa sezione.

• 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#

Usa questi punti come controlli pratici per questa sezione.

• 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#

Usa questi punti come controlli pratici per questa sezione.

• 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.

Usare Postman e OpenAPI#

Usa questi punti come controlli pratici per questa sezione.

• 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.