Files
docuseal-tools/docuseal_signing/README.md
Quentin Mondot c7f3a2dcfe
Some checks failed
tests / test (pull_request) Successful in 56s
pre-commit / pre-commit (pull_request) Failing after 1m34s
[IMP] docuseal_signing: pick the submitter role from the Docuseal roles
The submitter role was a free text field. It is now a dropdown listing
only the submitter roles of the Docuseal template
(docuseal.template.role), fetched with the Docuseal UUID of each role.

- The "Fetch from Docuseal" button, now above the role, syncs the roles
  (matched by UUID then name, in the Docuseal order, the first one
  selected by default) and the fields of the selected role only,
  keeping the existing mappings.
- Changing the role fetches the fields of the new role from Docuseal
  with an empty mapping, and warns that saving loses the current one.
- Signature requests only send the fields of the submitter role.
- Docuseal API errors and a missing token raise a clear UserError.
- Keep the Docuseal field name of new mapping lines on save
  (force_save on the read-only column).

Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 16:47:05 +01:00

3.7 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. 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 contacts and emails them the signature request. 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.
  • 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); errors bubble up as exceptions if the API call fails.

From a server action

The generated contextual action calls the same entry point on the selected records:

env['docuseal.template'].browse(<template_record_id>)._create_submissions(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