Guias de Desenvolvimento

Política e Conformidade

Signing Sessions

Sessão de Confiança

Modelos de Solução

Guias dos SDKs

Guia de Integração n8n + SignDocs Brasil

Adicione assinatura eletrônica com validade jurídica (MP 2.200-2/2001, LGPD e certificados ICP-Brasil quando aplicável) a qualquer workflow do n8n usando o community node oficial n8n-nodes-signdocs-brasil — sem escrever código. O pacote traz um node de ação (SignDocs Brasil) e um node de trigger (SignDocs Brasil Trigger) que recebe eventos com verificação HMAC.

Público-alvo: usuários de n8n (Cloud ou self-hosted) que querem ligar planilhas, CRMs, formulários, WhatsApp, Telegram ou ERPs a um fluxo de assinatura eletrônica brasileiro.

⚡ Caminho de 10 minutos

  1. Instale o community node: Settings → Community Nodes → Install e cole n8n-nodes-signdocs-brasil.
  2. Crie uma credencial do tipo SignDocs Brasil API apontando para Staging (HML) com seu client_id e client_secret.
  3. Adicione o node SignDocs Brasil com Resource = Signing Session e Operation = Create, anexando um PDF de um node anterior.
  4. Use o campo signingUrl da saída em um node Gmail / WhatsApp / Telegram — é o link completo que o signatário abre, já montado.
  5. Opcional: crie um segundo workflow com o node SignDocs Brasil Trigger ouvindo TRANSACTION.COMPLETED para baixar o documento assinado e o pacote de evidências.

1. Pré-requisitos

🟠 HML vs Produção — Desenvolva sempre em HML (api-hml.signdocs.com.br, com hífen). As credenciais HML não consomem cota do plano e os dados expiram em 7 dias. Só troque a credencial para Production quando o workflow estiver validado.

2. Credenciais

Crie uma credencial do tipo SignDocs Brasil API. O node faz o fluxo OAuth2 client_credentials (servidor-a-servidor) contra POST /oauth2/token e renova o token automaticamente.

Campo Valor
Environment Production ou Staging (HML)
Authentication Method Client Secret (mais simples) ou Private Key JWT (ES256)
Client ID Fornecido pelo painel admin
Client Secret Fornecido pelo painel admin (modo Client Secret)
Private Key (PEM) + Key ID (kid) Apenas no modo Private Key JWT

⚠️ O botão "Test" só funciona no modo Client Secret. No modo Private Key JWT o teste declarativo não consegue assinar a assertion ES256 e falha mesmo com credenciais corretas — valide executando um workflow (ex.: Signing Session → Get Status).

⚠️ Não exporte workflows com credenciais. Ao compartilhar um workflow JSON, o n8n referencia credenciais por ID, mas confira antes de publicar em fóruns. O AUP §7-A da SignDocs trata client_secret embutido em templates como violação.

3. Operações disponíveis (node de ação)

O node SignDocs Brasil expõe seis resources:

Resource Operações Endpoint principal
Signing Session Create, Get Status, Cancel POST /v1/signing-sessions
Trust Session Create, Get Status, Cancel POST /v1/trust-sessions
Envelope Create, Get, Add Session, Combined Stamp POST /v1/envelopes
Evidence Get GET /v1/evidence/{id}
Document Upload, Download POST /v1/documents, download por transação
Webhook Register, List, Delete, Test POST /v1/webhooks

Signing Session vs Trust Session vs Envelope

✅ O campo signingUrl já vem pronto

A operação Create (Signing Session, Trust Session e Envelope → Add Session) retorna os campos brutos da API (url, clientSecret, expiresAt) e também signingUrl — o link combinado {url}?cs={clientSecret} que o signatário deve abrir. Use {{$json.signingUrl}} direto no corpo de um e-mail, mensagem de WhatsApp ou Telegram. É a única URL que o signatário precisa; você não precisa concatenar nada.

