Nó Zapsign

O nó Zapsign do workflow é um cliente REST flexível para a API v1 da Zapsign — contratos eletrônicos e assinatura digital para o mercado brasileiro. Use-o para criar documentos, adicionar signatários e acompanhar status de contratos diretamente de Automações.

ID do nó no editor: zapsign_request
URL padrão: GET https://api.zapsign.com.br/api/v1/docs/
Executor: http_request (mesmo motor do nó HTTP genérico)

O que faz

• Envia requisições HTTP autenticadas para a API v1 da Zapsign
• Suporta GET, POST, PUT, PATCH e DELETE
• Retorna status HTTP, data da resposta e headers
• Auth padrão: Authorization: Bearer {{zapsign_api_token}}
• Inclui presets de operação no diálogo de configuração para ações comuns de documento e signatário

Use este nó quando sua empresa usa Zapsign e você quer automatizar criação de contratos e convites de assinatura após vendas, atualizações de CRM ou triggers de webhook.

Pré-requisitos

1. Conta Zapsign
2. Token de API em Zapsign → Configurações → API (ou configurações de desenvolvedor)
3. Chave de integração zapsign_api_token em Configurações → Chaves de API
4. Contrato PDF hospedado em URL pública ou assinada (url_pdf), ou gerado em passo anterior do workflow

A Zapsign usa uma única base de API de produção (https://api.zapsign.com.br). Confirme se sua conta usa token sandbox/teste para desenvolvimento.

Como configurar

Passo 1 — Definir credenciais

1. Copie seu token de API da Zapsign
2. Em Configurações → Chaves de API, adicione:
   • Nome: zapsign_api_token
   • Valor: seu token de API da Zapsign
3. Salve

O template padrão de cabeçalhos envia:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {{zapsign_api_token}}"
}

Nunca cole o token diretamente nos campos do nó no canvas — use sempre chaves de integração ou variáveis do workflow.

Passo 2 — Adicionar o nó

1. Abra Automações e edite seu workflow
2. Na paleta, abra a categoria Contratos
3. Arraste Zapsign para o canvas
4. Conecte após o trigger ou nós de preparação de dados

Passo 3 — Escolher um preset de operação (recomendado)

Dê duplo clique no nó. O diálogo de configuração lista presets de operação que pré-preenchem URL, método, cabeçalhos e corpo:

Selecione um preset, ajuste os campos e substitua placeholders por variáveis do workflow.

Passo 4 — Configurar campos da requisição

Todos os campos aceitam variáveis do workflow ({{contact.email}}, {{variables.doc_token}}, etc.).

Passo 5 — Fluxo típico de assinatura

A Zapsign frequentemente precisa de duas ou mais chamadas de API:

1. Criar documento — registrar PDF por URL
2. Adicionar signatário — incluir cliente e receber link de assinatura
3. Enviar WhatsApp — entregar URL de assinatura ao cliente
4. Consultar documento (opcional) — consultar status até assinado

Salve doc_token e URLs de assinatura de cada passo com nós Variável ou referências downstream.

Detalhes das operações

Criar documento (POST /docs/)

URL: https://api.zapsign.com.br/api/v1/docs/
Template de corpo:

{
  "name": "Contrato — {{contact.name}}",
  "url_pdf": "{{variables.contract_pdf_url}}",
  "lang": "pt-br",
  "external_id": "{{variables.order_id}}"
}

Dica: Envie o PDF para armazenamento em nuvem (Google Drive, S3, storage WhatsWave) em passo anterior e passe URL de download. A URL precisa ser alcançável pelos servidores da Zapsign.

Resposta: Salve token (token do documento) — ex.: {{zapsign_1.data.token}}.

Adicionar signatário (POST /docs/{doc_token}/add-signer/)

URL: https://api.zapsign.com.br/api/v1/docs/{{doc_token}}/add-signer/
Template de corpo:

{
  "name": "{{contact.name}}",
  "email": "{{contact.email}}",
  "auth_mode": "assinaturaTela"
}

Resposta: Inclui detalhes do signatário e frequentemente uma URL de assinatura — inspecione data no histórico de execução. Referencie em nó Enviar mensagem:

Olá {{contact.name}}! Assine seu contrato aqui: {{zapsign_2.data.sign_url}}

(O nome exato do campo pode variar — verifique a saída da execução para o formato da sua conta.)

Consultar documento (GET /docs/{doc_token}/)

Consulte status do documento. Use nós Condição para ramificar conforme campos de status (ex.: signed, pending).

Excluir documento (DELETE /docs/{doc_token}/)

Remove documento quando negócio é cancelado ou rascunho deve ser descartado.

Listar documentos (GET /docs/?page=1)

Audite ou reconcilie documentos. Adicione parâmetros de query conforme docs da API Zapsign para filtrar.

Saídas do nó

Referencie campos aninhados nos nós seguintes:

