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.
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.
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:
{ "detail": "O prazo para assinar precisa ser hoje ou uma data futura" }| Código | Quando acontece |
|---|---|
| 400 | dados inválidos no corpo ou nos parâmetros |
| 401 | token ausente, inválido ou revogado |
| 402 | o 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 |
| 404 | documento, modelo, signatário ou pasta que não existe, é de outra organização ou foi excluído de vez da lixeira |
| 409 | ação incompatível com a situação atual (ex.: reenviar convite de um documento cancelado ou recusado) |
| 410 | link 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.
create-doc em laço, com controle total sobre os erros de cada linha.Listar modelos
{
"count": 2, "next": null, "previous": null,
"results": [
{ "token": "7f1c…", "template_type": "docx", "name": "Contrato de honorários", "active": true }
]
}Detalhar modelo
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
{
"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" }
]
}| Campo | Comportamento |
|---|---|
| template_id | obrigatório |
| signer_name, signer_email, signer_phone_*, signer_cpf | dados do signatário variável; têm prioridade sobre o que está configurado no modelo |
| data[].de / data[].para | campo, 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_whatsapp | false (padrão): ninguém recebe convite e o seu sistema entrega o sign_url. true: os convites são enviados |
| disable_signer_emails | true: os signatários não recebem o aviso de conclusão |
| custom_message | mensagem do convite |
| signature_order_active | assinatura em ordem (sobrepõe o modelo) |
| date_limit_to_sign | prazo para assinar; sem o campo, vale o padrão da organização |
| reminder_every_n_days | lembra quem não assinou a cada tantos dias (1 a 30); 0 desliga; sem o campo, vale o padrão da organização |
| observers | até 20 e-mails que recebem a via final sem assinar |
| folder_path | pasta do documento, como /Clientes/2026; é criada se ainda não existir |
| replacements | outro nome aceito para data (usado por integrações já existentes) |
| created_by | e-mail de um usuário da organização, que fica como remetente |
| signer_has_incomplete_fields | true: os campos deixados em branco são preenchidos pelo próprio signatário, no link de assinatura (ver abaixo) |
| lang, brand_*, metadata e outros | aceitos 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:
- O documento é criado em rascunho, com
signer_has_incomplete_fields: truena resposta, e osign_urldo signatário já vale. - 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.
- Ao confirmar, o arquivo é gerado de novo com todos os valores, o documento passa a
pendinge o signatário segue para revisar e assinar.
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
{
"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"]
}
]
}| Campo | Comportamento |
|---|---|
| name | obrigatório; é o nome do envelope e do documento |
| base64_pdf, base64_docx, url_pdf, url_docx | o 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_docs | documentos 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[].requirements | pontos 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_attachments | até 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[].qualification | papel exibido (ex.: Contratante). Testemunha assina como testemunha; Aprovador aprova sem assinatura desenhada no PDF (a assinatura na tela não conta como ponto) |
| folder_path | pasta do documento, como /Clientes/2026; as pastas que faltarem são criadas |
| date_limit_to_sign | prazo para assinar; sem o campo, vale o padrão da organização |
| reminder_every_n_days | lembra quem não assinou a cada tantos dias (1 a 30); 0 desliga; sem o campo, vale o padrão da organização |
| observers | até 20 e-mails que recebem a via final sem assinar |
| signature_order_active | assinatura em ordem |
| custom_message (ou message) | mensagem do convite |
| send_automatic_email / send_automatic_whatsapp | false (padrão): ninguém recebe convite e o seu sistema entrega o sign_url |
| disable_signer_emails | true: os signatários não recebem o aviso de conclusão |
| create_as_draft | true: o documento fica em rascunho, sem links de assinatura |
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
{
"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": []
}| Campo | Quando aparece |
|---|---|
| signed_file | via assinada, depois da conclusão |
| signed_file_with_report | só 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_file | relatório de assinaturas e evidências, depois da conclusão |
| refusal | documento recusado: signer_token, signer_name, reason (o motivo escrito por quem recusou) e refused_at |
| in_trash | true quando o documento foi movido para a lixeira no painel |
Status do documento
| Status | Significado |
|---|---|
| pending | em assinatura |
| signed | concluído, com signed_file preenchido |
| refused | um signatário recusou, informando o motivo. O documento para para todos: ninguém mais assina, e o motivo vem em refusal |
| canceled | cancelado pelo remetente |
| expired | o 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
| Status | Significado |
|---|---|
| new | ainda não abriu o link |
| link-opened | abriu o link |
| signed | assinou |
| refused | recusou |
Listar e buscar documentos
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âmetro | Para que serve |
|---|---|
| q | nome, código de verificação, signatário, e-mail ou CPF |
| status | pending, signed, draft, expired ou canceled |
| from / to | período, em AAAA-MM-DD |
| date_field | qual data o período filtra: created (padrão) ou completed |
| created_by | e-mail de quem enviou |
| template_id | documentos 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_size | itens 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.
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.
"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=…"
}
]urlbaixa 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,
urlvemnull. - 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
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
{ "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
{ "folder_path": "/Clientes/2026" }As pastas que faltarem são criadas. Use "/" para tirar o documento de qualquer pasta.
Reenviar convite
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
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.
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
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.
{ "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_whatsapperequested_attachments(lista vazia tira os pedidos; sem o campo, ficam como estão).
new_sign_url: true — pegue o sign_url novo em signer.{ "changed": true, "new_sign_url": true, "invited": true, "signer": { … }, "document": { … } }Pastas
[ { "token": "…", "name": "2026", "path": "/Clientes/2026", "documents": 12, "subfolders": 0 } ]{ "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.
| Evento | Quando |
|---|---|
| doc_created | documento enviado para assinatura |
| doc_signed | a 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_refused | um signatário recusou; o motivo vem em refusal |
| doc_deleted | o remetente cancelou, ou moveu para a lixeira um documento em assinatura |
| doc_expired | o prazo para assinar terminou sem todas as assinaturas |
| doc_viewed | um signatário abriu o documento pela primeira vez |
| created_signer | signatário incluído num documento já enviado |
| signature_notification_sent | convite, reenvio ou lembrete enviado; notification (invite ou reminder) e channel (email ou whatsapp) |
| signer_authentication_failed | o 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_alert | faltam 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çalho | Conteúdo |
|---|---|
| X-ZapAssina-Event | tipo do evento |
| X-ZapAssina-Delivery | id da entrega |
| X-ZapAssina-Signature | sha256=<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:
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
{
"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ção | Endpoint |
|---|---|
| Listar | GET /user/company/webhook/ |
| Trocar cabeçalhos | POST /user/company/webhook/header/ { "id": 1, "headers": [...] } |
| Excluir | DELETE /user/company/webhook/delete/ { "id": "1" } |
Link público do modelo
Ative em Modelo → Link público e API. Quem acessa https://assina.zapconnecta.com/modelo/{token} preenche o formulário, o documento é gerado e a pessoa segue para a assinatura, confirmando a identidade conforme os pontos de autenticação do signatário variável. Os signatários fixos recebem o convite normalmente.
O link aceita até 10 envios por hora por conexão e 300 por dia por modelo. “Gerar novo link” invalida o link anterior.
Dúvida que não está aqui? Veja a Central de Ajuda ou escreva para admin@zapconnecta.com.