SignDocs Brasil

SignDocs Brasil is the official WordPress plugin for legally-binding electronic signatures in Brazil. Embed signing flows on any page with a shortcode or Gutenberg block, send multi-signer envelopes (sequential or parallel), verify signed evidence directly from the WordPress admin, and track everything through an audit log with CSV export.

Built on top of the official SignDocs Brasil PHP SDK (signdocs-brasil/signdocs-brasil-php), the plugin leverages OAuth token caching shared across PHP-FPM workers, deterministic idempotency, webhook secret rotation with a grace window, and observability via RateLimit-* / Deprecation / Sunset response headers.

The plugin targets the Brazilian market (compliance with MP 2.200-2/2001, ICP-Brasil, NT65/ITI for INSS payroll loans), but works for any signing workflow worldwide. The signing UI itself is hosted on sign.signdocs.com.br, isolated from your WordPress install, so a compromised WordPress site cannot forge signatures.

Why SignDocs Brasil?

• Brazilian compliance — MP 2.200-2/2001, PKCS#7/CMS evidence package, ICP-Brasil A1/A3 certificate support, NT65/ITI flow for INSS payroll loans
• Seven verification policies — CLICK_ONLY, CLICK_PLUS_OTP, BIOMETRIC, BIOMETRIC_PLUS_OTP, DIGITAL_CERTIFICATE, BIOMETRIC_SERPRO, BIOMETRIC_SERPRO_AUTO_FALLBACK
• Multi-signer envelopes — sequential (each signer waits for the previous one) or parallel (everyone signs simultaneously), with consolidated .p7s or combined PDF download when complete
• Two authentication modes — OAuth2 client_credentials (simple) or Private Key JWT ES256 (for regulated customers who cannot store shared secrets at rest)
• WooCommerce integration — automatically emails the signing link after order completion
• Complete audit trail — every API call and webhook delivery is logged in a dedicated table with a filterable WP_List_Table view and CSV export
• GDPR / LGPD — data exporter and eraser handlers registered with the WordPress privacy panel
• Observability — RateLimit-* headers captured for the dashboard widget; deprecation warnings (RFC 8594 Deprecation / Sunset) surface as admin notices
• Zero code — configure everything from the WordPress admin

Features

