n8n-nodes-zapsign

Node comunitário do n8n para o ZapSign — plataforma de assinatura eletrônica de documentos com validade jurídica no Brasil (MP 2.200-2/2001).

Crie documentos, gerencie signatários, acompanhe assinaturas e receba webhooks em tempo real, tudo dentro do n8n.

n8n is a fair-code licensed workflow automation platform.

Sumário

• Instalação
• Credenciais
• Nodes
  • ZapSign Node
  • ZapSign Trigger Node
• Referência de Operações
  • Document
  • Signer
• Exemplos de Uso
• Ambientes
• Compatibilidade
• Recursos
• Licença

Instalação

Community Nodes (Recomendado)

1. Abra sua instância do n8n
2. Vá em Settings > Community Nodes
3. Clique em Install
4. Digite n8n-nodes-zapsign
5. Aceite os riscos e clique em Install

Instalação Manual

cd ~/.n8n
npm install n8n-nodes-zapsign
# Reinicie o n8n

Docker

RUN cd /usr/local/lib/node_modules/n8n && npm install n8n-nodes-zapsign

Credenciais

Como obter seu API Token

1. Acesse o painel do ZapSign
2. Vá em Configurações > Integrações > API ZapSign
3. Copie seu Token de API

Configurar no n8n

1. Em qualquer node ZapSign, clique em Credentials > Create New
2. Cole seu API Token
3. Selecione o Environment (Production ou Sandbox)
4. Clique em Save — a credencial será testada automaticamente

Ambientes

| Ambiente | Uso | URL Base | |---|---|---| | Production | Documentos reais com validade jurídica | api.zapsign.com.br | | Sandbox | Testes sem custo | sandbox.api.zapsign.com.br |

Para criar uma conta sandbox, acesse: sandbox.app.zapsign.com.br

Nodes

ZapSign Node

Node principal para interagir com a API do ZapSign.

| Resource | Operations | |---|---| | Document | Create (via URL), Create (via Base64), Get, Get Many, Delete | | Signer | Add to Document, Get, Update |

ZapSign Trigger Node

Node de webhook que recebe eventos do ZapSign em tempo real. O webhook é registrado e removido automaticamente via API.

| Evento | Descrição | |---|---| | All Events | Qualquer evento do ZapSign | | Document Created | Documento criado | | Document Signed | Todas as assinaturas concluídas | | Document Refused | Documento recusado por um signatário | | Document Deleted | Documento excluído | | Document Expired | Prazo de assinatura expirou | | Document Expiration Alert | Alerta de expiração próxima | | Document Viewed | Documento visualizado | | Signature Notification Sent | Notificação de assinatura enviada | | Read Confirmation | Signatário leu o documento | | Email Bounce | Falha no envio de email | | Signer Authentication Failed | Falha na autenticação do signatário | | Signer Created | Signatário adicionado ao documento |

Referência de Operações

Document

Create (via URL)

Cria um documento a partir de uma URL pública de PDF ou DOCX.

| Parâmetro | Tipo | Obrigatório | Descrição | |---|---|---|---| | Document Name | string | Sim | Nome do documento (max 255 chars) | | PDF URL | string | Sim | URL pública do arquivo (max 10MB) | | Signers | collection | Não | Lista de signatários com nome, email, telefone, auth mode | | Language | select | Não | pt-br, en, es, fr | | External ID | string | Não | Seu ID interno | | Folder Path | string | Não | Pasta para organização (ex: /contratos/) | | Date Limit to Sign | string | Não | Prazo (YYYY-MM-DD) | | Signature Order | boolean | Não | Ativar ordem sequencial | | Allow Refuse | boolean | Não | Permitir recusa | | Observers | string | Não | Emails separados por vírgula | | Reminder Every N Days | number | Não | Lembrete automático | | Brand Logo/Name/Color | string | Não | Personalização visual |

Create (via Base64)

Mesmo que acima, mas recebe o conteúdo do PDF em Base64 (sem o prefixo data:application/pdf;base64,).

Get

Busca detalhes de um documento pelo token.

| Parâmetro | Tipo | Obrigatório | Descrição | |---|---|---|---| | Document Token | string | Sim | Token do documento |

