@assinafy/n8n-nodes-assinafy

Português (Brasil) · English

Community n8n nodes for Assinafy, the Brazilian electronic-signature platform. The package is centered on document upload, signer creation, assignments, signing status, certified-artifact downloads, templates, tags, and webhooks. Related account and authentication operations remain available when a workflow needs them.

This package ships:

• Assinafy — an action node for assignment, auth, document, field, oauth, signer, signerDocument, tag, template, webhook, and workspace resources.
• Assinafy Trigger — a webhook trigger that registers its own webhook endpoint, with mandatory credential-derived URL authentication and optional Standard Webhooks signature verification.
• Assinafy OAuth2 API — authorization code with PKCE, encrypted token storage and automatic refresh managed by n8n.
• Assinafy API — a shared credential (X-Api-Key + account ID, with production/sandbox/custom base URLs).

Installation

Public releases use npmjs.com under @assinafy/n8n-nodes-assinafy; installation does not require a custom registry or .npmrc.

Self-hosted n8n

In n8n, open Settings → Community Nodes → Install, enter @assinafy/n8n-nodes-assinafy, and follow the installation prompts. For a manual installation, install the package in your instance's community-node directory and restart n8n. See the official installation guide for containers and queue workers.

GitHub Packages may be used as an optional release mirror. Installing from that mirror requires an @assinafy:registry=https://npm.pkg.github.com scope mapping and a GitHub token with read:packages; those settings are not needed for the primary npmjs package.

n8n Cloud

Publication to npmjs is required for n8n's verified community-node submission process. Availability in n8n Cloud still depends on n8n review and catalog approval; npm publication alone does not imply Cloud availability.

The package declares n8n-workflow as a peer dependency so the installed n8n instance supplies the runtime. Use Node.js 24.21.0 LTS for development, builds, and tests. Your n8n runtime must satisfy the package's node >=24.21.0 requirement; the official n8n image supplies its own compatible Node.js version. Assinafy accepts only HTTPS with TLS 1.2 or higher, which Node.js uses by default; do not lower the minimum with --tls-min-v1.0 or --tls-min-v1.1.

For production hosting, use the supported official n8n image, a stable HTTPS hostname, persistent data, and backups of the database and credential encryption key. Keep every queue worker on the same n8n version with this package installed. Follow n8n's Docker deployment guidance for database and runtime configuration. The Compose service in this repository is an isolated local test instance.

Credentials

OAuth for document workflows

Use a current n8n release; the local setup in this repository pins n8n 2.42.4. Select Authentication → OAuth2 in the Assinafy action node and create an Assinafy OAuth2 API credential.

1. Copy the OAuth Redirect URL displayed by n8n. It must be a public HTTPS URL, normally https://n8n.example.com/rest/oauth2-credential/callback.
2. In your Assinafy workspace, open Integrations → OAuth Apps → New application. Choose Server application / Confidential, enter the exact callback, and select the permissions your workflows need.
3. Copy the issued Client ID and one-time Client Secret into the n8n credential. Store the secret in n8n credentials, never in workflow parameters or exported JSON.
4. Set Scope to a space-separated subset of the permissions registered for the application. A document workflow uses documents:read documents:write account:read offline_access; add templates:read when using templates. To create, update, delete, register or inactivate Assinafy webhook endpoints through the action node, enable webhooks:write in the OAuth application and add it to the credential's Scope field. The credential default includes templates:read, so remove it if the application does not allow it.
5. Leave Account ID empty to discover the single workspace selected during consent, or enter that workspace's ID explicitly. Click Connect my account, sign in to Assinafy, select the workspace, and approve the requested access.
6. Test the connection with Workspace → List. OAuth returns only the consented workspace; a different workspace is forbidden. The credential's connection test also calls GET /accounts.

