Signaturit in Odoo: cosa ti dà un modulo nativo che Zapier non ti dà

Risposta breve: Zapier ti basta per far partire una firma e sapere che è stata completata. Non ti basta per riflettere dentro Odoo gli stati intermedi che attraversa un documento, né per recuperare un webhook perso, né per archiviare il PDF firmato e il suo documento probatorio nel record giusto. Se il tuo processo finisce quando il cliente firma, uno Zap è sufficiente e costa meno. Se il tuo processo inizia quando il cliente firma (fatturare, aprire una pratica, assumere un dipendente), ti servono gli stati dentro l'ERP.

Il punto di partenza: il documento viaggia via e-mail

Il circuito abituale ha tre passaggi manuali: qualcuno genera il PDF del preventivo in Odoo, lo carica nel pannello di Signaturit e aspetta; quando il cliente firma, il PDF firmato arriva nella casella di una persona; quella persona lo ricarica in Odoo, se se ne ricorda. I sintomi sono sempre gli stessi: nessuno sa se il cliente l'ha aperto, il PDF firmato finisce sul desktop di qualcuno e, quando serve la prova (il documento probatorio, l'audit trail), non è accanto alla fattura, che è dove chiunque la cercherebbe.

Prima di tutto, un requisito che riguarda tutti e tre i percorsi allo stesso modo: il tuo piano di Signaturit deve includere l'accesso all'API. L'autenticazione è un token Bearer che si ottiene dal pannello, e sandbox e produzione sono due record distinti con due token distinti. Signaturit non pubblica apertamente quali piani includono quell'accesso, quindi confermalo con loro prima di progettare qualsiasi cosa. Senza token non c'è né Zap, né n8n, né modulo.

I tre modi per collegarli, e dove basta Zapier

L'app di Signaturit su Zapier pubblica, a oggi, un solo trigger («New Signed Document», cioè «un documento è stato firmato») e cinque azioni: creare una richiesta di firma, crearla da un modello, annullarla, inviare un promemoria e creare un'e-mail certificata. L'app di Odoo self-hosted, dal canto suo, espone trigger e azioni generici sui record (creare un record, un lead, un'attività…). Questa è tutta la materia prima disponibile.

Dove basta Zapier (e puoi smettere di leggere)

Se invii un solo tipo di documento, pochi al mese, e ti serve solo che alla firma si crei un'attività o si avvisi via chat, monta uno Zap e non pensarci più. Basta anche se il documento non nasce in Odoo (un NDA preparato nel pannello di Signaturit). La regola è questa: se lo stato della firma non cambia nessuna decisione dentro l'ERP, l'ERP non ha bisogno di saperlo.

Quale documento esce da quale modello di Odoo

Questa è la parte che un passaggio generico «crea record» non può fare: non sa renderizzare il report QWeb di un ordine di vendita. Ogni modello richiede tre cose sue: il titolo che vedrà il firmatario, il destinatario predefinito e come si genera il PDF. Nel connettore che abbiamo costruito, ogni bridge risolve esattamente questi tre punti.

• Preventivo e ordine di vendita (sale.order): il report standard dell'ordine di vendita, con il cliente come firmatario.
• Fattura (account.move) e ordine di acquisto (purchase.order), per accettazioni e conferme del fornitore.
• Documento di consegna (stock.picking): il report di consegna, che una volta firmato funziona come prova di consegna.
• Contratto di lavoro: hr.contract in Odoo 17 e 18, e hr.version in Odoo 19, dove il modulo HR è stato rifatto. Il tipo di dettaglio che obbliga a mantenere tre rami del codice, non uno.
• Offerta a un candidato (hr.applicant), opportunità CRM (crm.lead), ticket (helpdesk.ticket) e progetto e attività, per accettazioni di lavori svolti.

Il ciclo completo degli stati, dove tutto il resto crolla

L'API v3 di Signaturit comunica, per documento, otto stati: in_queue, ready, signing, completed, expired, canceled, declined e error. I suoi eventi webhook sono ancora più granulari: e-mail consegnata, e-mail rimbalzata, documento aperto, documento firmato, documento d'identità aggiunto, scadenza prorogata, audit trail generato…

Dentro Odoo questo deve trasformarsi in due cose distinte. Primo: la richiesta in sé, con il suo ciclo (bozza, inviata, in corso, completata, rifiutata, scaduta, annullata, errore). Secondo: un campo nel documento di origine, perché l'addetto vendite che apre il preventivo veda lo stato senza uscire dal preventivo. Nel nostro connettore quel campo ha sette valori: non inviato, in attesa di firma, firmato, rifiutato, scaduto, annullato ed errore.

Con più firmatari, lo stato va dedotto dall'insieme: tutti completati, completata; uno che rifiuta, rifiutata; alcuni firmati e altri no, in corso. E c'è una protezione che si impara solo sbagliando: una richiesta annullata a mano non deve mai lasciarsi sovrascrivere da un evento successivo, perché Signaturit può segnalare error per documento in una richiesta che avevi già annullato. Senza di essa, un annullamento deliberato diventa da solo un errore inspiegabile.

L'ultimo tassello: i tre stati terminali negativi (rifiutato, scaduto ed errore) non possono ridursi a un semplice cambio di colore. Nel connettore generano un'attività in sospeso per la persona che ha creato la richiesta, con l'istruzione di decidere se reinviare, prorogare il termine o sostituire. Un rifiuto che nessuno guarda equivale a non accorgersene.