Token do documento: {{zapsign_1.data.token}}
URL de assinatura: {{zapsign_2.data.sign_url}}

Substitua zapsign_1 / zapsign_2 pelos IDs dos nós no canvas. Confirme caminhos JSON exatos no Histórico de execução.

Confirmação de assinatura (webhooks)

O nó Zapsign chama a API; não escuta eventos de assinatura. Para reagir quando um documento for assinado:

1. Crie um segundo workflow com trigger Webhook
2. Nas configurações de webhook da Zapsign, registre a URL do webhook da WhatsWave
3. Inscreva-se em eventos de documento assinado ou signatário concluído (conforme docs de webhooks da Zapsign)
4. No workflow de confirmação, envie confirmação no WhatsApp, atualize CRM ou inicie onboarding

Veja Webhooks recebidos para padrões de configuração.

Dicas e boas práticas

• Garanta que url_pdf seja publicamente acessível — a Zapsign busca o PDF na sua URL; URLs privadas falham salvo links assinados/temporários
• Um nó por chamada de API — logs mais claros e depuração mais fácil do que reutilizar um nó para várias operações
• Armazene doc_token e external_id em campos customizados do card no CRM para reconciliação
• Use external_id para casar payloads de webhook com pedidos ou registros do CRM
• Combine com nó PDF (Ferramentas) para gerar contratos, enviar ao storage e passar URL à Zapsign
• Combine com Enviar mensagem (WhatsWave) para entregar links de assinatura no WhatsApp logo após adicionar signatário
• Use Loop + Consultar documento para checagens em lote de contratos pendentes
• Inspecione Histórico de execução ao depurar — a Zapsign retorna detalhes de validação em data

Exemplos de uso

Enviar contrato após webhook de compra Hotmart

1. Trigger Webhook com nome, e-mail e ID do produto do comprador
2. Variável — mapeia ID do produto para URL do PDF do contrato
3. Zapsign — criar documento com url_pdf e external_id = ID da transação
4. Variável — salva doc_token
5. Zapsign — adicionar signatário com e-mail do comprador
6. Enviar WhatsApp — link de assinatura da saída do nó anterior

Contrato B2B com vários signatários

1. Zapsign — criar documento
2. Zapsign — adicionar signatário (contato do cliente)
3. Zapsign — adicionar signatário (aprovador interno) — mesmo doc_token, e-mail diferente
4. Enviar mensagem para cada parte com suas respectivas URLs de assinatura

Lembrete de assinatura em atraso

1. Trigger Schedule diário
2. Zapsign GET — listar ou consultar documentos pendentes
3. Loop sobre documentos não assinados
4. Enviar WhatsApp com lembrete e link de assinatura de variáveis salvas ou nova chamada Consultar documento

Contrato guiado por CRM na mudança de estágio

1. Trigger CRM WhatsWave quando card entra em "Contrato enviado"
2. Cadeia Zapsign criar + adicionar signatário
3. Atualiza campo customizado no CRM com doc_token
4. Workflow separado com webhook na assinatura → move card para "Assinado"

FAQ

Por que o nó retorna 401 Unauthorized?
O token de API está ausente, inválido ou não se chama zapsign_api_token. Verifique a chave em Configurações → Chaves de API.

Por que criar documento falha com erros de PDF?
url_pdf está inacessível, retorna HTML em vez de PDF ou exige autenticação que a Zapsign não pode usar. Teste a URL no navegador ou com curl de uma rede externa.

Posso enviar PDF em Base64 em vez de URL?
O template do preset usa url_pdf. Para upload em Base64, consulte a docs da API Zapsign para endpoints alternativos e configure URL/método/corpo manualmente no nó.

Qual a diferença entre este nó e o nó HTTP?
Mesmo executor (http_request), mas Zapsign vem pré-configurado com auth Bearer, URL padrão da API, presets de operação e agrupamento na paleta Contratos.

O que é auth_mode: assinaturaTela?
Fluxo de assinatura na tela — signatário desenha ou confirma assinatura na interface web da Zapsign. Altere conforme requisitos de compliance e opções do seu plano.

Como obtenho o link de assinatura para WhatsApp?
Geralmente retornado na resposta de adicionar signatário. Sempre confirme o campo exato no Histórico de execução (sign_url, url ou objeto signatário aninhado).

Posso excluir documento após assinatura?
O preset DELETE remove o documento via API. Verifique regras de retenção/compliance da Zapsign antes de excluir contratos assinados.

A Zapsign tem sandbox?
Confirme com suporte Zapsign ou seu gerente de conta. Use tokens de teste e documentos não produtivos quando disponível.

Referência da API

Resumo dos endpoints dos presets

Artigos relacionados

• Visão geral de Contratos
• Nó Clicksign
• Nó HTTP
• Variáveis no workflow
• Webhooks recebidos
• Nó PDF — gerar PDFs de contrato antes do upload