n8n performs Authorization Code with PKCE S256 and sends the confidential client secret in the token request body. A public application can leave Client Secret empty. Access tokens expire after one hour. offline_access requests rotating refresh tokens: every refresh returns a new refresh token valid for another 30 days, so a connection expires only after 30 days without a refresh. n8n refreshes on demand, when a request finds the access token expired; to keep a rarely used credential connected, schedule a lightweight call such as Workspace → List at least every few weeks. Reconnect when a connection expires or is revoked. Keep queue workers on the same supported n8n version and shared credential/coordination infrastructure; never copy rotating tokens into separate credentials or refresh the same connection manually. To disconnect, revoke the application under Connected apps in your Assinafy profile, then delete the n8n credential; deleting only the credential leaves its refresh token valid until it expires.

OAuth does not authorize owner administration such as password/API-key changes, workspace lifecycle, billing, or membership. Use the API-key credential for those operations and for Assinafy Trigger. The action node's Webhook operations can use OAuth when the application grants the required scopes: account:read to read endpoints or the subscription, webhooks:write to change them, and documents:read to list event types or dispatches. Endpoint signing secrets are available only with the API key. Signer-side operations still require the signer's access code.

Each deployment registers its callback. Self-hosted n8n and n8n Cloud use the URL shown by that instance. One application may serve multiple workflows and connections; separate deployments should use separate applications, or explicitly register each exact callback in an application they control. There is no shared client secret or desktop loopback callback in this package. Behind a reverse proxy, configure N8N_EDITOR_BASE_URL, WEBHOOK_URL, and N8N_PROXY_HOPS so n8n advertises the external HTTPS origin. A temporary tunnel URL changes when the tunnel is recreated, requiring a callback update and reconnection. OAuth currently uses Production; Sandbox remains available for API-key workflows.

API key for owner operations and webhooks

Create an Assinafy API credential for account-scoped and API-key operations:

The credential test calls GET /accounts/{accountId} to confirm the key and account are valid. Custom URLs are validated and normalized before either the Test request or any authenticated request can attach the API key. The Assinafy action credential is optional only for public, signer-access-code, and explicitly Bearer-authenticated operations. Without a selected credential those calls use the production base URL; if a selected credential cannot be loaded, the call fails instead of silently falling back to production. Select a Sandbox credential even for an unauthenticated call when you need the sandbox host. The Assinafy Trigger always requires a credential because endpoint lifecycle calls are account-scoped.

Document workflow

Sending and receiving are separate n8n workflows because a trigger starts a workflow and has no input connection:

Send:     PDF → Upload → Wait Until Ready → Create Signer(s) → Estimate Cost → Create Assignment
Receive:  Assinafy Trigger → deduplicate event → route by event → Download Certified PDF / handle failure

Workflow A: upload and request signatures

1. Start with a Manual Trigger, Webhook, form, storage node, or another source that provides a non-empty PDF as binary data, up to 25 MB and 2,000 pages. The default binary property is data. Confirm the intended recipients before sending.
2. Add Assinafy → Document → Upload, select the binary property, and name the node Upload document. Its output is the document object; the reusable ID expression is ={{ $('Upload document').first().json.id }}. Persist the ID so a retry can reconcile the existing document.
3. Add Assinafy → Document → Wait Until Ready. Set Document ID to the upload expression. Continue only after the status is metadata_ready, pending_signature, or certificated; failed, rejection, expiration, and timeout states raise an error.
4. Add Assinafy → Signer → Create for each recipient. Only Full Name is mandatory, but a virtual email or WhatsApp assignment needs the matching contact field. Reuse If Exists searches every result page before creating another contact with the same email. Name the nodes, for example, Create signer 1 and Create signer 2.
5. Add Assignment → Estimate Cost before sending. Use the uploaded document ID and the same verification and notification options intended for Create. Check has_sufficient_resources, total_credits, and blocking_reason before allowing the assignment. Stop if the resources or expected cost are unacceptable.
6. Add Assignment → Create:
   • Document ID: ={{ $('Upload document').first().json.id }}
   • Method: virtual for remote signing or collect for positioned fields
   • Signer 1 ID: ={{ $('Create signer 1').first().json.id }}
   • Signer 2 ID: ={{ $('Create signer 2').first().json.id }}
   • Set each signer's verification method, notification method, and step. Equal steps run in parallel; increasing steps enforce sequence.
   • Verification methods: Email (code by email; 0 credits), Whatsapp (code over WhatsApp; requires whatsapp_phone_number and a paid plan; 0.45 credits for the paired WhatsApp notification), and DigitalCertificate (the signer's own ICP-Brasil A1 or A3 certificate in the browser; requires the plan's Digital Certificate feature, a CPF in government_id, the signer alone in its step; 0.5 credits plus its notification). Email verification pairs with Email notification and Whatsapp with Whatsapp; DigitalCertificate accepts either. Send one notification method per signer.
   • Add expires_at, message, or copy_receivers only when needed. Attach tags with Document → Append Tags or Replace Tags.
