Documentazione API esterna V1

Funzionalità principali#

Usa questi punti come controlli pratici per questa sezione.

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

Avvio rapido#

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

Richiedi accesso alla beta chiusa#

Usa questi punti come controlli pratici per questa sezione.

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

Usa questi punti come controlli pratici per questa sezione.

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

Usa questi punti come controlli pratici per questa sezione.

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

Usa questi punti come controlli pratici per questa sezione.

• Authorization: Bearer <api_key>

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#

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

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.
• 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 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, 403, 409, 413).

Ciclo di vita del task e conservazione#

Usa questi punti come controlli pratici per questa sezione.

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

Usa questi punti come controlli pratici per questa sezione.

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

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.