# Automazione della conversione da PDF a fattura elettronica su scala tramite API

- Aggiornato a maggio 2026

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.