Pré-requisitos

  • Conta na ZapSign (o plano grátis serve para testar).
  • Um terminal com curl — ou Postman/Insomnia, se preferir.
  • Um PDF acessível por URL pública (use o de exemplo abaixo).

Passo a passo

Gere e teste seu token

Em app.zapsign.com.br → Configurações → Integrações → API, copie o api_token. Todas as chamadas usam o header Authorization: Bearer. Teste listando seus documentos:

terminalbash
curl -s https://api.zapsign.com.br/api/v1/docs/ \
  -H "Authorization: Bearer SEU_TOKEN"

Se voltar um JSON (mesmo vazio), a autenticação está funcionando.

Crie o documento com signatários

POST /api/v1/docs/bash
curl -s -X POST https://api.zapsign.com.br/api/v1/docs/ \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato de Teste",
    "url_pdf": "https://zapsign.s3.amazonaws.com/exemplo.pdf",
    "external_id": "PEDIDO-0001",
    "lang": "pt",
    "send_automatic": true,
    "signers": [
      {
        "name": "Maria Silva",
        "email": "maria@empresa.com",
        "auth_mode": "assinaturaTela"
      }
    ]
  }'

Campos que importam:

CampoPara que serve
url_pdfURL pública do PDF. Alternativa: base64_pdf para enviar o arquivo embutido. Há também criação por modelo (templates com variáveis).
signers[]Nome e e-mail de cada signatário; auth_mode define a autenticação (assinatura na tela, token por e-mail, selfie…).
send_automatictrue = a ZapSign envia o convite por e-mail. false = você distribui o sign_url pelo seu canal (WhatsApp, app…).
external_idSeu identificador interno, para reconciliar com o seu sistema.
order_groupCom signature_order_active: true, define a ordem de assinatura entre signatários.

A resposta traz o token do documento e, em cada signatário, o sign_url — o link de assinatura.

Acompanhe o status

GET /api/v1/docs/{doc_token}/bash
curl -s https://api.zapsign.com.br/api/v1/docs/DOC_TOKEN/ \
  -H "Authorization: Bearer SEU_TOKEN"

O campo status evolui de pending para signed; o PDF assinado fica em signed_file.

Receba eventos por webhook (recomendado)

Em vez de fazer polling, registre uma URL para receber eventos:

POST /api/v1/user/company/webhook/bash
curl -s -X POST https://api.zapsign.com.br/api/v1/user/company/webhook/ \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sua-api.com/webhooks/zapsign",
    "type": "doc_signed",
    "headers": [
      { "name": "X-Webhook-Secret", "value": "um-segredo-seu" }
    ]
  }'

Eventos úteis: doc_created, doc_signed (documento totalmente assinado), doc_refused, além de eventos por signatário. Valide o header secreto no seu endpoint.

Pronto! Documento criado, assinado e notificado. Esse fluxo — criar, acompanhar, reagir — é exatamente o que o servidor MCP automatiza para agentes de IA.

SDKs e recursos para o seu agente

  • SDKs oficiais em TypeScript, Java e Go — veja a documentação.
  • Doc consultável por IA: GET https://docs.zapsign.com.br/master.md?ask=sua-pergunta devolve o trecho relevante — perfeito para RAG e agentes de código.
  • Índice para LLMs: docs.zapsign.com.br/llms.txt.
  • Rate limits e códigos de erro estão descritos na seção de introdução da doc oficial.

Problemas comuns

ErroCausa provável e correção
401Token ausente/errado. Confira o header Authorization: Bearer SEU_TOKEN (com espaço após "Bearer").
400 ao criar documentoJSON malformado ou url_pdf inacessível. Teste a URL do PDF no navegador.
Signatário não recebeu e-mailsend_automatic em false, ou e-mail caiu no spam. Você sempre pode usar o sign_url direto.
Webhook não disparaURL sem HTTPS válido ou tipo de evento diferente do esperado. Confira o tipo registrado e os logs do seu endpoint.

Próximos passos