Files
docuseal-tools/docuseal_signing/README.md
Quentin Mondot fddc2e5c4b
Some checks failed
pre-commit / pre-commit (pull_request) Failing after 1m31s
tests / test (pull_request) Successful in 52s
[FIX] docuseal_signing: harden template copies, API errors and emails
- 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>
2026-11-09 17:35:19 +01:00

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 a res.partner field. 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_url and docuseal.api_token).

Installation

  • Requires Odoo 18.0.
  • Depends only on base and base_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_id and submitter_role_id; the partner's name and email identify 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 to https://sign.elabore.coop.

Credits