✅ E-mail de convite automático — se você preencher Owner Email (em Additional Fields) com um e-mail diferente do Signer Email, a própria SignDocs envia o convite de assinatura ao signatário e uma notificação de conclusão ao owner. Sem Owner Email, a entrega do signingUrl é responsabilidade do seu workflow (Gmail, WhatsApp, Telegram etc.).

Perfis de política (policyProfile)

O node usa os mesmos nomes de perfil da API REST (policy.profile):

Perfil O que o signatário faz
CLICK_ONLY Aceite clickwrap simples
CLICK_PLUS_OTP Clickwrap + código de verificação por e-mail ou SMS (additionalFields.otpChannel = email ou sms)
BIOMETRIC Biometria facial (liveness + match)
BIOMETRIC_PLUS_OTP Biometria facial + OTP
DIGITAL_CERTIFICATE Assinatura digital com certificado ICP-Brasil (o signatário escolhe A1 ou A3 na página de assinatura)
CUSTOM Composição de etapas definida pelo tenant

⚠️ Atualizou de uma versão anterior a 0.5.1? Versões antigas do node ofereciam valores de perfil (OTP, CLICK_AND_OTP, CLICK_AND_BIOMETRIC, OTP_AND_BIOMETRIC, FULL, DIGITAL_CERT) que a API rejeita com HTTP 400 "Invalid policy profile". Atualize o community node para a versão mais recente e re-selecione o perfil nos nodes SignDocs dos seus workflows salvos.

O resource Trust Session omite DIGITAL_CERTIFICATE (assinatura ICP-Brasil exige documento) e adiciona variantes com cruzamento SERPRO (BIOMETRIC_SERPRO, BIOMETRIC_SERPRO_AUTO_FALLBACK, BIOMETRIC_DOCUMENT_FALLBACK). Para escolher o perfil certo por cenário e nível de validade jurídica, veja Perfis de assinatura e níveis legais.

4. Trigger: reagindo a eventos

O node SignDocs Brasil Trigger inicia workflows quando eventos chegam da SignDocs, com verificação de assinatura HMAC-SHA256 (headers X-SignDocs-Signature e X-SignDocs-Timestamp, tolerância padrão de 300s configurável). Requisições com assinatura inválida ou timestamp fora da janela recebem 401 e não disparam o workflow.

Ciclo de vida automático:

  1. Ao ativar o workflow, o node registra um webhook na SignDocs (POST /v1/webhooks) com a URL pública do n8n e os eventos selecionados.
  2. O secret HMAC retornado fica guardado no static data do workflow e nunca é exposto.
  3. Ao desativar o workflow, o node remove o webhook (DELETE /v1/webhooks/{id}).

Evento padrão: TRANSACTION.COMPLETED. Também disponíveis: TRANSACTION.CREATED / CANCELLED / FAILED / EXPIRED, STEP.STARTED / COMPLETED / FAILED, SIGNING_SESSION.CREATED / COMPLETED / CANCELLED / EXPIRED, ENVELOPE.CREATED / ALL_SIGNED / EXPIRED, QUOTA.WARNING e API.DEPRECATION_NOTICE, entre outros. Detalhes de payload e assinatura em Webhooks.

🟠 URL pública obrigatória — a SignDocs rejeita webhooks apontando para localhost ou IPs privados (bloqueio na borda, retorna 403). O node valida isso antes de registrar e sugere configurar WEBHOOK_URL com um túnel público quando o n8n roda local.

5. Passo a passo: primeiro fluxo de assinatura

Fluxo de exemplo — enviar um PDF para assinatura a partir de uma planilha:

Google Sheets Trigger (nova linha)
  → HTTP Request                  // baixa o PDF (saída binária em "data")
  → SignDocs Brasil               // Signing Session → Create
  → Gmail                         // corpo usa {{$json.signingUrl}}