Tentativi e fallimenti: perché un webhook perso è peggio di un errore visibile

Un errore visibile ti ferma. Un webhook perso ti lascia convinto che il documento sia ancora in sospeso quando è firmato da giorni: o viceversa. La seconda situazione costa molto di più, perché nessuno la cerca.

I tentativi devono essere asimmetrici. Nel connettore, ogni chiamata ha un tempo massimo di attesa di 30 secondi per impostazione predefinita, configurabile. Una lettura (GET) viene ritentata fino a due volte, con attesa crescente, davanti a un 429, 500, 502, 503 o 504. Una scrittura (POST, PATCH, DELETE) non viene mai ritentata: ritentare una creazione non idempotente significa mandare lo stesso contratto due volte allo stesso firmatario. Meglio un errore visibile che un duplicato silenzioso. E una regola che di solito manca: un reindirizzamento dell'API viene trattato come errore grave e non si segue mai, perché seguirlo con l'intestazione di autorizzazione presente significa consegnare il tuo token all'indirizzo indicato dal Location.

Il webhook non è la verità: è un campanello. Signaturit non firma crittograficamente i suoi webhook (non c'è HMAC) e la sua documentazione non descrive alcuna politica di ritentativo automatico; offre invece un endpoint per rilanciare un evento a mano. Con questo sul tavolo, l'evento in ingresso nel connettore si autentica con un token per account all'interno dell'URL stesso, si limita facoltativamente all'IP di origine che Signaturit pubblica (uno solo, lo stesso in sandbox e in produzione), si registra con una chiave di deduplicazione SHA-256 del JSON canonicalizzato, e solo allora si interroga di nuovo l'API autenticata. Una consegna duplicata risponde 200 e non viene elaborata due volte.

E se l'evento non arriva mai, c'è una rete di sicurezza: un cron orario scorre fino a 200 richieste in sospeso e le interroga di nuovo. Quella riga è la vera differenza con uno Zap. Lo Zap dipende dal webhook; se il webhook si perde, non c'è nient'altro.

L'allegato che torna: dove si salva, con quale nome e con quale tracciabilità

Quando la richiesta arriva a completata, tornano due file, non uno. Il PDF firmato si archivia come <nombre>.signed.pdf e il documento probatorio come <nombre>.audit_trail.pdf, entrambi allegati al record della richiesta, che a sua volta punta al preventivo, alla fattura o al documento di consegna da cui è nata. Nessuno dei due finisce nella casella di qualcuno.

Un dettaglio che emerge solo in produzione: il documento probatorio non è sempre pronto quando il documento viene firmato. Signaturit lo genera a parte ed emette un evento proprio quando è disponibile. Se il download fallisce, non bisogna lasciare un buco: bisogna richiederne esplicitamente la generazione e recuperarlo nel ciclo successivo. Un connettore che scarica il PDF firmato e dimentica la traccia ti lascia con metà della prova. E se hai chiesto al firmatario di caricare documentazione (documento d'identità, giustificativo di domicilio), quei file si scaricano a parte, in uno ZIP, nello stesso record.

Cosa guardare prima di scegliere l'approccio

1. Quanti tipi di documento invii a firma? Uno solo, uno Zap. Quattro o più, ciascuno con il suo PDF e il suo destinatario, e mantenere quattro Zap costa già più di un modulo.
2. Lo stato della firma cambia qualche decisione dentro Odoo? Se alla firma bisogna fatturare, pianificare o assumere qualcuno, l'ERP ha bisogno dello stato. Se basta avvisare qualcuno, no.
3. Ti serve il documento probatorio archiviato? Se devi mostrarlo a un'ispezione o in una controversia, meglio che sia accanto alla fattura.
4. Cosa succede se nessuno guarda il pannello per due settimane? Chiediti a chi arriva un'attività quando un contratto scade senza firma. Se la risposta è «a nessuno», non hai ancora un'integrazione.
5. Quante versioni di Odoo devi sostenere? Uno Zap non dipende dalla versione; un modulo sì, e il salto da hr.contract a hr.version è il costo reale di questo.
6. Il tuo piano di Signaturit ha l'API? Senza token nessuna delle tre opzioni funziona. Verificalo prima di tutto.

Da dove nasce tutto questo

Abbiamo costruito sette moduli su questa integrazione: il nucleo, che gestisce account, richieste, destinatari, eventi e archiviazione, e sei bridge per CRM, helpdesk, HR, progetti, selezione del personale e magazzino. In totale, 270 test automatizzati nel ramo di Odoo 19, 262 in quello di 18 e 266 in quello di 17: lo stesso codice viene mantenuto contemporaneamente per le tre versioni.

Nessuna delle decisioni di questo articolo nasce dalla lettura della documentazione. Nascono da successivi cicli di QA contro il connettore reale: in un solo ciclo sono stati corretti 23 difetti trovati provandolo dal vivo e altri 5 da un audit avversariale contro la documentazione dell'API; nel successivo, altri 17. Il registro delle modifiche del modulo li elenca uno per uno, con data. Una scheda autogenerata «prodotto A × prodotto B» non ha nessuna di queste cicatrici, perché nessuno l'ha mai usata.

Link utili all'interno di FlexigoTech

Domande frequenti

Cosa facciamo in merito