Como preparar o seu projeto

Antes de integrar, decida o nível de cada tipo de documento e garanta que o seu sistema tenha os dados de quem assina.

Simples × avançada

Simples

Aceites, termos, autorizações e documentos do dia a dia.

Confere: Link exclusivo; nome e e-mail do signatário; trilha de auditoria.

Padrão: Só e-mail — o link por e-mail autentica, sem código

Avançada

Contratos, propostas, documentos de RH e de maior valor.

Confere: Tudo da simples + CPF e data de nascimento conferidos + dois canais.

Padrão: Planos pagos: e-mail + WhatsApp (link por e-mail, código pelo WhatsApp). Free: e-mail + código (link e código por e-mail)

Envie signatureLevel: "SIMPLE" ou "ADVANCED" (padrão) em cada documento. Detalhes jurídicos em Níveis de assinatura.

Modos de autenticação

Modo	authenticationMethod	Link vai por	Código	Você precisa enviar
Só e-mail	EMAIL_LINK	e-mail	sem código	e-mail
Só WhatsApp (planos pagos)	WHATSAPP_LINK	WhatsApp	sem código	celular (obrigatório)
E-mail + WhatsApp (planos pagos)	WHATSAPP_OTP	e-mail	pelo WhatsApp	e-mail; celular opcional (o signatário pode informar)
E-mail + código	EMAIL_OTP	e-mail	por e-mail	e-mail

Padrão de cada projeto

Cada projeto pode ter o seu padrão por nível (dashboard → Projetos → Editar, ou PATCH /v1/projects/:id com simpleAuthenticationMethod e advancedAuthenticationMethod; null volta ao padrão da plataforma). Os modos de WhatsApp só podem ser padrão em planos pagos. A ordem de decisão é: authenticationMethod do signatário → do documento → do template → do projeto → da plataforma.

bash

curl -X PATCH https://api.assinapi.com.br/v1/projects/prj_… \
  -H "Authorization: Bearer <token do dashboard>" -H "X-Organization-Id: org_…" \
  -H "Content-Type: application/json" \
  -d '{ "simpleAuthenticationMethod": "EMAIL_OTP", "advancedAuthenticationMethod": null }'

Checklist

Colete no seu sistema o nome e o e-mail de quem vai assinar e, nos planos pagos, o celular com WhatsApp (formato +55 DDD número). Para assinatura avançada, colete também o CPF; a data de nascimento é opcional (se enviar, o signatário precisa acertar).
Defina por tipo de documento se ele é simples ou avançado e envie signatureLevel. O modo de autenticação vem do padrão do projeto; só envie authentication/authenticationMethod quando quiser outro.
Configure em Projetos o padrão de autenticação de cada nível, se o da plataforma não servir (ex.: tudo pelo WhatsApp, nos planos pagos). No Free, o link e o código vão só por e-mail.
WhatsApp é dos planos pagos (no Free a API responde 402 WHATSAPP_REQUIRES_PAID_PLAN). Para "Só WhatsApp", envie sempre o phone; para "E-mail + WhatsApp", enviar o phone evita que o signatário precise digitar.
Receba os webhooks (envelope.completed) para atualizar o status e baixe o PDF assinado com a página de auditoria.
Teste no Sandbox (código 123456; nenhuma mensagem de WhatsApp é enviada) e troque para a chave de Produção.

Exemplo

bash

# Contrato (avançada): nos planos pagos, link por e-mail + código pelo WhatsApp (padrão); no Free, link e código por e-mail
curl -X POST https://api.assinapi.com.br/v1/signature-requests \
  -H "Authorization: Bearer $ASSINAPI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Contrato", "signatureLevel": "ADVANCED", "document": { "filename": "c.pdf", "contentBase64": "…" }, "signer": { "name": "Ana", "email": "ana@email.com", "cpf": "529.982.247-25", "phone": "+5511999999999" } }'

# Termo de aceite (simples): só WhatsApp, sem código (planos pagos; no Free: 402 WHATSAPP_REQUIRES_PAID_PLAN)
curl -X POST https://api.assinapi.com.br/v1/signature-requests \
  -H "Authorization: Bearer $ASSINAPI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Termo", "signatureLevel": "SIMPLE", "authentication": "WHATSAPP_LINK", "document": { "filename": "t.pdf", "contentBase64": "…" }, "signer": { "name": "Ana", "email": "ana@email.com", "phone": "+5511999999999" } }'