Signaturit in Odoo: wat een native module je geeft en Zapier niet

Kort antwoord: met Zapier kun je een ondertekening starten en te weten komen dat ze is afgerond. Het volstaat niet om de tussenstatussen van een document in Odoo weer te geven, om te herstellen van een verloren webhook, of om de getekende PDF en het bijbehorende bewijsdocument op het juiste record te archiveren. Als je proces eindigt wanneer de klant tekent, is een Zap genoeg en goedkoper. Als je proces begint wanneer de klant tekent (factureren, een dossier openen, een werknemer aanmaken), heb je de statussen in het ERP nodig.

Het startpunt: het document gaat per e-mail op reis

Het gebruikelijke circuit heeft drie handmatige stappen: iemand genereert de PDF van de offerte in Odoo, uploadt die naar het Signaturit-paneel en wacht; als de klant tekent, komt de getekende PDF in iemands inbox; die persoon uploadt hem opnieuw naar Odoo, als hij eraan denkt. De symptomen zijn altijd dezelfde: niemand weet of de klant het document heeft geopend, de getekende PDF belandt op iemands bureaublad, en als het bewijs nodig is (het bewijsdocument, de audit trail) ligt het niet naast de factuur, waar iedereen het zou zoeken.

Eerst nog een vereiste die voor alle drie de wegen geldt: je Signaturit-abonnement moet toegang tot de API bevatten. De authenticatie is een Bearer-token dat je uit het paneel haalt, en sandbox en productie zijn twee aparte records met twee verschillende tokens. Signaturit publiceert niet openlijk welke abonnementen die toegang bevatten, dus bevestig het bij hen voordat je iets ontwerpt. Zonder token is er geen Zap, geen n8n en geen module.

De drie manieren om ze te koppelen, en waar Zapier volstaat

De Signaturit-app in Zapier publiceert op dit moment één trigger ("New Signed Document", dus "een document is ondertekend") en vijf acties: een handtekeningaanvraag maken, er een maken vanuit een sjabloon, annuleren, een herinnering sturen en een gecertificeerde e-mail maken. De app voor zelf gehoste Odoo biedt op zijn beurt generieke triggers en acties voor records (een record, een lead, een taak aanmaken…). Dat is alle beschikbare grondstof.

Waar Zapier volstaat (en je kunt stoppen met lezen)

Als je één type document verstuurt, weinig per maand, en je alleen wilt dat er bij ondertekening een taak wordt aangemaakt of een chatmelding komt, bouw dan een Zap en denk er verder niet over na. Het volstaat ook als het document niet in Odoo ontstaat (een NDA die in het Signaturit-paneel is voorbereid). De regel is deze: als de status van de handtekening geen enkele beslissing in het ERP verandert, hoeft het ERP hem niet te kennen.

Welk document komt uit welk Odoo-model

Dit is het deel dat een generieke stap "record aanmaken" niet kan: die weet niet hoe je het QWeb-rapport van een verkooporder rendert. Elk model heeft drie eigen dingen nodig: de titel die de ondertekenaar ziet, de standaardontvanger en hoe de PDF wordt gegenereerd. In de connector die wij hebben gebouwd, lost elke brug precies die drie punten op.

• Offerte en verkooporder (sale.order): het standaardrapport van de verkooporder, met de klant als ondertekenaar.
• Factuur (account.move) en inkooporder (purchase.order), voor aanvaardingen en bevestigingen van leveranciers.
• Leveringsbon (stock.picking): het leveringsrapport, dat na ondertekening dient als bewijs van levering.
• Arbeidscontract: hr.contract in Odoo 17 en 18, en hr.version in Odoo 19, waar de HR-module opnieuw is opgezet. Het soort detail dat dwingt tot drie codebranches in plaats van één.
• Aanbod aan een kandidaat (hr.applicant), CRM-verkoopkans (crm.lead), ticket (helpdesk.ticket) en project en taak, voor aanvaarding van uitgevoerd werk.

De volledige statuscyclus, waar al het andere faalt

De Signaturit API v3 meldt per document acht statussen: in_queue, ready, signing, completed, expired, canceled, declined en error. De webhook-events zijn nog fijnmaziger: e-mail afgeleverd, e-mail gebounced, document geopend, document ondertekend, identiteitsdocument toegevoegd, vervaldatum verlengd, audit trail gegenereerd…

Binnen Odoo moet dat in twee verschillende dingen worden vertaald. Eerste: de aanvraag zelf, met een eigen cyclus (concept, verzonden, in behandeling, voltooid, geweigerd, verlopen, geannuleerd, fout). Tweede: een veld op het brondocument, zodat de verkoper die de offerte opent de status ziet zonder de offerte te verlaten. In onze connector heeft dat veld zeven waarden: niet verzonden, wacht op handtekening, ondertekend, geweigerd, verlopen, geannuleerd en fout.

Bij meerdere ondertekenaars moet de status uit het geheel worden afgeleid: allemaal voltooid, voltooid; één die weigert, geweigerd; sommigen ondertekend en anderen niet, in behandeling. En er is een bescherming die je alleen leert door te falen: een handmatig geannuleerde aanvraag mag nooit door een latere gebeurtenis worden overschreven, want Signaturit kan per document error melden bij een aanvraag die jij al had geannuleerd. Zonder die bescherming wordt een bewuste annulering vanzelf een onverklaarbare fout.

Het laatste stuk: de drie slechte eindstatussen (geweigerd, verlopen en fout) mogen niet eindigen in alleen een kleurwijziging. In de connector genereren ze een openstaande activiteit voor de persoon die de aanvraag heeft gemaakt, met de instructie om te beslissen of ze opnieuw wordt verzonden, de termijn wordt verlengd of ze wordt vervangen. Een weigering die niemand ziet, is precies hetzelfde als het niet weten.