7. Persist the returned assignment ID together with the document ID in your application or data store. Do not use automatic workflow retries around Create Assignment unless your workflow first checks whether the assignment already exists; only explicit HTTP 429 failures are retried by the node; other failures are returned to the workflow.

For a dynamic recipient array, use n8n's Split Out/Loop Over Items to create signers, Aggregate their returned IDs, and build the Assignment signer collection from that aggregate. Keep the document ID from Upload document through a named-node expression instead of relying on the current item after the signer loop.

The assignment request built by the node has this shape:

{
  "method": "virtual",
  "signers": [{
    "id": "<signer-id>",
    "verification_method": "Email",
    "notification_methods": ["Email"],
    "step": 1
  }],
  "message": "Demonstration document for signing"
}

The recipient opens the signing invitation, receives the access code through the selected channel, confirms their information, and signs. Digital-certificate signing uses the signer's own certificate and browser flow. metadata_ready only means the PDF is ready for an assignment; it does not mean anyone has signed it.

For a template-based document, use Template → List/Get to obtain the role IDs, Document → Estimate Cost From Template with the intended signer configuration, and Document → Create From Template with one signer per role and the editor field values. Save the returned document and assignment IDs and use the same completion workflow below.

Workflow B: receive completion and download the artifact

1. Create a separate workflow beginning with Assinafy Trigger. Select document_ready, signer_rejected_document, and document_processing_failed; add signer_signed_document if intermediate signer progress is useful.
2. Store $json.headers['webhook-id'] as an idempotency key before side effects. Assinafy can redeliver an event, and the header also tells deliveries of the same event to different endpoints apart.
3. Add a Switch node on ={{ $json.event }}.
4. For document_ready, use ={{ $json.body.object.id }} as Document ID in Document → Get. Continue to Document → Download Artifact with certificated only when the returned status is certificated and artifacts.certificated exists. Otherwise, use an IF node and a short Wait node to loop back to Get with a bounded retry count or workflow timeout; stop immediately on a failed, rejected, or expired status. The PDF is returned in the configured binary property (data by default) with JSON metadata containing documentId, filename, MIME type, and size.
5. For rejection or processing failure, route $json.body.object.id, $json.body.message, and $json.body.payload to your notification or incident workflow.

Each active Trigger registers its own webhook endpoint, and a workspace holds 1 endpoint or up to 3 on paid plans. Fan out inside one workflow when more downstream processes need the same events than the plan allows. If you use OAuth without an API-key webhook connection, start the completion workflow from your own scheduler or application and poll Document → Get with bounded Wait/Get loops.

Store the certified PDF binary in your chosen storage system. The certificate-page artifact contains the certificate, bundle is a ZIP, and pades is available when digital-certificate signing was used. Get Signing Progress provides counts when available, but downloading must still wait for the final status and artifact.

After an uncertain Upload or Create Assignment result, reconcile the saved document and assignment before repeating the operation. Repeating a completion workflow should only read status and download existing artifacts.

Data and error conventions

• Assinafy's { status, message, data } response envelope is removed before output.
• List operations emit one n8n item per resource. Array-valued mutation responses emit one item shaped as { "data": [...] }.
• Binary downloads emit one item with JSON metadata and the file in the selected binary property.
• Get Signing Progress sets available: false and returns null counts when the document response does not include assignment details; it never reports a synthetic 0/0 as known progress.
• OAuth code exchange, refresh, and revocation are never automatically retried. HTTP requests have a 30-second timeout.
• HTTP 429 responses are retried with a bounded budget for every method, honoring Retry-After. A rate limit is refused before the request is handled, so replaying it cannot duplicate a document, signer, assignment, notification, or webhook action. Every other failure is surfaced after a single attempt, because an ambiguous response may mean the mutation was applied.

