Signaturit a Odoo: què et dona un mòdul natiu que no et dona Zapier

Resposta curta: Zapier et serveix per disparar una signatura i assabentar-te que s'ha completat. No et serveix per reflectir dins d'Odoo els estats intermedis pels quals passa un document, ni per recuperar-te d'un webhook perdut, ni per deixar el PDF signat i el seu document probatori arxivats al registre correcte. Si el teu procés acaba quan el client signa, un Zap és suficient i és més barat. Si el teu procés comença quan el client signa (facturar, obrir expedient, donar d'alta un empleat), necessites els estats dins de l'ERP.

El punt de partida: el document viatja per correu

El circuit habitual té tres salts manuals: algú genera el PDF del pressupost a Odoo, el puja al tauler de Signaturit i espera; quan el client signa, el PDF signat arriba a la safata d'una persona; aquesta persona el torna a pujar a Odoo, si se'n recorda. Els símptomes són sempre els mateixos: ningú sap si el client l'ha obert, el PDF signat acaba a l'escriptori d'algú, i quan cal la prova (el document probatori, l'audit trail) no és al costat de la factura, que és on qualsevol la buscaria.

Abans de res, un requisit que afecta els tres camins per igual: el teu pla de Signaturit ha d'incloure accés a l'API. L'autenticació és un token Bearer que es treu del tauler, i sandbox i producció són dos registres diferents amb dos tokens diferents. Signaturit no publica en obert quins plans inclouen aquest accés, així que confirma-ho amb ells abans de dissenyar res. Sense token no hi ha ni Zap, ni n8n, ni mòdul.

Les tres maneres d'unir-los, i on n'hi ha prou amb Zapier