Herpogingen en fouten: waarom een verloren webhook erger is dan een zichtbare fout

Een zichtbare fout stopt je. Een verloren webhook laat je geloven dat het document nog openstaat terwijl het al dagen is ondertekend: of andersom. De tweede situatie is veel duurder, want niemand zoekt ernaar.

Herpogingen moeten asymmetrisch zijn. In de connector heeft elke aanroep standaard een maximale wachttijd van 30 seconden, instelbaar. Een leesactie (GET) wordt tot twee keer herhaald, met oplopende wachttijd, bij een 429, 500, 502, 503 of 504. Een schrijfactie (POST, PATCH, DELETE) wordt nooit herhaald: een aanmaak die niet idempotent is opnieuw proberen betekent hetzelfde contract twee keer naar dezelfde ondertekenaar sturen. Een zichtbare fout is beter dan een stil duplicaat. En een regel die vaak ontbreekt: een redirect van de API wordt behandeld als harde fout en nooit gevolgd, want hem volgen met de autorisatieheader erbij is je token afgeven aan het adres dat de Location aangeeft.

De webhook is niet de waarheid: het is een deurbel. Signaturit ondertekent zijn webhooks niet cryptografisch (er is geen HMAC) en zijn documentatie beschrijft geen enkel automatisch herpogingsbeleid; wel biedt het een endpoint om een event handmatig opnieuw af te vuren. Met dat op tafel wordt het binnenkomende event in de connector geauthenticeerd met een token per account in de URL zelf, optioneel beperkt tot het bron-IP dat Signaturit publiceert (één enkel, hetzelfde in sandbox en productie), vastgelegd met een deduplicatiesleutel SHA-256 van de gecanonicaliseerde JSON, en dan (en alleen dan) wordt de geauthenticeerde API opnieuw bevraagd. Een dubbele aflevering antwoordt 200 en wordt niet twee keer verwerkt.

En als het event nooit aankomt, is er een vangnet: een cron per uur loopt tot 200 openstaande aanvragen langs en raadpleegt ze opnieuw. Die regel is het echte verschil met een Zap. De Zap hangt af van de webhook; als de webhook verloren gaat, is er niets anders.

De bijlage die terugkomt: waar ze wordt opgeslagen, onder welke naam en met welke audit

Wanneer de aanvraag voltooid is, komen er twee bestanden terug, niet één. De getekende PDF wordt gearchiveerd als <nombre>.signed.pdf en het bewijsdocument als <nombre>.audit_trail.pdf, beide als bijlage bij het record van de aanvraag, dat op zijn beurt verwijst naar de offerte, de factuur of de levering waaruit het voortkwam. Geen van beide belandt in iemands inbox.

Een detail dat alleen in productie opduikt: het bewijsdocument is niet altijd klaar op het moment dat het document wordt ondertekend. Signaturit genereert het apart en stuurt een eigen event als het beschikbaar is. Als de download mislukt, mag er geen gat blijven: je moet de generatie expliciet aanvragen en het in de volgende cyclus ophalen. Een connector die de getekende PDF binnenhaalt en het spoor vergeet, laat je met het halve bewijs achter. En als je de ondertekenaar hebt gevraagd documentatie te uploaden (identiteitsbewijs, bewijs van woonadres), worden die bestanden apart gedownload, in een ZIP, naar hetzelfde record.

Waar je op moet letten voordat je een aanpak kiest

1. Hoeveel typen documenten stuur je ter ondertekening? Eén enkel type, een Zap. Vier of meer, elk met zijn eigen PDF en ontvanger, en vier Zaps onderhouden kost al meer dan een module.
2. Verandert de status van de handtekening een beslissing binnen Odoo? Als er bij ondertekening gefactureerd, gepland of iemand aangemaakt moet worden, heeft het ERP de status nodig. Als alleen iemand verwittigd moet worden, niet.
3. Heb je het bewijsdocument gearchiveerd nodig? Als je het moet tonen bij een inspectie of in een geschil, staat het beter naast de factuur.
4. Wat gebeurt er als niemand twee weken naar het paneel kijkt? Vraag wie een taak krijgt wanneer een contract verloopt zonder ondertekening. Als het antwoord "niemand" is, heb je nog geen integratie.
5. Hoeveel Odoo-versies moet je ondersteunen? Een Zap hangt niet af van de versie; een module wel, en de stap van hr.contract naar hr.version is de echte kost daarvan.
6. Heeft je Signaturit-abonnement API? Zonder token werkt geen van de drie opties. Controleer het eerst.

Waar dit allemaal vandaan komt

We hebben zeven modules op deze integratie gebouwd: de kern, die accounts, aanvragen, ontvangers, events en archief afhandelt, en zes bruggen voor CRM, helpdesk, HR, projecten, werving en selectie en magazijn. In totaal 270 geautomatiseerde tests in de branch van Odoo 19, 262 in die van 18 en 266 in die van 17: dezelfde code wordt tegelijk voor de drie versies onderhouden.

Geen van de beslissingen in dit artikel komt voort uit het lezen van de documentatie. Ze komen uit opeenvolgende QA-rondes tegen de echte connector: in één ronde werden 23 gebreken verholpen die bij live testen werden gevonden en 5 meer uit een adversariële audit tegen de API-documentatie; in de volgende, 17 meer. Het wijzigingslogboek van de module somt ze een voor een op, met datum. Een automatisch gegenereerde pagina "product A × product B" heeft geen van die littekens, want niemand heeft ze ooit gebruikt.

Nuttige links binnen FlexigoTech

Veelgestelde vragen

Wat wij hierover doen