Quando i documenti nascono in un altro sistema

La domanda che arriva al secondo incontro: «vi integrate con il nostro sistema?». Finora la risposta onesta era no. Ora la risposta è questa: hai un portale, un CRM o un sistema contabile in cui l'affare esiste già, e DocuTract può funzionare come una sua parte.

La sesta funzionalità di questa serie è la via d'uscita. Un token con cui il tuo sistema ci chiama, un indirizzo a cui scriviamo di nostra iniziativa e una descrizione aperta di tutto ciò che sta in mezzo.

Un token che non possiamo mostrarti due volte

Un token si crea nella schermata Integrazioni: un nome che riconoscerai in seguito, così sai quale sistema lo usa, e un elenco di ciò che gli è consentito fare. Poi viene mostrato una volta sola.

Non è una dimenticanza, è il modo in cui deve funzionare un prodotto che custodisce la chiave di qualcun altro. Conserviamo solo un hash: mostrare il token una seconda volta è qualcosa che nemmeno noi possiamo fare, il che significa che non può esserci rubato. L'elenco conserva i primi caratteri, i permessi e la data dell'ultimo utilizzo, così si vede quale token è attivo e se qualcuno lo sta ancora usando.

Revoca lo disattiva all'istante. La sua traccia resta: il fatto che sia esistito e quando ha smesso di funzionare fa parte della storia dell'area di lavoro, non è spazzatura.

I permessi vengono verificati su ogni indirizzo separatamente. Un token autorizzato solo a leggere i modelli riceve un chiaro «manca lo scope documents:write» quando prova a creare un documento, non un vuoto «non trovato». Partiamo dal presupposto che a collegare l'integrazione ci sia una persona in carne e ossa, e una risposta che non spiega nulla le costa una serata.

Cosa può fare l'API

Tutto ciò che puoi fare dalla schermata, solo senza la schermata: aprire una pratica e caricarvi le scansioni, creare un documento da un modello con i valori già compilati, chiedere a che punto è arrivato, prendere ogni valore insieme alla scansione da cui è stato letto e ottenere un link a breve scadenza al file finito.

Quest'ultima parte è ciò che rende questa integrazione diversa dalle altre. Il tuo sistema riceve non solo un file compilato, ma ogni valore con la sua provenienza: la scansione, il campo, quanto era affidabile la lettura. La stessa fonte che una persona vede nella schermata di revisione è disponibile per il codice.

La descrizione di ogni indirizzo e campo è generata dal codice stesso e pubblicata apertamente, senza token: /api/v1/openapi.json. Una documentazione che bisogna prima chiedere è una documentazione che nessuno legge.

Webhook e un registro onesto

Non devi chiederci se un documento è pronto. Dacci un indirizzo e spunta gli eventi: documento pronto, documento non riuscito, pratica pronta, discrepanza trovata, un cliente ha inviato un file.

Ogni richiesta è firmata, e il segreto che verifica la firma viene mostrato una volta sola, come il token. Se il tuo server ha risposto qualcos'altro, o non ha risposto affatto, riproviamo: dopo un minuto, dopo cinque, dopo mezz'ora, dopo due ore e dopo dieci. Poi ci fermiamo, perché un'integrazione di cui nessuno si occupa non dovrebbe consumare per sempre le risorse di qualcuno.

E poi la parte per cui tutto questo è stato scritto. Quando l'altra parte dice «il nostro sistema non ha ricevuto nulla», la risposta è sullo schermo: l'evento, l'ora, quanti tentativi, quale codice di risposta è tornato e l'inizio del corpo della risposta. Si vede che ha risposto 500 cinque volte. Non è uno strumento di debug per noi, è una risposta per il tuo tecnico.

Accanto, due pulsanti per il momento in cui un'integrazione è ancora in fase di configurazione. Invia una prova invia subito una richiesta di prova, senza aspettare un evento reale, così un ricevitore può essere verificato prima che ci passi qualsiasi lavoro. Riprova, accanto a una consegna non riuscita, fa subito un altro tentativo e non azzera la cronologia: i quattro tentativi falliti restano nel registro, perché questa è la verità su quanto è costata quella notifica.

I limiti che ci siamo imposti

Un webhook va solo verso https e solo verso un indirizzo pubblico: un indirizzo all'interno di una rete privata viene rifiutato sia al salvataggio sia prima di ogni tentativo, perché un nome host che ieri puntava verso l'esterno oggi può puntare verso l'interno. Il limite di frequenza conta per token anziché per indirizzo, così un vicino sullo stesso server non consuma la tua quota, e superarlo produce un onesto «riprova tra tot secondi».

L'API e i webhook fanno parte del piano Team. Se un'area di lavoro passa a un altro piano, ciò che è già stato creato resta visibile e può essere revocato: chiavi che nessuno può raggiungere sono peggio di una funzione a pagamento.

Cosa non c'è in questa versione

Il brief di questa fase descriveva altre due parti: l'esportazione di un documento finito su Google Drive, OneDrive o Dropbox, e l'invio per la firma tramite DocuSign o Dropbox Sign. Entrambe richiedono credenziali di quei fornitori, che al momento non abbiamo, e scrivere un'integrazione che non si può testare da nessuna parte significa spacciare codice non scritto per finito. Restano nel piano come versioni a sé.

Cosa viene dopo

La settima e ultima funzionalità di questa serie è la generazione in lotti: un elenco di cinquanta righe o un archivio di scansioni invece di cinquanta compilazioni identiche a mano, con l'avanzamento visibile e la possibilità di ripetere solo quelle che non sono riuscite.

L'elenco completo è in cosa stiamo costruendo adesso, e le istruzioni passo passo per le integrazioni sono nel centro assistenza.