API e webhook
Il caricamento e la lettura dei documenti sono disponibili tramite REST API. La gestione dell'account, delle cartelle, delle etichette e delle connessioni rimane nell'applicazione.
Chiave
Si crea in Impostazioni → Per sviluppatori. La chiave viene mostrata una sola volta, al momento della creazione — poi non più, perché viene memorizzato solo il suo hash. Una chiave persa non può essere recuperata, ne viene creata una nuova e quella vecchia viene eliminata. È possibile avere cinque chiavi, ciascuna con una durata massima di validità di due anni.
Il proprietario dell'account riceverà un'email riguardo ogni nuova chiave, così come due settimane prima della scadenza della chiave. Vedi Avviso via email.
La chiave viene inviata nell'intestazione X-API-Key.
Cosa fa l'API
| Operazione | Descrizione |
|---|---|
POST /api/upload | Caricamento di un file con opzioni: formato, direzione, tipo, valuta, schema, cartella, webhook |
POST /api/upload/url | Idem da un indirizzo pubblico; scarichiamo il file noi stessi |
GET /api/jobs | Elenco dei documenti con filtri e paginazione |
GET /api/jobs/{id} | Stato, dati letti, segnalazioni e risultato nel formato di destinazione |
GET /api/jobs/{id}/original | File caricato |
DELETE /api/jobs/{id} | Eliminazione nel cestino |
Excel e PDF vengono restituiti come Base64. Chi non ha bisogno del risultato può inviare includeResult=false, risparmiando così la conversione sul server.
La descrizione dell'interfaccia in formato OpenAPI è disponibile all'indirizzo /api/docs; il link si trova nelle impostazioni delle chiavi. La descrizione è generata dal codice in esecuzione, quindi corrisponde a ciò che l'API fa.
Controllo dei documenti dall'API
Il controllo prima dell'invio è attivo di default anche per i documenti caricati con la chiave: il documento rimane in attesa di conferma nell'app e il webhook viene inviato solo dopo di essa. Chi sta costruendo un'integrazione in cui nessuno è davanti allo schermo può disattivare il canale API in Impostazioni → Controllo prima dell'invio, oppure disattivare il controllo.
MCP
Per gli agenti AI, all'indirizzo /api/mcp c'è un server MCP con la stessa chiave. Può leggere e cercare documenti, ma non caricarli; il caricamento restituisce come comando pronto, che l'agente eseguirà autonomamente.
Webhook
Invece di interrogare lo stato, fai inviarti il risultato quando è pronto. L'indirizzo viene impostato per l'intero account in Impostazioni → Per sviluppatori, oppure per ciascun caricamento individuale tramite il parametro targetWebhookUrl. Un pulsante nelle impostazioni invia un messaggio di test.
Viene inviato un POST con JSON: identificatore del documento, nome del file, formato e risultato nel formato di destinazione. Quando il documento supera il controllo o viene rielaborato, il webhook viene inviato una seconda volta con il flag di correzione (IsCorrection).
Il messaggio non viene firmato. Verifica il mittente aggiungendo il tuo token segreto all'indirizzo. Gli indirizzi per reti private vengono rifiutati.
Se il webhook non arriva dopo tutti i tentativi, dopo circa quattro e mezzo ore, verrà inviato un'email. Durante un singolo guasto solo una volta, ulteriori fallimenti verranno registrati nelle attività. L'email verrà inviata anche dopo ogni modifica dell'indirizzo webhook, nel caso fosse cambiato da qualcun altro oltre a te.
Le consegne fallite verranno ripetute con un'attesa crescente, per un totale di undici tentativi durante circa quattro e mezzo ore. Ogni tentativo è registrato nelle attività con la risposta da parte tua; per ogni documento nell'elenco è presente un'icona con il risultato della consegna.
Limiti
L'API non ha un limite proprio sul numero di chiamate al minuto; il caricamento è limitato dai crediti, dalla dimensione del file in base alla tariffa e da venti pagine per documento. Il rifiuto viene restituito come errore 400 con un codice che spiega il motivo. Il server MCP è limitato a dieci richieste al secondo.