Retorna: Dados completos do documento incluindo signatários, URLs dos arquivos, status, timestamps.

Os links original_file e signed_file expiram em 60 minutos.

Get Many

Lista documentos com paginação e filtros.

| Parâmetro | Tipo | Obrigatório | Descrição | |---|---|---|---| | Page | number | Sim | Número da página (25 docs/página) | | Status | select | Não | pending, signed, refused | | Folder Path | string | Não | Filtrar por pasta | | Created From / To | string | Não | Filtro por data (YYYY-MM-DD) | | Sort Order | select | Não | asc ou desc |

Delete

Remove um documento pelo token.

Signer

Add to Document

Adiciona um novo signatário a um documento existente.

| Parâmetro | Tipo | Obrigatório | Descrição | |---|---|---|---| | Document Token | string | Sim | Token do documento | | Signer Name | string | Sim | Nome do signatário | | Email | string | Não | Email do signatário | | Auth Mode | select | Não | Método de autenticação | | Phone Country / Number | string | Não | Telefone com DDD | | Send Email Automatically | boolean | Não | Enviar link por email | | Send WhatsApp Automatically | boolean | Não | Enviar link por WhatsApp (cobra créditos) | | Redirect Link | string | Não | URL após assinatura | | Qualification | string | Não | Papel (ex: Contratante) | | Require Selfie / Document Photo | boolean | Não | Verificação adicional |

Retorna: Dados do signatário incluindo sign_url (link de assinatura) e token.

Get

Busca detalhes de um signatário pelo token.

Retorna: Nome, email, status (new/signed), timestamps, geolocalização, fotos.

Update

Atualiza dados de um signatário.

| Parâmetro | Tipo | Descrição | |---|---|---| | Name | string | Novo nome | | Email | string | Novo email | | Phone | string | Novo telefone | | Auth Mode | select | Novo método de autenticação | | Lock Name/Email/Phone | boolean | Bloquear edição | | Redirect Link | string | URL de redirecionamento |

Exemplos de Uso

Exemplo 1 — Enviar contrato para assinatura via URL

[Webhook/Form] → [ZapSign: Document > Create via URL]

1. Receba os dados do signatário (nome, email) via webhook ou formulário
2. No node ZapSign, configure:
   • Resource: Document
   • Operation: Create (via URL)
   • PDF URL: URL do contrato
   • Signers: Nome e email do signatário
   • Send Email Automatically: true

O ZapSign enviará o link de assinatura automaticamente por email.

Exemplo 2 — Monitorar documentos assinados

[ZapSign Trigger: Document Signed] → [Google Sheets: Append Row] → [Slack: Send Message]

1. Adicione o node ZapSign Trigger com evento Document Signed
2. Copie a webhook URL gerada
3. O webhook é registrado automaticamente na API do ZapSign
4. Quando todos assinarem, o trigger dispara com os dados do documento

Exemplo 3 — Criar documento e adicionar signatários dinamicamente

[Spreadsheet] → [ZapSign: Document > Create via URL] → [Loop] → [ZapSign: Signer > Add to Document]

1. Leia a lista de signatários de uma planilha
2. Crie o documento sem signatários
3. Em um loop, adicione cada signatário usando o token do documento

Exemplo 4 — Consultar status de um documento

[Schedule Trigger] → [ZapSign: Document > Get] → [IF: status == "signed"] → [Email: Send]

1. Configure um agendamento para verificar periodicamente
2. Use o node ZapSign com Document > Get passando o token
3. Verifique o status e envie notificação quando assinado

Ambientes

O node suporta tanto Production quanto Sandbox:

• Production: https://api.zapsign.com.br — Documentos reais com validade jurídica
• Sandbox: https://sandbox.api.zapsign.com.br — Para testes, sem custo

Selecione o ambiente na configuração das credenciais.

Compatibilidade

| Requisito | Versão | |---|---| | n8n | >= 0.200.0 | | Node.js | >= 18.0.0 |

Testado com n8n versões 1.x.

Recursos

• Documentação ZapSign API
• Documentação em Inglês
• Painel ZapSign
• Sandbox ZapSign
• Documentação Community Nodes do n8n

Licença

MIT