A ZapSign API permite criar, enviar e acompanhar documentos para assinatura eletrônica diretamente em CRMs, ERPs, sites, aplicativos e sistemas internos. Por meio de requisições HTTP e dados em JSON, sua aplicação pode criar documentos, adicionar signatários, configurar autenticações, consultar status e receber eventos automaticamente por webhooks.
A integração pode utilizar um API Token estático ou autenticação dinâmica por JWT. Antes de operar com documentos reais, a ZapSign oferece um ambiente sandbox separado da produção para desenvolvimento e homologação.
Neste artigo, mostramos como funciona a ZapSign API, como obter as credenciais, criar o primeiro documento, acompanhar assinaturas, configurar webhooks e decidir quando usar API direta, integrações no-code ou o MCP da ZapSign.
Resumo
- O que é a ZapSign API e quais processos ela automatiza.
- Como funcionam API Token, JWT, sandbox e produção.
- Como criar documentos e configurar signatários via API.
- Como acompanhar eventos com webhooks sem depender de polling.
- Quando usar API direta ou integrações com Zapier, Make, Pluga e n8n.
- Como o MCP da ZapSign permite conectar agentes de IA à mesma infraestrutura.
O que é a ZapSign API e como funciona?
Uma API, ou Interface de Programação de Aplicações, define formas padronizadas para que diferentes sistemas troquem informações e solicitem operações entre si.
No caso da ZapSign, a API permite incorporar funções da plataforma de assinatura eletrônica diretamente ao software utilizado pela empresa.
Em vez de um funcionário entrar manualmente na plataforma sempre que um contrato precisa ser enviado, por exemplo, o ERP, CRM ou aplicativo pode fazer a solicitação de forma programática.
Entre as operações disponíveis na documentação estão criação de documentos por upload ou modelo, inclusão e atualização de signatários, posicionamento de assinaturas, consultas de status, cancelamento, assinatura em lote, modelos, webhooks e outros recursos.
| Recurso | O que permite fazer | Exemplo de aplicação |
|---|---|---|
| Criação por upload | Criar um documento a partir de PDF ou DOCX | Enviar contratos já gerados pelo ERP |
| Criação por modelo | Gerar documentos usando templates e variáveis | Propostas e contratos padronizados em escala |
| Signatários | Adicionar, atualizar e consultar participantes | Fluxos com múltiplas assinaturas |
| Consulta de documentos | Acompanhar status e arquivos | Exibir a situação da assinatura dentro do CRM |
| Webhooks | Receber eventos automaticamente | Atualizar negócio, pedido ou cadastro após assinatura |
| Widget | Incorporar o ambiente de assinatura | Permitir assinatura sem abandonar a experiência do site |
Eu gosto especialmente dessa lógica de transformar processos complexos em chamadas simples. É algo que também levamos para outros produtos da ZapSign: uma aplicação envia uma pergunta ou uma operação bem definida e recebe uma resposta que consegue incorporar ao próprio fluxo, sem obrigar o usuário final a entender toda a infraestrutura que existe por trás.
Como APIs facilitam a integração de diferentes sistemas?
APIs permitem conectar sistemas sem que todas as funcionalidades precisem ser reconstruídas dentro de cada software.
Uma integração entre CRM e assinatura eletrônica é um exemplo comum. Ao atingir determinado estágio comercial, o CRM pode gerar um contrato, enviar os dados à ZapSign e armazenar posteriormente o status da assinatura online.
O mesmo princípio pode ser aplicado a:
- ERPs que geram contratos ou pedidos;
- CRMs que enviam propostas comerciais;
- sistemas de RH que automatizam admissões;
- plataformas imobiliárias que geram contratos;
- sistemas financeiros e administrativos;
- sites e aplicativos que precisam coletar assinaturas dentro da própria jornada.
Uma integração bem estruturada reduz alternância entre sistemas, digitação repetitiva e atualização manual de status. O ganho real depende, entretanto, de como a empresa desenha seu fluxo e trata erros, eventos e reconciliação de dados.
💡 Dica! Precisa de assinatura eletrônica gratuita? Clique aqui e crie a sua agora!
O que é possível automatizar com a ZapSign API?
A ZapSign API pode assumir diferentes etapas do ciclo de um documento, permitindo que o sistema da empresa permaneça como a interface principal do usuário.
- criar documentos: enviar arquivos ou gerar documentos a partir de modelos;
- adicionar signatários: definir participantes e seus dados;
- configurar autenticações: determinar os métodos disponíveis no fluxo conforme os recursos contratados;
- definir ordem de assinatura: criar processos sequenciais quando necessário;
- posicionar campos: estabelecer onde assinaturas e demais elementos devem aparecer;
- consultar status: acompanhar documentos e signatários;
- obter arquivos: acessar os documentos resultantes do processo;
- reagir a eventos: receber webhooks de criação, assinatura, recusa, visualização, expiração e outras ocorrências.
A API está atualmente incluída nos planos Equipe e Enterprise da ZapSign. O plano Equipe também inclui conta de desenvolvedor, webhooks e integrações, enquanto o Enterprise oferece configurações corporativas adicionais.
⚠️ Confira também estes artigos relacionados 👇
➡️ O que é API de assinatura eletrônica e como ela beneficia a gestão de uma empresa
➡️ Quais são as vantagens de contratar uma plataforma de assinatura eletrônica?
➡️ Por que você precisa entrar na era dos documentos eletrônicos hoje mesmo
Como integrar a ZapSign API em 6 passos?
Para uma integração programática, o caminho recomendado é começar pelo sandbox, validar o fluxo completo e somente depois substituir credenciais e endpoint pelos correspondentes de produção.
1. Crie uma conta no sandbox
A ZapSign mantém um ambiente de testes separado para desenvolvimento. Ele reproduz as funcionalidades necessárias para homologar a integração, mas os documentos produzidos ali não possuem validade jurídica.
O endpoint-base documentado para o ambiente de testes é:
https://sandbox.api.zapsign.com.br/api/v1/
Na produção, utilize:
https://api.zapsign.com.br/api/v1/
Não é necessário enviar um parâmetro sandbox=true para usar o ambiente de testes quando você já utiliza os endpoints próprios do sandbox.
2. Obtenha seu token da ZapSign API
Na conta correspondente ao ambiente utilizado, acesse:
Configurações → Integrações → API ZAPSIGN
Copie o API Token e armazene-o com segurança. Ele funciona como uma credencial de acesso e não deve ser exposto em código público, repositórios, páginas do navegador ou logs desnecessários.
A autenticação das chamadas utiliza o cabeçalho Authorization com o prefixo Bearer:
Authorization: Bearer SEU_API_TOKEN
A ZapSign também oferece autenticação via JWT. Nesse modelo, é obtido um token de acesso temporário associado ao usuário e à organização. O access token expira após uma hora e pode ser renovado utilizando o fluxo de refresh token.
3. Crie o documento
Um dos endpoints centrais permite criar um documento para assinatura. A aplicação envia os dados necessários, e a ZapSign devolve as informações que serão usadas para acompanhar o processo.
Um exemplo simplificado de requisição é:
POST /api/v1/docs/
Authorization: Bearer SEU_API_TOKEN
Content-Type: application/json
{
"name": "Contrato de prestação de serviços",
"url_pdf": "https://seusite.com/contrato.pdf",
"external_id": "CONTRATO-123",
"signers": [
{
"name": "Maria Silva",
"email": "maria@empresa.com"
}
]
}
A documentação também oferece opções de criação por DOCX, Base64 e modelos com variáveis, além de endpoints assíncronos para determinados cenários.
O campo external_id é especialmente útil para relacionar o documento da ZapSign ao identificador correspondente no ERP, CRM ou banco de dados da empresa.
4. Configure os signatários e as autenticações
Os signatários podem ser enviados já na criação do documento ou gerenciados posteriormente pelos endpoints correspondentes.
Dependendo do fluxo e dos recursos contratados, é possível trabalhar com diferentes métodos de autenticação e configurações de envio, ordem, identificação e validação.
Evite simplesmente ativar todos os métodos de segurança disponíveis em todos os documentos. O melhor desenho considera risco, experiência de quem assina e requisitos jurídicos da operação.
Quando fundamos a ZapSign, nossa preocupação já era combinar validade jurídica com simplicidade. Esse princípio continua importante em uma integração via API: mais segurança deve significar evidências melhores, e não necessariamente mais atrito para cada usuário.
5. Armazene os identificadores retornados
Depois da criação, registre no seu sistema os identificadores necessários para reconciliar a operação com a ZapSign.
Isso permite consultar posteriormente o documento, identificar seus signatários e vincular eventos recebidos por webhook ao registro correto da sua aplicação.
Uma boa prática é manter também seu próprio identificador em external_id, evitando que a integração dependa exclusivamente de IDs externos para localizar processos de negócio.
6. Configure webhooks para acompanhar o processo
É possível consultar periodicamente o status de cada documento pela API, mas a própria documentação recomenda o uso de webhooks em vez de polling repetitivo.
Com um webhook, a ZapSign envia uma requisição HTTP POST em JSON para o endpoint da sua aplicação quando determinado evento ocorre.
doc_created: documento criado;doc_signed: evento de assinatura;doc_refused: documento recusado;doc_deleted: documento excluído;doc_viewed: documento visualizado;doc_expired: documento expirado;signer_authentication_failed: falha máxima nas tentativas de determinados métodos de validação.
Seu endpoint deve devolver HTTP 200 quando o evento for processado corretamente. Quando isso não acontece, a ZapSign pode realizar novas tentativas, o que significa que a aplicação deve estar preparada para lidar com eventos repetidos sem executar a mesma ação indevidamente.
API e webhook são a mesma coisa?
Não. Embora trabalhem juntos, API e webhook resolvem direções diferentes da comunicação.
| Recurso | Quem inicia | Exemplo |
|---|---|---|
| API | Seu sistema envia uma solicitação à ZapSign | Criar documento ou consultar signatário |
| Webhook | A ZapSign envia um evento ao seu sistema | Avisar que alguém assinou ou recusou |
Imagine um CRM. Ele usa a API para solicitar a criação de um contrato. Depois, não precisa perguntar à ZapSign a cada minuto se alguém já assinou: um webhook pode informar a mudança assim que o evento ocorrer.
Como configurar webhooks da ZapSign com segurança?
Os webhooks podem ser cadastrados pela interface da plataforma ou pela própria API. É possível selecionar os tipos de evento monitorados e configurar headers personalizados enviados junto às notificações.
Isso permite, por exemplo, criar um segredo conhecido pelo seu servidor e verificar o cabeçalho antes de processar o payload recebido.
Algumas práticas úteis para integrações robustas são:
- receber os eventos em um endpoint HTTPS;
- validar headers ou credenciais configuradas para o webhook;
- responder rapidamente com HTTP 200 após o processamento adequado;
- preparar a aplicação para receber eventos duplicados;
- usar identificadores para impedir a execução duplicada da mesma ação;
- monitorar os logs de webhooks disponíveis na plataforma para investigar falhas.
A ZapSign disponibiliza no painel os logs dos webhooks enviados nos últimos sete dias, o que ajuda no diagnóstico de integrações.
Qual é o limite de requisições da ZapSign API?
A documentação atual informa um limite geral de 500 requisições por minuto para endpoints públicos.
Esse limite é aplicado por IP ou token de autenticação válido. Quando a cota é ultrapassada dentro da janela, novas chamadas podem receber o código HTTP 429 Too Many Requests.
A própria documentação recomenda práticas como cache, redução de chamadas repetitivas e lógica de retry com espera progressiva.
Webhooks também ajudam nesse ponto porque evitam consultas constantes apenas para descobrir se o status de um documento mudou.
Sandbox e produção: qual é a diferença?
A ZapSign mantém ambientes separados para testes e documentos reais.
| Ambiente | Endpoint-base | Uso |
|---|---|---|
| Sandbox | https://sandbox.api.zapsign.com.br/api/v1/ |
Desenvolvimento e testes sem validade jurídica |
| Produção | https://api.zapsign.com.br/api/v1/ |
Operação real de documentos |
Os tokens também pertencem aos respectivos ambientes. Por isso, não basta trocar somente a URL: antes de publicar uma integração, confirme se ela utiliza as credenciais corretas de produção.
A documentação também informa uma opção de infraestrutura com servidores no Brasil para empresas que necessitam dessa configuração e possuem planos compatíveis.
ZapSign API Token ou JWT: qual escolher?
A ZapSign disponibiliza duas formas principais de autenticação.
API Token estático
É uma credencial fixa associada à conta e costuma ser a maneira mais simples de iniciar uma integração servidor a servidor.
Por ser uma credencial persistente, deve ser armazenada em um gerenciador de segredos ou variável protegida do servidor, nunca diretamente em código entregue ao navegador ou aplicativo cliente.
JWT
No fluxo JWT, a aplicação obtém um access token temporário vinculado ao usuário e à organização. Segundo a documentação atual, esse token expira após uma hora e pode ser atualizado usando o refresh token.
Esse modelo é útil quando a arquitetura pede credenciais de curta duração e uma gestão dinâmica de sessões de acesso.
Integrações no-code: Zapier, Make, Pluga e n8n
Nem toda integração precisa ser desenvolvida diretamente contra endpoints da API.
A ZapSign também pode participar de fluxos construídos com plataformas de automação como Zapier, Make, Pluga e n8n. Esses serviços funcionam como uma camada intermediária capaz de conectar aplicativos sem que a empresa desenvolva toda a lógica do zero.
Por exemplo, é possível criar um fluxo no qual:
- um contrato é criado ou assinado na ZapSign;
- um webhook ou conector informa a plataforma de automação;
- a automação cria ou atualiza uma linha no Google Sheets;
- o CRM recebe o novo status;
- outra ação é iniciada automaticamente.
O conteúdo original deste artigo trazia um tutorial de 19 etapas com capturas da interface antiga do Zapier. Como menus e telas dessas ferramentas mudam com frequência, a atualização prioriza o fluxo conceitual e a documentação atual, evitando orientar o usuário por botões que podem não existir mais no mesmo local.
Ferramentas no-code possuem seus próprios planos e limites, que não estão necessariamente incluídos na assinatura da ZapSign.
Quando usar API direta e quando usar integração no-code?
A escolha depende principalmente do grau de controle, escala e complexidade necessária.
| Cenário | Opção mais comum |
|---|---|
| Automação simples entre duas ferramentas | Zapier, Make, Pluga ou n8n |
| Produto próprio com jornada de assinatura | API REST |
| ERP ou CRM com regras complexas | API + webhooks |
| Grande volume e controle sobre erros e reconciliação | API + webhooks |
| Protótipo sem equipe de desenvolvimento | Integração no-code |
A solução no-code pode reduzir o esforço inicial, enquanto uma integração direta costuma oferecer maior controle sobre experiência, tratamento de erros, autenticação, observabilidade e regras específicas do negócio.
ZapSign API e agentes de IA: o que mudou em 2026?
Além da API REST, a ZapSign passou a oferecer um servidor oficial baseado no Model Context Protocol (MCP), voltado a clientes e agentes de inteligência artificial.
Isso permite conectar ferramentas compatíveis e transformar operações como criar documentos, adicionar signatários, consultar status e gerenciar webhooks em ferramentas estruturadas que um agente consegue utilizar.
A API REST continua sendo a opção adequada quando uma aplicação precisa integrar diretamente por HTTP. O MCP adiciona outra interface sobre esse universo, especialmente útil quando o “usuário” do serviço é um agente de IA.
Para mim, essa evolução é uma continuação natural do que estamos construindo. Durante muito tempo, produtos de software foram projetados apenas para pessoas clicando em interfaces. Agora também precisam conseguir ser operados por sistemas e agentes. A infraestrutura precisa continuar simples de usar, mesmo quando quem está do outro lado deixa de ser necessariamente uma pessoa.
A documentação da própria API também passou a oferecer recursos voltados a agentes e modelos de linguagem, incluindo um índice llms.txt para facilitar a descoberta das páginas técnicas.
Boas práticas para integrar a ZapSign API
- comece pelo sandbox: valide a integração completa antes de usar documentos reais;
- não exponha tokens: mantenha credenciais exclusivamente em ambientes seguros no backend;
- use webhooks: evite polling excessivo para acompanhar alterações de status;
- prepare-se para duplicidades: webhooks podem ser reenviados se o seu endpoint não responder corretamente;
- trate HTTP 429: implemente espera e novas tentativas quando atingir o rate limit;
- registre um identificador interno: use campos como
external_idpara reconciliar ZapSign e seu sistema; - monitore erros: registre status HTTP e mensagens relevantes sem gravar credenciais;
- consulte a documentação antes de publicar: parâmetros, endpoints e funcionalidades podem evoluir.
A arquitetura técnica importa, mas a integração só gera valor quando simplifica o processo real. Na ZapSign, tenho insistido bastante nessa visão de confiança digital: certificado, identidade, APIs e validações podem parecer componentes separados, mas devem funcionar juntos para que a empresa consiga automatizar sem perder controle sobre quem participa e quais evidências ficam registradas.
A ZapSign API garante validade jurídica?
A API é o meio técnico utilizado para criar e controlar o processo de assinatura. Não é o simples fato de um documento ter sido criado por uma API que determina sua validade jurídica.
Documentos gerados em produção por meio da API utilizam os mesmos fluxos e recursos da plataforma ZapSign. A análise jurídica depende da modalidade de assinatura, das evidências produzidas, das partes, do documento e das exigências legais aplicáveis.
A legislação brasileira reconhece diferentes formas de assinatura eletrônica, incluindo as categorias simples, avançada e qualificada previstas na Lei nº 14.063/2020. A Medida Provisória nº 2.200-2/2001 também disciplina a ICP-Brasil e admite outros meios de comprovação de autoria e integridade nas condições previstas pela norma.
Já os documentos gerados no sandbox são destinados a testes e, conforme a própria documentação da ZapSign, não possuem validade jurídica.
Onde consultar a documentação da ZapSign API?
A documentação oficial está disponível em docs.zapsign.com.br e reúne guias sobre autenticação, documentos, signatários, templates, webhooks, SDKs, rate limits, códigos de status e demais funcionalidades.
A ZapSign também disponibiliza requisições prontas para ferramentas como Postman, que ajudam a testar os endpoints antes de implementar o código na aplicação.
Se a ideia é apenas automatizar aplicativos sem criar uma integração customizada, avalie primeiro os conectores no-code disponíveis. Já para jornadas próprias, regras de negócio avançadas e integração profunda ao produto, a API oferece maior controle.
Para saber mais sobre como as nossas soluções podem integrar assinaturas eletrônicas aos processos da sua empresa, fale com um dos nossos especialistas.
Perguntas frequentes sobre a ZapSign API
É a interface REST que permite integrar criação, envio e acompanhamento de documentos para assinatura eletrônica a CRMs, ERPs, sites, aplicativos e outros sistemas.
Na conta ZapSign, acesse Configurações, Integrações e API ZAPSIGN. Copie o token do ambiente utilizado e envie-o no cabeçalho Authorization com o prefixo Bearer.
Sim. O sandbox permite desenvolver e testar a integração antes da produção. Os documentos gerados nesse ambiente não possuem validade jurídica.
Na API, seu sistema solicita operações ou informações à ZapSign. No webhook, a ZapSign envia automaticamente um evento ao seu sistema quando ocorre uma mudança configurada.
A documentação informa limite geral de 500 requisições por minuto para endpoints públicos, aplicado por IP ou token. Ao excedê-lo, a API pode retornar HTTP 429.
Atualmente, a página de planos inclui API nos planos Equipe e Enterprise. O sandbox pode ser utilizado para desenvolver e testar a integração antes da operação em produção.

![[Banner] Como a assinatura eletrônica está redefinindo eficiência e redução de custos nas empresas brasileiras [Banner] Validade jurídica das assinaturas digitais e eletrônicas: guia definitivo com análises de especialistas](https://blog.zapsign.com.br/wp-content/uploads/2024/10/Banners-para-blog-whitepaper-reducao-de-custos.png)
![[Banner] Sign-up 1 – 10.12.24 Cadastre-se gratuitamente na ZapSign](https://blog.zapsign.com.br/wp-content/uploads/2024/12/BANNER-SIGN-UP-1.png)