Assinafy Trigger

On activation the trigger creates a webhook endpoint named n8n Assinafy Trigger for the workflow's delivery URL, or updates the endpoint already registered for that URL; on deactivation it deletes that endpoint. Other endpoints in the workspace are not touched. A workspace holds 1 endpoint, or up to 3 on paid plans; activation in a full workspace fails with 403. The delivery URL must use HTTPS; HTTP is accepted only for localhost, 127.0.0.1, or ::1 development URLs. The node adds an assinafy-token query parameter derived with HMAC-SHA256 from the credential's Webhook Secret, or from its API key when no secret is configured. Every delivery must present that token and is rejected on a missing or mismatched value. Reactivate the workflow after rotating either credential value so Assinafy receives the new URL.

Each accepted delivery emits { event, headers, body } as one n8n item; authentication, cookie, API-key, token, secret, and signature headers are redacted. headers['webhook-id'] identifies the delivery for deduplication.

Signature verification. Enable Verify Signature to create the endpoint with signing on. Every delivery must then carry a valid Standard Webhooks signature (webhook-id, webhook-timestamp, webhook-signature) computed over the raw body with the endpoint secret, and a timestamp within five minutes. The node reads the secret from the API on the first signed delivery, keeps it in the n8n process, and reads it again when a signature does not match, so Webhook → Rotate Endpoint Signing Secret takes effect without reactivation. Deliveries without the headers or the raw body are rejected.

Where the API offers no webhook endpoints, the trigger falls back to the workspace's single subscription: activation replaces it, deactivation inactivates it only while it still matches this trigger, and Verify Signature is unavailable.