• Shortcode [signdocs] and Gutenberg block to embed the signing button on any post or page
• Custom post type signdocs_envelope for multi-signer workflows with a signer repeater
• “Verify Document” admin page — paste an evidence ID or envelope ID and inspect signer identities, tenant CNPJ, consolidated downloads
• Audit log with filters by level, event type, and date range, plus streaming CSV export (via php://output, safe for multi-GB exports)
• Webhook secret rotation with a 7-day grace window — both secrets (current + previous) are accepted during rotation
• All 17 webhook event types covered, including the NT65 events (STEP.PURPOSE_DISCLOSURE_SENT, TRANSACTION.DEADLINE_APPROACHING)
• Custom capabilities (signdocs_manage, signdocs_send, signdocs_verify, signdocs_view_logs) automatically granted to administrator / editor / author
• WP-CLI commands (wp signdocs health | send | status | webhook-test | log-tail) for shell automation
• WooCommerce integration — “SignDocs Signature” product tab, automatic email with the signing link, order notes after completion
• Popup, redirect, or overlay — pick the embed mode that fits your theme
• Optional anonymous signing with rate limiting
• Credentials encrypted with AES-256-CBC in wp_options
• Hardened webhook receiver: timestamp drift gate (≤300s), HMAC-SHA256 timing-safe verification, replay de-duplication via X-SignDocs-Webhook-Id
• OAuth token cache shared via WordPress transients (WpTransientTokenCache implements the SDK’s TokenCacheInterface) — a single token reused by every PHP-FPM worker
• Deterministic idempotency keys on every resource-creating call — AJAX retries never create duplicate sessions
• Deprecation observer (RFC 8594) that surfaces an admin notice when the API signals an endpoint is being removed
• Translatable: English, Portuguese (Brazil), Spanish

Use cases

• Law firms — powers of attorney, contracts, terms, multi-party envelopes
• Real estate — rental and sale contracts signed by tenant, landlord, and guarantor (sequential envelope)
• E-commerce — terms of service, supplier contracts, post-purchase NDAs
• HR and people ops — employment contracts, NDAs, onboarding paperwork
• Education — enrollment forms and parental consent (parents + student in a parallel envelope)
• SaaS — terms of use and license agreements at onboarding
• INSS payroll loans (Brazil-specific) — NT65 flow with SERPRO biometric verification and purpose disclosure notification
• Banks and financial institutions — Private Key JWT lets you sign without storing a shared secret in the database

How it works

1. Configure your SignDocs Brasil API credentials in the WordPress admin (Client ID + Secret, or Private Key + Key ID)
2. Add a shortcode, Gutenberg block, or create a multi-signer envelope from the admin
3. The signer clicks “Sign Document” and is redirected to the secure domain sign.signdocs.com.br (signing never happens inside your WordPress site — this isolates your install from any compromise)
4. The signer completes the flow according to the configured policy (click, OTP, biometrics, digital certificate)
5. Webhooks update the status in the WordPress admin in real time; the .p7m evidence package becomes available for download and verification

Links

• Official site
• API documentation
• Support
• Create a free account
• GitHub repository

Usage

Shortcode

Add to any page or post:

[signdocs document_id="123" policy="CLICK_ONLY" button_text="Sign Contract"]

With name / email / CPF form:

[signdocs document_id="123" show_form="true" policy="CLICK_PLUS_OTP"]

Available attributes:

• document_id (required) — ID of the PDF attachment in the media library
• policy — one of: CLICK_ONLY, CLICK_PLUS_OTP, BIOMETRIC, BIOMETRIC_PLUS_OTP, DIGITAL_CERTIFICATE, BIOMETRIC_SERPRO, BIOMETRIC_SERPRO_AUTO_FALLBACK
• locale — language: pt-BR, en, es
• mode — embed mode: redirect (default), popup, overlay
• button_text — button label (default: “Sign Document”)
• show_form — "true" to display name / email / CPF / CNPJ inputs
• return_url — URL to redirect to after signing
• class — additional CSS class for the button

Gutenberg block

1. In the block editor, click “+” to add a block
2. Search for “SignDocs” or “Signature”
3. Pick a PDF in the right sidebar
4. Configure the policy, locale, and mode
5. Publish the page

Multi-signer envelopes

For contracts with more than one signer (for example, landlord + tenant + guarantor), use the Envelopes menu:

1. WP Admin > Signatures > Envelopes > Add New
2. Select the signing mode:
   • SEQUENTIAL — each signer signs in order; the next signer only receives their link when the previous one completes
   • PARALLEL — all signers can sign simultaneously, in any order
3. Add the signers (name + email + CPF or CNPJ + optional per-signer policy)
4. Attach the PDF and publish
5. Each signer receives an email with their individual link; the admin sees the envelope status update as each signature completes
6. After everyone has signed, a combined stamped PDF (or consolidated .p7s for non-PDF documents) becomes available for download

The webhook events STEP.STARTED, STEP.COMPLETED, and STEP.FAILED are recorded per signer in each envelope’s log.

WooCommerce

1. Edit a product and open the “SignDocs Signature” tab
2. Check “Requires signature” and select the PDF
3. Configure the verification policy
4. When an order completes, the signing link is automatically emailed to the customer
5. After signing, an order note is added with the evidence ID

The customer’s CPF or CNPJ must be present in the order. The plugin reads the standard _billing_cpf / _billing_cnpj order meta keys used by the Brazilian Market on WooCommerce extension. If neither is present, the plugin adds an order note explaining the requirement and skips session creation.

Document verification

The Signatures > Verify page (requires the signdocs_verify capability):

1. Paste an evidence_id (single signature) or envelope_id (multi-signer)
2. The plugin calls GET /v1/verify/{id} or GET /v1/verify/envelope/{id} and renders:
   • Identities of every signer (name, CPF/CNPJ)
   • Tenant CNPJ
   • Timestamps for each step
   • The applied policy profile
   • Download links: evidence package (.p7m), signed PDF, consolidated .p7s (envelopes), combined PDF (envelopes)
3. Use the evidence files in external validators (ITI Validador, Adobe Acrobat) for independent confirmation

Audit log

The Signatures > Audit Log page (requires the signdocs_view_logs capability):

• WP_List_Table view over {prefix}signdocs_log
• Filters: level (debug / info / warning / error), event type, date range
• CSV export via admin-post.php (chunked streaming, safe for multi-GB exports)
• Automatic 30-day retention via the daily signdocs_prune_logs cron
• Every API call, webhook delivery, and deprecation warning is recorded with JSON context

WP-CLI

For shell-based operations (useful for automation, CI/CD, and troubleshooting):

wp signdocs health

— check connectivity to the API in the configured environment

wp signdocs send --document=42 --email=alice@example.com --cpf=12345678901 --policy=CLICK_PLUS_OTP

— create a signing session from a WordPress attachment and print the session ID and URL

wp signdocs status <sessionId>

— look up the status of a session by ID

wp signdocs webhook-test <webhookId>

— send a test delivery to a registered webhook

wp signdocs log-tail --level=warning --limit=20

— show the last N entries of the audit log filtered by level

Webhook secret rotation

1. In Settings > SignDocs Brasil, click “Rotate Secret”
2. The plugin requests a new secret from the API; the previous secret becomes the “previous secret” with a 7-day grace window
3. During the window, the /wp-json/signdocs/v1/webhook endpoint accepts both secrets — in-flight deliveries are not rejected
4. After 7 days, the daily signdocs_expire_prev_secret cron removes the old secret
5. The rotation status is visible in the admin (with a countdown)

For developers

Available hooks:

Session lifecycle:

• signdocs_session_created — Session created (via the API, not necessarily via WordPress)
• signdocs_signing_completed — Signing completed successfully
• signdocs_signing_cancelled — Signing cancelled by the integrator or the signer
• signdocs_signing_expired — Session expired without completion
• signdocs_signing_failed — Signing failed (unrecoverable error)
• signdocs_transaction_fallback — Fallback was triggered (e.g., SERPRO unavailable)

Per-step (for envelopes and custom flows):

• signdocs_step_started — Step started (OTP sent, biometric capture, etc.)
• signdocs_step_completed — Step completed
• signdocs_step_failed — Step failed
• signdocs_purpose_disclosure_sent — (NT65) Purpose disclosure notification delivered to the beneficiary
• signdocs_deadline_approaching — (NT65) ≤2 business days left before the INSS submission deadline

Tenant / API:

• signdocs_quota_warning — Tenant usage crossed a threshold (80 / 90 / 100%)
• signdocs_api_deprecation_notice — API signaled a deprecated endpoint

WooCommerce:

• signdocs_wc_signing_completed — A WooCommerce order signing completed

Each action receives $post_id (of the signdocs_signing or signdocs_envelope CPT) and $payload (the raw webhook array) as arguments, except signdocs_quota_warning and signdocs_api_deprecation_notice which receive only the payload.

Capabilities:

• signdocs_manage — Configure credentials, webhook, branding; manage other users’ envelopes
• signdocs_send — Create sessions and envelopes
• signdocs_verify — Use the Verify page and inspect evidence
• signdocs_view_logs — Access the audit log and export CSV

Use current_user_can('signdocs_send') instead of manage_options / edit_posts when adding custom functionality.

PHP SDK:

The configured SDK client (with encrypted credentials and shared token cache) is available via:

$client = Signdocs_Client_Factory::get(); // SignDocsBrasil\Api\SignDocsBrasilClient or null

See the PHP SDK documentation for the full surface (transactions, envelopes, verification, users, documentGroups, webhooks, etc.).

External services

This plugin connects to the SignDocs Brasil platform — operated by the same company that publishes the plugin — to create, deliver, and verify electronic signatures. The plugin cannot function without sending data to these endpoints, because the signing itself happens on the SignDocs servers (the WordPress site only orchestrates the request and stores the result reference).

SignDocs Brasil API (api.signdocs.com.br / api-hml.signdocs.com.br)

Used to create signing sessions, register webhooks, verify signed evidence, and manage multi-signer envelopes. The plugin authenticates with the API credentials you enter in the WordPress admin (OAuth2 client_credentials, or alternatively Private Key JWT when configured).

• What data is sent, per signing-session create: the PDF document content (base64-encoded), the signer’s name, the signer’s email address, the signer’s CPF or CNPJ (one is required by the API), the selected verification policy (e.g. CLICK_ONLY, BIOMETRIC), the language preference, an optional return URL, and metadata fields identifying the WordPress site URL and source surface (shortcode, AJAX, WP-CLI, WooCommerce, envelope).
• When: every time a signing session is created. This happens on shortcode AJAX submission, on wp signdocs send from the WP-CLI, on WooCommerce order completion when the product is configured for signing, and on every envelope creation / new-signer add.
• Other API calls that send no document data: webhook registration, status polling (GET /v1/signing-sessions/{id}), evidence verification (GET /v1/verify/{evidenceId}), envelope status. These send only the relevant identifier you provide (session ID, evidence ID, envelope ID).
• Authentication: every API call is authenticated with a short-lived Bearer token obtained from the OAuth2 token endpoint at the same domain (POST {baseUrl}/oauth2/token). The plugin sends your Client ID and either Client Secret or a signed JWT assertion (when Private Key JWT mode is configured) to that endpoint at first call and again when the cached token expires (typically once per hour per environment); the access token is cached in a WordPress transient and reused across all subsequent API calls. No signer data is sent to the token endpoint.
• Environment switch: the plugin uses api-hml.signdocs.com.br (HML / sandbox) by default, and api.signdocs.com.br only when the administrator explicitly switches the environment to “Production” in the settings page.
• Provided by SignDocs Brasil. Terms of Use. Privacy Policy.

SignDocs Brasil browser SDK (cdn.signdocs.com.br / cdn-hml.signdocs.com.br)

A JavaScript file (signdocs-brasil.js) loaded from the SignDocs CDN that opens the signing popup, redirect, or overlay when the signer clicks the embedded “Sign Document” button rendered by the shortcode or Gutenberg block.

• What data is sent: nothing directly by this script load — it is a static asset request, the same as any other JavaScript file from a third-party CDN. No personally identifiable information is transmitted by the CDN request itself; the script is bytes-identical for every site that loads it.
• When: every front-end page-view that renders the [signdocs] shortcode or the SignDocs Gutenberg block (the script is enqueued conditionally — pages without the block do not load it).
• The CDN environment (HML vs prod) follows the same signdocs_environment option as the API.
• Provided by SignDocs Brasil. Terms of Use. Privacy Policy.

SignDocs Brasil signing UI (sign.signdocs.com.br)

After the signer clicks “Sign Document”, they are taken to the secure signing page on sign.signdocs.com.br — not to a page hosted by your WordPress site. The signing flow (OTP, biometric capture, digital-certificate selection, click-only confirmation) executes entirely on this domain. This isolation is intentional: even if your WordPress site were compromised, an attacker could not forge signatures because the authentication factors are collected on a separate origin under SignDocs Brasil’s control.

• What data is sent: the signer interacts directly with this domain to complete the signing flow. The data exchanged here (OTP codes, biometric photos, certificate selections) does not pass through your WordPress site. Your plugin only receives the result back via the webhook described above.
• When: when the signer clicks the signing button rendered by the plugin and the browser SDK opens the signing surface (popup / redirect / overlay).
• Provided by SignDocs Brasil. Terms of Use. Privacy Policy.