Configuração do node SignDocs Brasil:

  1. Resource: Signing Session — Operation: Create.
  2. Policy Profile: CLICK_PLUS_OTP (bom default para contratos; para aceites simples use CLICK_ONLY).
  3. Signer Name e Signer External ID (o ID do signatário no seu sistema — entra na trilha de auditoria).
  4. Document Source: Binary Property (From Previous Node) com Binary Property = data e Filename = contrato.pdf.
  5. Em Additional Fields: Signer Email, Signer CPF, OTP Channel, Expires In (Minutes) (default 60) e Metadata (JSON) com chaves de negócio, ex.: {"contrato_id": "CT-2026-0042"}.

A saída traz sessionId, transactionId, status, expiresAt e o signingUrl pronto para o node de entrega.

Para fechar o ciclo, crie um segundo workflow que arquiva o resultado:

SignDocs Brasil Trigger (TRANSACTION.COMPLETED)
  → SignDocs Brasil (Evidence → Get)       // pacote de evidências JSON + .p7m
  → SignDocs Brasil (Document → Download)  // documento assinado
  → Google Drive (Upload)                  // arquiva ambos

O pacote de evidências é assinado em PKCS#7/CMS (.p7m) com certificado ICP-Brasil A1 e reúne timestamps ISO do servidor, trilha de auditoria e hash SHA-256 do documento — verificável em GET /v1/verify/{evidenceId}.

6. Templates prontos para importar

Três workflows completos, prontos para importar via Workflows → Import from File (selecione o .json baixado). Em todos eles, substitua as credenciais marcadas com REPLACE pelas suas (basta abrir cada node e selecionar a credencial correspondente).

6.1 Contrato via Google Docs

Nova linha em uma planilha de contratos pendentes → preenche um template de contrato no Google Docs → exporta PDF via Google Drive → cria a sessão de assinatura na SignDocs (perfil CLICK_PLUS_OTP) → envia o signingUrl por Gmail.

Expõe um endpoint HTTP (Webhook do n8n) que recebe os dados do signatário, cria a sessão de assinatura e entrega o signingUrl pelo canal indicado no campo channel do request: WhatsApp, Telegram ou e-mail. O perfil de política pode vir no próprio request (policyProfile, default CLICK_PLUS_OTP).

⚠️ WhatsApp e Telegram são canais de entrega do link — o envio usa a API do WhatsApp Business / bot do Telegram do seu próprio tenant dentro do n8n. Não existe integração nativa SignDocs↔WhatsApp.

6.3 Pipeline Imobiliário

Lead imobiliário chega por webhook → registra no CRM (planilha) → gera a proposta a partir de um template do Google Docs → exporta PDF → cria a sessão de assinatura (perfil CLICK_PLUS_OTP) → envia o signingUrl ao comprador por WhatsApp. Espelha o cenário descrito em Solução: Imobiliário.

Para notificações de conclusão, combine qualquer um dos templates com um workflow separado usando o SignDocs Brasil Trigger em TRANSACTION.COMPLETED (seção 4).

7. Erros comuns

Sintoma Causa provável Correção
401 invalid_client ao executar Credencial errada para o ambiente (creds HML com Environment Production, ou vice-versa) ou secret revogado Confira o campo Environment da credencial; gere novo secret no painel admin se necessário
Botão Test falha com Private Key JWT Limitação do teste declarativo — não assina ES256 Valide executando um workflow; o erro não indica credencial inválida
403 ao ativar workflow com trigger URL de webhook é localhost/IP privado, bloqueada na borda Configure WEBHOOK_URL do n8n com um túnel público https e reative
403 ao criar Trust Session Tenant sem trustSessionsEnabled ou sem cota monthlyTrustSessions Solicite provisionamento ao seu contato de CS
422 validation_error Campo obrigatório ausente (ex.: Signer CPF para perfis biométricos, documento ausente com purpose DOCUMENT_SIGNATURE) A mensagem problem+json indica o campo; ajuste no node
429 rate_limited Limite do plano atingido (loop com muitos itens) Ative Retry on Fail no node com backoff; reduza o batch ou suba o plano
Trigger nunca dispara Assinatura HMAC inválida (proxy reescrevendo o body) ou timestamp fora da tolerância Não coloque middleware que altere o corpo bruto; ajuste Signature Tolerance se houver clock skew

Próximos passos