The full event list (source of truth: nodes/Assinafy/resources/webhookEvents.ts, shown in the node's Events dropdown):
assignment_created, document_metadata_ready, document_prepared, document_processing_failed, document_ready, document_uploaded, signature_requested, signer_created, signer_data_confirmed, signer_email_verified, signer_rejected_document, signer_signed_document, signer_viewed_document, signer_whatsapp_verified, template_created, template_processed, template_processing_failed, user_rejected_document. When no events are selected, the trigger subscribes to a sensible default set (document_ready, document_prepared, signer_signed_document, signer_rejected_document, document_processing_failed).

Supported operations

Full reference with request/response payloads: see
docs/OPERATIONS.md for each operation's node parameters,
example request body/query, and example response ({status,message,data} envelope,
unwrapped by the node). The tables below are a quick endpoint index.

Signer access codes

Operations marked (Signer Side) authenticate with a per-signer signer-access-code instead of the workspace API key. No endpoint returns that code — it reaches the signer only in the notification the API sends when an assignment is created or resent, by email or WhatsApp. The signing_urls on a new assignment are not a substitute: each one addresses the web signing page for the document (https://app.assinafy.com.br/sign/{documentId}?email=…) and carries no code, so passing its path segment as signer-access-code returns an HTTP 401 authentication error.

Drive these operations only when a code enters the workflow through a step you control — an inbox-reading node, a WhatsApp integration, or a human pasting it in. To simply get a signer to their document, hand them the signing URL or use Document → Send Public Token. Owner administration uses the API-key credential; delegated document operations may use OAuth. See Where a signer access code comes from.

Resource: Document

Uploads accept a binary property from the previous node (must be a non-empty PDF up to 25 MB and no more than 2,000 pages). Downloaded artifacts are attached back to the output item as binary data. The pades PDF contains the signers' ICP-Brasil signatures plus the platform certification box and exists only for documents with digital-certificate signers; bundle is a ZIP containing the three standard PDF artifacts and pades when available. The List operation supports filtering by status, method (virtual / collect), tag IDs, and a search term. Create From Template supports signer roles, sequential step ordering, editor field values, and document tag names.

Resource: Signer

Signer creation follows the published request body: only Full Name is required; email and WhatsApp are optional and may be added later before a remote signature request. Signer Update exposes government_id for a CPF or CNPJ and normalizes it to digits. Changing an unverified email/WhatsApp channel with requests in flight rotates its links and OTPs; a verified in-flight channel cannot be changed until its documents are certificated. Signer Create does not send the unsupported cpf or metadata keys.

Resource: Assignment

The method can be virtual (remote signature via email or WhatsApp) or collect (field-placed signatures on the document). Each signer entry accepts optional verification_method (Email, Whatsapp, or DigitalCertificate), exactly one compatible notification_methods value when supplied, and sequential-signing step. Match the notification channel to the available signer contact data; when omitted, the API infers the notification channel from the verification method, defaulting both to Email when neither is supplied. DigitalCertificate requires the account feature, a signer CPF/CNPJ in government_id, and a signing step containing no other signer; it costs 2 credits per signer in addition to notification cost and produces the optional pades artifact. For collect, provide entries as JSON. copy_receivers are signer IDs, not email addresses.

Resource: Template

Templates are read-only resources created through the Assinafy web app. Use List and Get to retrieve roles and field placements needed for Create From Template documents.

Resource: Tag

Tags are workspace-scoped labels. They can be managed directly through the Tag resource and attached to documents through the Document tag operations. Tag color values are validated as 6-character hex strings before being sent. Multiple-value tag arrays preserve each entry as one tag, including embedded commas (for example, Example, Inc.); only a scalar comma-delimited value is split.

Resource: Field Definition

Resource: Signer Document (Signer Side)

These signer-link endpoints do not use the workspace API key. Get Current, List, Search, Sign Multiple, and Decline Multiple require the per-signer signer-access-code query parameter. Download is public; its access-code field is optional and is sent only when supplied.

Signer-side Download supports the same original, certificated, certificate-page, pades, and bundle artifacts as the authenticated document download. List supports pagination plus status, method, search, and sort filters.

Resource: OAuth

Use the native credential for ordinary workflows. Raw token operations return sensitive execution data and never retry code exchange, refresh, or revocation automatically. See the complete OAuth payloads and lifecycle.

Resource: Authentication

User-account flows. Login operations return an access token used as Authorization: Bearer …; for a user with two-factor authentication, Login returns an mfa_token for Complete Two-Factor Login instead. Operations that expose Access Token use it when provided and otherwise use the configured API key; public password-reset operations need neither.

Resource: Workspace

GET /users/self returns the authenticated user data from Assinafy after the standard response envelope is removed.

Resource: Webhook

A workspace holds 1 endpoint, or up to 3 on paid plans. The subscription operations act on the oldest endpoint. Signing secrets require the API-key credential.

See the webhook delivery payload reference for the complete POST envelope, all 18 event-specific payload variants, success/retry/circuit-breaker behavior, and the trigger's n8n output shape.

Development

npm ci --strict-peer-deps # reproducible install with peer compatibility checks
npm run verify:dependencies # check the complete installed dependency tree
npm run dev       # runs n8n-node dev — starts n8n locally with this package loaded and hot reload
npm run lint      # n8n-node lint
npm run build     # compiles TypeScript into dist/
npm test          # unit and request-shape tests
npm run test:ci   # tests with enforced coverage thresholds
npm run audit:dev # development-tooling vulnerability gate
npm run audit:prod # production-dependency vulnerability check
npm run verify:package # check package contents, load modules, and scan source and compiled tarball

For an isolated instance on http://localhost:5679, run npm run build followed by docker compose up -d, complete owner setup, and follow Local n8n and HTTPS OAuth. Rebuild and restart the service after code changes.

The codebase contains two credentials, one action node with eleven resources, and one trigger. The shared transport handles authenticated and public/signer-access-code requests, response-envelope unwrapping, pagination, and bounded rate-limit retries. List-search methods back the resource-locator pickers for documents, signers, tags, and templates.

The sandbox suite requires explicit credentials, rejects production hosts, and cleans up disposable records. Mutations, account-credit consumption, and workspace/logo/subscription changes each have separate opt-in gates. See CONTRIBUTING.md for the commands and environment variables.

Report vulnerabilities according to SECURITY.md; never put API keys, signer codes, personal data, or document contents in a public issue.

License

MIT