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 integrazioni rimane nell'applicazione.
Chiave
Viene creata in Impostazioni → Per sviluppatori. La chiave viene mostrata una sola volta, al momento della creazione — poi non più, poiché viene salvato solo il suo hash. Una chiave persa non può essere recuperata, se ne crea una nuova e si elimina quella vecchia. Si possono avere cinque chiavi, ciascuna con un periodo di validità opzionale fino a due anni.
La chiave viene inviata nell'intestazione X-API-Key.
Cosa può fare l'API
| Operazione | Descrizione |
|---|---|
POST /api/upload | Caricamento di un file con opzioni: formato, direzione, tipo, valuta, schema, cartella, webhook |
POST /api/upload/url | Stessa cosa 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, risultati 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 nel formato OpenAPI è disponibile all'indirizzo /api/docs; il link si trova nelle impostazioni sotto le chiavi. La descrizione viene generata dal codice in esecuzione, quindi corrisponde a ciò che l'API fa.
Controllo dei documenti dall'API
Il controllo prima dell'invio è attivo per impostazione predefinita anche per i documenti caricati con la chiave: il documento attende una conferma nell'app e il webhook verrà inviato solo dopo. Chi sta costruendo un'integrazione che non prevede che qualcuno sia davanti allo schermo, può rimuovere il canale API in Impostazioni → Controllo prima dell'invio, oppure disattivare il controllo.
MCP
Per gli agenti AI è disponibile all'indirizzo /api/mcp il server MCP con la stessa chiave. Può leggere e cercare documenti, ma non caricarli; il caricamento viene restituito come comando pronto che l’agente eseguirà autonomamente.
Webhook
Invece di interrogare lo stato, fai inviarti il risultato quando è pronto. L'indirizzo si imposta per l'intero account in Impostazioni → Per sviluppatori, o per ciascun caricamento tramite il parametro targetWebhookUrl. Il pulsante nelle impostazioni invia un messaggio di test.
Viene inviato un POST con JSON: identificatore del documento, nome file, formato e risultato nel formato di destinazione. Quando il documento supera il controllo o viene rielaborato, il webhook arriverà di nuovo con il flag di correzione (IsCorrection).
Il messaggio non è firmato. Verifica il mittente aggiungendo il tuo token segreto all'indirizzo. Gli indirizzi nelle reti private vengono rifiutati.
La consegna non riuscita viene ripetuta con ritardi crescenti, per un totale di undici tentativi in circa quattro ore e mezza. Ogni tentativo è visibile nell'attività con la risposta del tuo lato; per un documento nell’elenco c'è 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 al piano e da venti pagine per documento. Un rifiuto viene restituito come errore 400 con un codice che spiega il motivo. Il server MCP è limitato a dieci query al secondo.