L'app de Signaturit a Zapier publica, a hores d'ara, un únic trigger («New Signed Document», és a dir, «un document s'ha signat») i cinc accions: crear una sol·licitud de signatura, crear-la des d'una plantilla, cancel·lar-la, enviar un recordatori i crear un correu certificat. L'app d'Odoo autoallotjat, per la seva banda, exposa triggers i accions genèrics de registre (crear un registre, un lead, una tasca…). Aquesta és tota la matèria primera disponible.

On n'hi ha prou amb Zapier (i pots deixar de llegir)

Si envies un sol tipus de document, pocs al mes, i només necessites que en signar-se es creï una tasca o s'avisi per xat, munta un Zap i no hi donis més voltes. També n'hi ha prou si el document no neix a Odoo (una NDA preparada al tauler de Signaturit). La regla és aquesta: si l'estat de la signatura no canvia cap decisió dins de l'ERP, l'ERP no necessita saber-ho.

Quin document surt de quin model d'Odoo

Aquesta és la part que un pas genèric de «crear registre» no pot fer: no sap renderitzar l'informe QWeb d'una comanda de venda. Cada model necessita tres coses seves: el títol que veurà el signant, el destinatari per defecte i com es genera el PDF. Al connector que hem construït, cada pont resol exactament aquests tres punts.

• Pressupost i comanda de venda (sale.order): l'informe estàndard de comanda de venda, amb el client com a signant.
• Factura (account.move) i comanda de compra (purchase.order), per a acceptacions i confirmacions de proveïdor.
• Albarà de lliurament (stock.picking): l'informe d'albarà, que un cop signat funciona com a prova de lliurament.
• Contracte laboral: hr.contract a Odoo 17 i 18, i hr.version a Odoo 19, on el mòdul de RRHH es va refondre. El tipus de detall que obliga a mantenir tres branques del codi, no una.
• Oferta a un candidat (hr.applicant), oportunitat de CRM (crm.lead), tiquet (helpdesk.ticket) i projecte i tasca, per a acceptacions de feina feta.

El cicle d'estats complet, que és on cau tot el que no el té

L'API v3 de Signaturit informa, per document, de vuit estats: in_queue, ready, signing, completed, expired, canceled, declined i error. Els seus esdeveniments de webhook són encara més granulars: correu lliurat, correu rebotat, document obert, document signat, document d'identitat afegit, caducitat ampliada, audit trail generat…

Dins d'Odoo això s'ha de convertir en dues coses diferents. Primera: la sol·licitud en si, amb el seu propi cicle (esborrany, enviada, en curs, completada, rebutjada, caducada, cancel·lada, error). Segona: un camp al document d'origen, perquè el comercial que obre el pressupost vegi l'estat sense sortir del pressupost. Al nostre connector aquest camp té set valors: sense enviar, pendent de signatura, signat, rebutjat, caducat, cancel·lat i error.

Amb diversos signants, l'estat s'ha de deduir del conjunt: tots completats, completada; un que rebutja, rebutjada; uns signats i altres no, en curs. I hi ha una protecció que només s'aprèn fallant: una sol·licitud cancel·lada a mà no s'ha de deixar sobreescriure mai per un esdeveniment posterior, perquè Signaturit pot reportar error per document en una sol·licitud que tu ja havies cancel·lat. Sense ella, una cancel·lació deliberada es converteix sola en un error inexplicable.

L'última peça: els tres estats terminals dolents (rebutjat, caducat i error) no poden acabar només canviant un color. Al connector generen una activitat pendent per a la persona que va crear la sol·licitud, amb la instrucció de decidir si es reenvia, s'amplia el termini o es reemplaça. Un rebuig que ningú mira és exactament igual que no assabentar-se'n.

Reintents i fallades: per què un webhook perdut és pitjor que un error visible

Un error visible t'atura. Un webhook perdut et deixa creient que el document encara és pendent quan fa dies que està signat: o al revés. La segona situació és molt més cara, perquè ningú la busca.

Els reintents han de ser asimètrics. Al connector, cada crida té un temps màxim d'espera de 30 segons per defecte, configurable. Una lectura (GET) es reintenta fins a dues vegades, amb espera creixent, davant d'un 429, 500, 502, 503 o 504. Una escriptura (POST, PATCH, DELETE) no es reintenta mai: reintentar una creació que no és idempotent significa enviar el mateix contracte dues vegades al mateix signant. Val més un error visible que un duplicat silenciós. I una regla que sol faltar: una redirecció de l'API es tracta com a error dur i no se segueix mai, perquè seguir-la amb la capçalera d'autorització posada és lliurar el teu token a l'adreça que digui el Location.

El webhook no és la veritat: és un timbre. Signaturit no signa criptogràficament els seus webhooks (no hi ha HMAC) i la seva documentació no descriu cap política de reintent automàtic; sí que ofereix un endpoint per rellançar un esdeveniment a mà. Amb això damunt la taula, l'esdeveniment entrant al connector s'autentica amb un token per compte dins de la mateixa URL, opcionalment es restringeix a la IP d'origen que Signaturit publica (una sola, la mateixa en sandbox i en producció), es registra amb una clau de deduplicació SHA-256 del JSON canonitzat, i llavors (i només llavors) es torna a preguntar a l'API autenticada. Un lliurament duplicat respon 200 i no es processa dues vegades.

I si l'esdeveniment no arriba mai, hi ha una xarxa de seguretat: un cron horari recorre fins a 200 sol·licituds pendents i les torna a consultar. Aquesta línia és la diferència real amb un Zap. El Zap depèn del webhook; si el webhook es perd, no hi ha res més.

L'adjunt que torna: on es guarda, amb quin nom i amb quina auditoria

Quan la sol·licitud arriba a completada, tornen dos fitxers, no un. El PDF signat s'arxiva com <nombre>.signed.pdf i el document probatori com <nombre>.audit_trail.pdf, tots dos adjunts al registre de la sol·licitud, que alhora apunta al pressupost, la factura o l'albarà del qual va sortir. Cap dels dos acaba a la safata de ningú.

Un detall que només apareix en producció: el document probatori no sempre està llest quan el document se signa. Signaturit el genera a part i emet un esdeveniment propi quan està disponible. Si la descàrrega falla, no s'ha de deixar un buit: s'ha de demanar explícitament la seva generació i recuperar-lo en el cicle següent. Un connector que es baixi el PDF signat i s'oblidi de la traça et deixa amb la meitat de la prova. I si has demanat al signant que pugi documentació (DNI, justificant de domicili), aquests fitxers es baixen a part, en un ZIP, al mateix registre.

Què mirar abans d'escollir enfocament

1. Quants tipus de document envies a signar? Un de sol, un Zap. Quatre o més, cadascun amb el seu PDF i el seu destinatari, i mantenir quatre Zaps ja costa més que un mòdul.
2. L'estat de la signatura canvia alguna decisió dins d'Odoo? Si en signar-se cal facturar, planificar o donar d'alta algú, l'ERP necessita l'estat. Si només cal avisar algú, no.
3. Necessites el document probatori arxivat? Si l'has d'ensenyar a una inspecció o en un litigi, millor que sigui al costat de la factura.
4. Què passa si ningú mira el tauler durant dues setmanes? Pregunta a qui li salta una tasca quan un contracte caduca sense signar. Si la resposta és «a ningú», encara no tens integració.
5. Quantes versions d'Odoo has de sostenir? Un Zap no depèn de la versió; un mòdul sí, i el salt de hr.contract a hr.version és el cost real d'això.
6. El teu pla de Signaturit té API? Sense token no funciona cap de les tres opcions. Comprova-ho abans de res.

D'on surt tot això

Hem construït set mòduls sobre aquesta integració: el nucli, que resol comptes, sol·licituds, destinataris, esdeveniments i arxiu, i sis ponts per a CRM, servei d'assistència, RRHH, projectes, selecció de personal i magatzem. En total, 270 proves automatitzades a la branca d'Odoo 19, 262 a la de 18 i 266 a la de 17: el mateix codi es manté alhora per a les tres versions.

Cap de les decisions d'aquest article surt de llegir la documentació. Surten de rondes successives de QA contra el connector real: en una sola ronda es van corregir 23 defectes trobats provant-lo en viu i 5 més d'una auditoria adversarial contra la documentació de l'API; en la següent, 17 més. El registre de canvis del mòdul els enumera un per un, amb data. Una fitxa autogenerada de «producte A × producte B» no té cap d'aquestes cicatrius, perquè ningú l'ha fet servir mai.

Enllaços útils dins de FlexigoTech

Preguntes freqüents

El que fem sobre això