Vai al contenuto principale

Guida · 2026-05-16

Esporta Markdown

Automazione 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

  • Acquisisci una chiave API di produzione dalla dashboard dello sviluppatore.
  • Autentica tutte le richieste utilizzando l'intestazione Authorization con un token Bearer.
  • Invia una richiesta POST a /api/v1/invoices:convert con 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, ZUGFeRD o UBL.

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à

  • Specifica sempre un profilo di conformità esplicito, come XRechnung o ZUGFeRD, 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-Key stabile per ogni fattura, in modo che i nuovi tentativi non creino mai conversioni duplicate.