- Do not copy the contextual action nor the submitter role with a template: a copy sharing the action would rewrite or delete the original's. - Make the template ID read-only once fetched from Docuseal: another Docuseal template needs a new entry. - Report an invalid API URL or token, an unexpected (non-JSON) response and a connection dropped mid-response as a readable UserError. - Refuse to email a signature request to contacts without a valid email address (email_normalize), before any call to Docuseal. - Stop logging the field values and the Docuseal response, which hold personal data and the signing links. - Prevent adding mapping lines by hand: they come from Docuseal only. Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>
4.4 KiB
4.4 KiB
Docuseal Signing
Electronic signature integration between Odoo and a Docuseal instance: configure signature templates in Odoo, pre-fill them with contact data and request signatures from partners in a few clicks.
Features
- Template registry (
docuseal.template): reference Docuseal templates by their ID; the Fetch from Docuseal button loads their submitter roles and fields from the Docuseal API. The submitter role is picked from a dropdown listing only the roles of the template (docuseal.template.role); the first one is selected by default. - Field mapping (
docuseal.template.field): map each Docuseal field of the selected role to ares.partnerfield. Fetching again keeps the existing mappings; changing the role loads the fields of the new role from Docuseal with an empty mapping (with a warning in the form). Once fetched, the template ID is read-only: another Docuseal template needs a new entry. Fields are kept in the order returned by the Docuseal API (reorderable with drag & drop). Values are pre-filled at submission time and locked so the signer cannot change them (empty mappings stay editable by the signer). - One-click signature request: generate a server action bound to
res.partner(contextual Action menu entry) that creates a Docuseal submission for the selected contact and emails them the signature request. It is reserved to administrators (base.group_system, who manage the Docuseal templates), and only runs on a single contact so that a failure never leaves some contacts already emailed. A draft mode (_create_draft_submissions) creates the pre-filled submission without sending the email, so it can be sent from Docuseal. - Settings: configure the Docuseal API URL and API token in
Settings → General Settings (system parameters
docuseal.api_urlanddocuseal.api_token).
Installation
- Requires Odoo 18.0.
- Depends only on
baseandbase_setup; no extra Python package (API calls use the standard library). - A reachable Docuseal instance with an API token is needed at runtime.
Technical usage
The module adds two methods for developers and server actions.
Request a signature from code
template = self.env["docuseal.template"].search(
[("template_id", "=", 12345)], limit=1
)
partners = self.env["res.partner"].browse([42, 43])
# Create a submission per partner and let Docuseal email the
# signature request:
results = template._create_submissions(partners)
# Or create pre-filled drafts without sending the email: the
# submission must then be sent from Docuseal.
template._create_draft_submissions(partners)
Behavior of both calls:
- One Docuseal submission is created per partner, using the template's
Docuseal
template_idandsubmitter_role_id; the partner'snameandemailidentify the submitter. When the request is emailed, every partner must have an email address: otherwise nothing is sent. - Each mapped Docuseal field is pre-filled from the partner field set
in
docuseal.template.field. Non-empty values are locked (readonly=True) so the signer cannot change them; empty values stay editable. - Date values are formatted as
%d/%m/%Y, many2one/many2many values as a comma-joined list of display names, and selection values as their human-readable label. - Both methods return the list of Docuseal API responses (one dict per
submission). A missing API token or a Docuseal error (with the
explanation sent by Docuseal), an invalid API URL or an unreachable
instance raises a
UserError; with several partners, the submissions created before the error are not rolled back in Docuseal.
From a server action
The generated contextual action calls _action_request_signature,
which refuses a selection of several contacts, then _create_submissions
and shows a confirmation notification:
action = env['docuseal.template'].browse(<template_record_id>)._action_request_signature(records)
Configuration
Both methods read the API credentials from system parameters
(ir.config_parameter):
docuseal.api_token— the Docuseal API token (required), set in Settings → General Settings.docuseal.api_url— the Docuseal instance base URL, defaulting tohttps://sign.elabore.coop.
Credits
- Contributors: Quentin Mondot quentin@elabore.coop
- Maintainer: Elabore