Guida · Aggiornato a maggio 2026
Esporta MarkdownAutomazione della conversione da PDF a fattura elettronica su scala tramite API
Automatizza la conversione da PDF a fattura elettronica tramite l'API, configura il polling asincrono dello stato ed elabora più fatture a livello di codice, con una richiesta di conversione per fattura.
Passaggi chiave dell'integrazione
Usa questi punti come controlli pratici per questa sezione.
- Acquisisci una chiave API di produzione dalla dashboard dello sviluppatore.
- Autentica tutte le richieste utilizzando l'intestazione
Authorizationcon un tokenBearer. - Invia una richiesta
POSTa/api/v1/invoices:convertcon il file PDF e i parametri del profilo di conformità. - Gestisci la risposta dell'attività asincrona ed esegui il polling di
GET/api/v1/tasks/{task_id}finché la conversione non viene completata o non fallisce. - Recupera l'output XML convalidato in formato
XRechnung,ZUGFeRDoUBL.
Polling asincrono dello stato
Integrare la conformità per la fatturazione elettronica su scala significa automatizzare l'invio e il recupero tramite l'API. Ogni richiesta converte esattamente una fattura e i risultati convertiti dovrebbero comunque passare attraverso il tuo normale processo di revisione e gestione delle eccezioni per i casi limite e i documenti di origine di bassa qualità.
L'API è asincrona: quando carichi un PDF, restituisce immediatamente uno stato 202 Accepted con un ID attività univoco.
Il tuo sistema interroga l'endpoint dello stato dell'attività su GET /api/v1/tasks/{task_id} ogni 10-15 secondi, finché l'attività non risulta completata o non riuscita. L'API non fornisce webhook: è tramite il polling che il tuo sistema apprende quando una conversione è pronta.
Best practice per la scalabilità
Usa questi punti come controlli pratici per questa sezione.
- Specifica sempre un profilo di conformità esplicito, come
XRechnungoZUGFeRD, per evitare ritardi dovuti al rilevamento automatico. - Implementa un backoff esponenziale durante il polling dello stato dell'attività per evitare inutili limiti di frequenza (rate limit).
- Memorizza gli UUID delle attività restituiti nel tuo database locale per facilitare la tracciabilità e la registrazione dei controlli.
- Invia un header
Idempotency-Keystabile per ogni fattura, in modo che i nuovi tentativi non creino mai conversioni duplicate.