Prima o poi ogni team vuole che i documenti dialoghino con il resto del software: caricare un file da uno script, avviare un flusso da un pianificatore o essere avvisato appena un documento finisce di essere elaborato. AuraDoc offre due strade complementari. L'API REST permette ai tuoi sistemi di chiedere qualcosa ad AuraDoc, e i webhook permettono ad AuraDoc di avvisare i tuoi sistemi che qualcosa è successo. Questo articolo li percorre entrambi, con i dettagli di sicurezza che contano in produzione.
Chiavi API e ambiti
Tutto parte da una chiave API. Creane una in Dashboard › Settings › API keys, dalle un nome e scegli gli ambiti. Gli ambiti limitano ciò che la chiave può fare, quindi una chiave usata solo per caricare file non ha bisogno del permesso di gestire altro. Una chiave non può crearne un'altra con ambiti più ampi dei propri, e i permessi effettivi sono sempre quelli in comune tra la chiave e il ruolo della persona, come descritto in ruoli e permessi del team. Le richieste portano la chiave nell'intestazione Authorization come token bearer.
La stessa pagina mostra le statistiche d'uso di ogni chiave, per capire quale integrazione è attiva e quale è rimasta in silenzio. Nei piani a pagamento puoi anche impostare un limite di richieste per una singola chiave, utile quando uno script rumoroso non deve penalizzare gli altri. Se una chiave trapela, eliminala e creane una nuova; nient'altro deve cambiare in AuraDoc.
Cosa può fare l'API
La pagina delle integrazioni nella documentazione indica l'indirizzo di base e offre esempi pronti da copiare. Oggi puoi caricare un documento, chiedere ad AuraDoc di acquisire un documento da un URL, avviare l'esecuzione di un flusso e creare una richiesta di firma, ciascuno con una sola richiesta autenticata. Sono le stesse operazioni che le persone fanno nella dashboard, quindi il risultato creato dall'API compare nell'interfaccia come ogni altro.
Se preferisci interrogare invece di ricevere chiamate, esistono endpoint trigger che restituiscono nuovi documenti, esecuzioni di flusso completate e firme completate, insieme a un catalogo che li descrive. Gli strumenti che non ricevono webhook, come i componenti aggiuntivi dei fogli di calcolo o le piattaforme no-code, possono consultarli a intervalli. Il riferimento completo è nella pagina di documentazione delle integrazioni.
Webhook in uscita
Per notifiche in tempo reale apri Dashboard › Webhooks e aggiungi un endpoint. Scegli gli eventi di interesse da un elenco che comprende documento creato, classificato ed eliminato, OCR e traduzione completati o falliti, eventi dei flussi, avvisi sulla quota di archiviazione ed eventi di firma. Al salvataggio AuraDoc mostra il segreto di firma una sola volta. Copialo subito nel servizio ricevente; se lo perdi, ruota il segreto e ne viene generato uno nuovo, con la rotazione registrata nel log di audit.
Puoi dare forma al contenuto con un modello, fino a qualche migliaio di caratteri, e validarlo prima di salvare. Un pulsante di prova invia un evento di esempio, contrassegnato da un'intestazione di test, per confermare che l'endpoint risponda e legga il corpo prima di farci affidamento. Ogni webhook può essere disattivato senza essere eliminato, utile durante le finestre di manutenzione.
Verificare le firme e gestire i guasti
Ogni consegna è firmata. AuraDoc calcola un HMAC-SHA256 su timestamp e corpo grezzo con il tuo segreto e invia il risultato nell'intestazione della firma, insieme a intestazioni con nome dell'evento, id del webhook, id della consegna, timestamp e numero di tentativi. Il tuo ricevente deve ricalcolare la firma dal corpo grezzo, confrontarla in tempo costante e rifiutare le richieste con timestamp troppo vecchio. Così nessuno può falsificare un evento verso il tuo endpoint, anche conoscendone l'indirizzo.
Gli endpoint si fermano, e AuraDoc lo prevede. Quando una consegna fallisce, viene ritentata automaticamente con attese crescenti, da cinque minuti a sei ore. La vista delle consegne mostra ogni tentativo con il suo esito, e puoi avviare un nuovo tentativo a mano dopo aver risolto il problema. Poiché lo stesso id di consegna viene riutilizzato nei tentativi, il ricevente può ignorare i duplicati senza rischi. Per unire i webhook ai file in arrivo dai provider, vedi archiviazione cloud e cartelle monitorate.