ZapAssinaDocumentação da API
API e integrações

Envie documentos para assinatura direto do seu sistema.

Crie documentos com ou sem modelo, acompanhe cada assinatura, altere signatários e prazos e receba avisos no n8n, no Make ou no seu CRM. É uma API REST com JSON e autenticação por token.

Endereço base https://assina.zapconnecta.com/api/v1 · autenticação Authorization: Bearer zpa_… · testes com token zpa_test_… (sandbox: documentos sem validade jurídica, fora da cota do plano)

Como a API funciona

A API cria documentos — a partir de um modelo ou enviando o arquivo direto —, acompanha e altera o que já foi enviado, e avisa o seu sistema quando algo acontece.

O formato segue o padrão usual das plataformas de assinatura eletrônica: para migrar uma automação que já existe, em geral basta trocar o endereço base (https://assina.zapconnecta.com/api/v1) e o token, criado em Painel → Integrações.

Campos sem valor são omitidosA resposta não traz null: um documento sem prazo simplesmente não tem date_limit_to_sign. Datas de prazo usam AAAA-MM-DD; datas com hora vêm em ISO 8601 (UTC).

Autenticação

Crie o token em Painel → Integrações e mande em todas as chamadas. O token aparece uma única vez, na criação. A sessão do painel não vale na API, e o token de API não vale no painel.

bash
curl https://assina.zapconnecta.com/api/v1/docs/ \
  -H "Authorization: Bearer zpa_sua_chave"

Cada organização pode ter até 5 tokens ativos. Revogar um token no painel derruba na hora as integrações que o usam.

Erros e limites

Erros vêm com o código HTTP e uma mensagem em português no corpo:

json
{ "detail": "O prazo para assinar precisa ser hoje ou uma data futura" }
CódigoQuando acontece
400dados inválidos no corpo ou nos parâmetros
401token ausente, inválido ou revogado
402o plano não permite a ação: não inclui a API ou modelos, a cota de documentos do mês acabou ou a conta está bloqueada
404documento, modelo, signatário ou pasta que não existe, é de outra organização ou foi excluído de vez da lixeira
409ação incompatível com a situação atual (ex.: reenviar convite de um documento cancelado ou recusado)
410link de assinatura de um documento cancelado ou com o prazo encerrado

Arquivos: até 25 MB cada e 10 documentos por envelope. Os links de arquivo (original_file, signed_file, signed_file_with_report, signatures_report_file) valem 60 minutos: consulte o documento de novo para obter links novos, ou baixe e guarde os arquivos.

Modelos

Um modelo é um arquivo Word (.docx) com campos entre chaves duplas, como {{NOME COMPLETO}} ou {{CPF}}. Ele é cadastrado em Painel → Modelos, onde também se configuram:

  • Campos: pergunta, tipo, opções e se é obrigatório — resposta curta, texto longo, nome do signatário, e-mail, CPF, CNPJ, telefone, CEP, número, valor em R$, data, múltipla escolha, lista, caixas de seleção e data de envio automática.
  • Signatários: o primeiro é variável (muda a cada documento) e os demais são fixos (a empresa, uma testemunha). Nome, e-mail e telefone aceitam campos.
  • Documentos complementares: PDFs ou arquivos Word enviados no mesmo envelope — um link para assinar tudo e uma via assinada, com código de verificação próprio, para cada documento.
  • Link público: a pessoa preenche o formulário e assina em seguida.

Modelos precisam do serviço de conversão de DOCX (Gotenberg) configurado no servidor e de um plano que inclua o módulo de modelos: sem ele, /templates/ e create-doc respondem 402.

Posicionar a assinatura e envio em massa são do painelEm Modelo → Posicionar assinaturas dá para marcar onde a assinatura, a rubrica, o nome, a data e o CPF de cada signatário aparecem nas páginas — o desenho entra na via final, antes do selo. Não vale para signatário com certificado ICP-Brasil, cujo PDF não pode ser alterado depois da assinatura.
Envio em massa é só no painelEm Modelo → Envio em massa, uma planilha CSV gera um documento por linha, até 300 por lote, com conferência antes de enviar. Pela API, o mesmo se faz chamando create-doc em laço, com controle total sobre os erros de cada linha.

Listar modelos

GEThttps://assina.zapconnecta.com/api/v1/templates/?page=1
json
{
  "count": 2, "next": null, "previous": null,
  "results": [
    { "token": "7f1c…", "template_type": "docx", "name": "Contrato de honorários", "active": true }
  ]
}

Detalhar modelo

GEThttps://assina.zapconnecta.com/api/v1/templates/{token}/

Devolve inputs (variable, input_type, label, help_text, options, required, order), signers, public_url e extra_templates (documentos complementares: token, name, template_type).

Os campos de inputs já incluem os dos documentos complementares, então o mesmo data preenche todos.

Criar documento via modelo

POSThttps://assina.zapconnecta.com/api/v1/models/create-doc/
json
{
  "template_id": "7f1c…",
  "signer_name": "Maria da Silva",
  "signer_email": "maria@exemplo.com",
  "signer_phone_country": "55",
  "signer_phone_number": "84981210000",
  "external_id": "pedido-123",
  "date_limit_to_sign": "2026-10-01",
  "send_automatic_email": true,
  "data": [
    { "de": "{{NOME COMPLETO}}", "para": "Maria da Silva" },
    { "de": "{{CPF}}", "para": "52998224725" },
    { "de": "{{VALOR DOS HONORÁRIOS}}", "para": "1500" }
  ]
}
CampoComportamento
template_idobrigatório
signer_name, signer_email, signer_phone_*, signer_cpfdados do signatário variável; têm prioridade sobre o que está configurado no modelo
data[].de / data[].paracampo, com ou sem chaves, e valor. CPF, CNPJ, telefone, CEP, datas e valores são formatados automaticamente. Campos não enviados ficam em branco
send_automatic_email / send_automatic_whatsappfalse (padrão): ninguém recebe convite e o seu sistema entrega o sign_url. true: os convites são enviados
disable_signer_emailstrue: os signatários não recebem o aviso de conclusão
custom_messagemensagem do convite
signature_order_activeassinatura em ordem (sobrepõe o modelo)
date_limit_to_signprazo para assinar; sem o campo, vale o padrão da organização
reminder_every_n_dayslembra quem não assinou a cada tantos dias (1 a 30); 0 desliga; sem o campo, vale o padrão da organização
observersaté 20 e-mails que recebem a via final sem assinar
folder_pathpasta do documento, como /Clientes/2026; é criada se ainda não existir
replacementsoutro nome aceito para data (usado por integrações já existentes)
created_bye-mail de um usuário da organização, que fica como remetente
signer_has_incomplete_fieldstrue: os campos deixados em branco são preenchidos pelo próprio signatário, no link de assinatura (ver abaixo)
lang, brand_*, metadata e outrosaceitos e ignorados

A resposta é o documento. Se o modelo tiver documentos complementares, eles vêm em extra_docs, cada um com arquivo e código de verificação próprios.

O signatário preenche os campos que faltam

Com signer_has_incomplete_fields: true você manda só o que sabe — nome e e-mail, por exemplo — e o resto o signatário preenche ao abrir o sign_url:

  1. O documento é criado em rascunho, com signer_has_incomplete_fields: true na resposta, e o sign_url do signatário já vale.
  2. Esse link abre um formulário com os campos que ficaram em branco, com a mesma validação do modelo: obrigatórios, CPF, e-mail e opções da lista.
  3. Ao confirmar, o arquivo é gerado de novo com todos os valores, o documento passa a pending e o signatário segue para revisar e assinar.
Enquanto faltam camposO PDF e o código de assinatura não são liberados, e o documento não pode ser enviado pelo painel. A troca do arquivo fica registrada na trilha de auditoria — e nada tinha sido assinado até ali. Se o data já preencher tudo, o parâmetro é ignorado e o envio segue normal.

Com send_automatic_email: true, o convite sai na criação e leva direto ao formulário. Os demais signatários só são convidados depois que os campos forem preenchidos.

Criar documento sem modelo

POSThttps://assina.zapconnecta.com/api/v1/docs/envia um arquivo pronto, sem passar por modelo
json
{
  "name": "Contrato - Maria da Silva",
  "base64_pdf": "JVBERi0xLjQK…",
  "extra_docs": [ { "name": "Anexo I", "base64_pdf": "JVBERi0xLjQK…" } ],
  "folder_path": "/Clientes/2026",
  "date_limit_to_sign": "2026-10-01",
  "external_id": "crm-77",
  "send_automatic_email": true,
  "signers": [
    {
      "name": "Maria da Silva",
      "email": "maria@exemplo.com",
      "phone_country": "55",
      "phone_number": "84981210000",
      "cpf": "52998224725",
      "requirements": ["DRAW_SIGNATURE", "EMAIL_CODE", "SELFIE"]
    }
  ]
}
CampoComportamento
nameobrigatório; é o nome do envelope e do documento
base64_pdf, base64_docx, url_pdf, url_docxo arquivo, em base64 ou por URL. Até 25 MB cada. DOCX exige o serviço de conversão. A URL precisa ser pública e não segue redirecionamento
extra_docsdocumentos complementares no mesmo envelope, cada um com name e o arquivo. Um link para assinar tudo, uma via assinada e um código de verificação por documento
signers[]name obrigatório; email e/ou phone_country+phone_number; cpf; method (ELETRONICA_AVANCADA, padrão, ou ICP_BRASIL); send_automatic_whatsapp manda o convite pelo WhatsApp
signers[].requirementspontos de autenticação: DRAW_SIGNATURE, EMAIL_CODE, WHATSAPP_CODE, SELFIE, ID_DOCUMENT, CPF, RG, LOCATION. Sem o campo, vale assinatura na tela + código pelo canal do convite. Com o campo, ao menos 2 pontos diferentes; o código é opcional. require_selfie_photo e require_document_photo também funcionam
signers[].requested_attachmentsaté 5 arquivos pedidos ao signatário, como [{ "name": "Comprovante de residência", "description": "emitido nos últimos 90 dias", "required": true }]. Ele envia PDF, JPG ou PNG de até 5 MB cada; sem os obrigatórios, não assina. Não vale com ICP_BRASIL. Veja Anexos do signatário
signers[].qualificationpapel exibido (ex.: Contratante). Testemunha assina como testemunha; Aprovador aprova sem assinatura desenhada no PDF (a assinatura na tela não conta como ponto)
folder_pathpasta do documento, como /Clientes/2026; as pastas que faltarem são criadas
date_limit_to_signprazo para assinar; sem o campo, vale o padrão da organização
reminder_every_n_dayslembra quem não assinou a cada tantos dias (1 a 30); 0 desliga; sem o campo, vale o padrão da organização
observersaté 20 e-mails que recebem a via final sem assinar
signature_order_activeassinatura em ordem
custom_message (ou message)mensagem do convite
send_automatic_email / send_automatic_whatsappfalse (padrão): ninguém recebe convite e o seu sistema entrega o sign_url
disable_signer_emailstrue: os signatários não recebem o aviso de conclusão
create_as_drafttrue: o documento fica em rascunho, sem links de assinatura
Selfie e documento de identidade são capturados pela câmeraNão existe upload de arquivo para esses pontos de autenticação: a foto é tirada no aparelho, no momento da assinatura. É o que sustenta a evidência contra fraude.
bash
curl -X POST https://assina.zapconnecta.com/api/v1/docs/ \
  -H "Authorization: Bearer zpa_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"name":"Contrato","base64_pdf":"JVBERi0xLjQK…","signers":[{"name":"Maria","email":"maria@exemplo.com"}]}'

Posição da assinatura pela âncora no texto: escreva <<signer1>> (ou <<assinatura1>>) no documento onde vai a assinatura do primeiro signatário, <<signer2>> para o segundo e assim por diante; <<rubrica1>> põe a rubrica. Cada âncora vira uma marcação de assinatura ao criar o documento. O texto da âncora continua no PDF: use letra branca para escondê-lo.

Detalhar documento

GEThttps://assina.zapconnecta.com/api/v1/docs/{token}/
json
{
  "token": "3b7e…",
  "name": "Contrato - Maria da Silva",
  "status": "pending",
  "external_id": "pedido-123",
  "created_through": "api",
  "date_limit_to_sign": "2026-10-01",
  "folder_path": "/Clientes/2026",
  "original_file": "https://assina.zapconnecta.com/api/public/files/…?exp=…&sig=…",
  "verification_code": "Y7B4-JNEU-MV8L",
  "verification_url": "https://assina.zapconnecta.com/verificar/Y7B4-JNEU-MV8L",
  "sealed": false,
  "signers": [
    {
      "token": "…",
      "sign_url": "https://assina.zapconnecta.com/assinar/…",
      "status": "new",
      "name": "Maria da Silva",
      "requirements": ["DRAW_SIGNATURE", "EMAIL_CODE"]
    }
  ],
  "answers": [ { "variable": "CPF", "value": "529.982.247-25" } ],
  "extra_docs": []
}
CampoQuando aparece
signed_filevia assinada, depois da conclusão
signed_file_with_reportsó quando alguém assinou com certificado ICP-Brasil: a via assinada fica intacta em signed_file (para não quebrar a assinatura) e esta segunda via traz o relatório de assinaturas anexado ao fim
signatures_report_filerelatório de assinaturas e evidências, depois da conclusão
refusaldocumento recusado: signer_token, signer_name, reason (o motivo escrito por quem recusou) e refused_at
in_trashtrue quando o documento foi movido para a lixeira no painel

Status do documento

StatusSignificado
pendingem assinatura
signedconcluído, com signed_file preenchido
refusedum signatário recusou, informando o motivo. O documento para para todos: ninguém mais assina, e o motivo vem em refusal
canceledcancelado pelo remetente
expiredo prazo de date_limit_to_sign passou e os links pararam de funcionar. Um prazo novo reabre o documento, que volta a pending

Status do signatário

StatusSignificado
newainda não abriu o link
link-openedabriu o link
signedassinou
refusedrecusou

Listar e buscar documentos

GEThttps://assina.zapconnecta.com/api/v1/docs/?page=1

Lista os documentos da organização, dos mais novos para os mais antigos. Os filtros são os mesmos da busca do painel e podem ser combinados:

ParâmetroPara que serve
qnome, código de verificação, signatário, e-mail ou CPF
statuspending, signed, draft, expired ou canceled
from / toperíodo, em AAAA-MM-DD
date_fieldqual data o período filtra: created (padrão) ou completed
created_bye-mail de quem enviou
template_iddocumentos de um modelo; avulso traz os enviados sem modelo
folder_path/Clientes/2026 filtra a pasta; / traz só os que estão fora de pastas
page_sizeitens por página (padrão 20, máximo 100)

Documentos recusados continuam no filtro status=pending, com status: "refused" em cada item. Documentos na lixeira do painel não aparecem na listagem; os excluídos definitivamente da lixeira respondem 404 também no detalhe.

bash
curl "https://assina.zapconnecta.com/api/v1/docs/?status=pending&folder_path=/Clientes/2026&from=2026-09-01&q=Maria" \
  -H "Authorization: Bearer zpa_sua_chave"

Anexos do signatário

Cada signatário traz, no documento e nos webhooks, os anexos pedidos e os arquivos já enviados. O webhook doc_signed já chega com eles.

json
"requested_attachments": [
  { "name": "Comprovante de residência", "description": "emitido nos últimos 90 dias", "required": true }
],
"attachments": [
  {
    "name": "Comprovante de residência",
    "file_name": "conta-de-luz.pdf",
    "content_type": "application/pdf",
    "size": 183204,
    "sha256": "052bc96e…",
    "url": "https://…/api/public/files/signers/…/attachments/1?exp=…&sig=…"
  }
]
  • url baixa o arquivo sem login e vale por 60 minutos, como os links dos PDFs. Consulte o documento de novo para obter um link novo.
  • O sha256 é o mesmo da trilha de auditoria e do relatório de assinaturas.
  • Os arquivos seguem o prazo de guarda das fotos de identidade: 10 anos após a conclusão, ou 1 ano após o cancelamento ou o fim do prazo. Depois disso, url vem null.
  • Nos modelos, cada signatário pode ter anexos pedidos; todo documento gerado pelo modelo sai com eles.

Cancelar, prazo, pasta e reenvio

Todas as ações devolvem o documento atualizado e ficam registradas na trilha de auditoria.

Cancelar

DELETEhttps://assina.zapconnecta.com/api/v1/docs/{token}/ou POST /docs/{token}/cancel/

Os links de assinatura param de funcionar na hora. Mover para a lixeira, no painel, um documento em assinatura também o cancela.

Alterar o prazo

POSThttps://assina.zapconnecta.com/api/v1/docs/{token}/deadline/
json
{ "date_limit_to_sign": "2026-11-05" }

Corpo vazio ({}) tira o prazo. Num documento expired, um prazo novo reabre para assinatura — as assinaturas já feitas continuam valendo. O prazo máximo é de 365 dias, e uma data no passado é recusada com 400.

Mover de pasta

POSThttps://assina.zapconnecta.com/api/v1/docs/{token}/folder/
json
{ "folder_path": "/Clientes/2026" }

As pastas que faltarem são criadas. Use "/" para tirar o documento de qualquer pasta.

Reenviar convite

POSThttps://assina.zapconnecta.com/api/v1/docs/{token}/resend/

Sem corpo, reenvia a todos os signatários pendentes que já podem assinar; com { "signer_token": "…" }, só a um. Um documento sem ninguém pendente, ou recusado, responde 409.

Incluir ou remover signatário

POSThttps://assina.zapconnecta.com/api/v1/docs/{token}/add-signer/

Inclui um signatário num documento já enviado, com o mesmo formato de um item de signers em “Criar documento”. Ele entra no fim da ordem, recebe o convite na hora (ou quando chegar a vez dele) e dispara o webhook created_signer.

DELETEhttps://assina.zapconnecta.com/api/v1/signers/{signer_token}/

Remove quem ainda não assinou: o link dele deixa de funcionar e o registro fica na trilha. Se todos os que restam já assinaram, o documento é concluído. Quem já assinou, ou o último signatário, responde 409. Também aceita POST /signers/{signer_token}/remove/.

Alterar signatário antes da assinatura

POSThttps://assina.zapconnecta.com/api/v1/signers/{signer_token}/

Corrige dados, forma de assinatura e pontos de autenticação de quem ainda não assinou. O signer_token é o token de dentro de signers no documento.

json
{ "name": "Maria Aparecida da Silva", "email": "maria.nova@exemplo.com", "resend_invite": true }
  • Campos omitidos ficam como estão; "cpf": "" remove o CPF.
  • Aceita também phone_country/phone_number, method, requirements, require_selfie_photo, require_document_photo, send_automatic_whatsapp e requested_attachments (lista vazia tira os pedidos; sem o campo, ficam como estão).
Trocar e-mail ou celular gera um link novoO convite anterior pode ter ido para o contato errado, então o link antigo é invalidado e os códigos já confirmados no contato antigo deixam de valer. A resposta traz new_sign_url: true — pegue o sign_url novo em signer.
json
{ "changed": true, "new_sign_url": true, "invited": true, "signer": { … }, "document": { … } }

Pastas

GEThttps://assina.zapconnecta.com/api/v1/folders/
json
[ { "token": "…", "name": "2026", "path": "/Clientes/2026", "documents": 12, "subfolders": 0 } ]
POSThttps://assina.zapconnecta.com/api/v1/folders/
json
{ "path": "/Clientes/2026" }

Os níveis que faltarem são criados. As pastas aceitam até 5 níveis e 300 pastas por organização. Para tirar um documento de qualquer pasta, mova-o para "/".

Webhooks

Configure em Painel → Integrações ou pela API. Um webhook vale para todos os documentos da organização e, opcionalmente, pode ser filtrado por modelo.

EventoQuando
doc_createddocumento enviado para assinatura
doc_signeda cada assinatura. Na última, o aviso sai depois do selo, com status: "signed", signed_file e, se houve certificado ICP-Brasil, signed_file_with_report
doc_refusedum signatário recusou; o motivo vem em refusal
doc_deletedo remetente cancelou, ou moveu para a lixeira um documento em assinatura
doc_expiredo prazo para assinar terminou sem todas as assinaturas
doc_viewedum signatário abriu o documento pela primeira vez
created_signersignatário incluído num documento já enviado
signature_notification_sentconvite, reenvio ou lembrete enviado; notification (invite ou reminder) e channel (email ou whatsapp)
signer_authentication_failedo signatário errou o código até esgotar as tentativas, ou pediu ajuda por não conseguir se identificar; reason (too_many_code_attempts ou signer_requested_help) e problem
doc_expiration_alertfaltam 7, 3 ou 1 dia para o prazo; days_left e date_limit_to_sign

O corpo é o documento (como em “Detalhar documento”) acrescido de event_type. Nos eventos de um signatário, ele vem em signer e também em signer_who_signed, o nome usado no ZapSign.

Assinatura e reenvios

Cabeçalhos enviados em cada entrega:

CabeçalhoConteúdo
X-ZapAssina-Eventtipo do evento
X-ZapAssina-Deliveryid da entrega
X-ZapAssina-Signaturesha256=<hex>: HMAC-SHA256 do corpo com o segredo do webhook
(extras)os cabeçalhos que você configurou, como Authorization

Valide a assinatura antes de processar:

javascript
const crypto = require("crypto");
const esperado = "sha256=" + crypto.createHmac("sha256", SEGREDO).update(corpoBruto).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(req.headers["x-zapassina-signature"]));

Responda com HTTP 2xx. Se falhar, há novas tentativas em 1 min, 5 min, 30 min, 2 h e 12 h, e o envio pode ser refeito pelo painel. Por segurança, URLs que resolvem para a rede interna do servidor (localhost, 10.x, 172.16–31.x, 192.168.x) são recusadas.

Gerenciar webhooks pela API

POSThttps://assina.zapconnecta.com/api/v1/user/company/webhook/
json
{
  "url": "https://seu-n8n.com/webhook/zapassina",
  "type": "",
  "headers": [ { "name": "Authorization", "value": "Bearer segredo-do-n8n" } ]
}

type vazio assina todos os eventos. A resposta traz id e secret — guarde o secret, é com ele que a assinatura é validada.

AçãoEndpoint
ListarGET /user/company/webhook/
Trocar cabeçalhosPOST /user/company/webhook/header/ { "id": 1, "headers": [...] }
ExcluirDELETE /user/company/webhook/delete/ { "id": "1" }