Assina
API do Assina
Crie, envie e acompanhe envelopes a partir do seu sistema. JSON, campos em português, autenticação por chave.
OpenAPI 3.1 (JSON) · Pegar a chave em Integrações
Autenticação
Cada conta tem uma chave de API, que fica em Integrações. Mande no cabeçalho de toda chamada. Gerar uma nova chave revoga a anterior na hora.
Authorization: Bearer assina_…Fluxo completo
# 1. Criar com o PDF numa URL https (ou sem arquivo_url, para receber a upload_url)
curl -s -X POST https://assina.app.br/api/v1/envelopes \
-H "Authorization: Bearer $ASSINA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-123" \
-d '{"titulo":"Contrato","arquivo_url":"https://exemplo.com.br/contrato.pdf",
"signatarios":[{"nome":"Ana Souza","email":"ana@exemplo.com.br"}],
"campos":[{"signatario_email":"ana@exemplo.com.br","tipo":"assinatura","pagina":1,"x":0.1,"y":0.8}]}'
# 1b. Sem arquivo_url: suba o PDF na upload_url e confirme
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @contrato.pdf
curl -s -X POST https://assina.app.br/api/v1/envelopes/$ID/arquivo -H "Authorization: Bearer $ASSINA_CHAVE"
# 2. Enviar
curl -s -X POST https://assina.app.br/api/v1/envelopes/$ID/enviar -H "Authorization: Bearer $ASSINA_CHAVE"
# 3. Consultar (e a trilha)
curl -s https://assina.app.br/api/v1/envelopes/$ID -H "Authorization: Bearer $ASSINA_CHAVE"
curl -s https://assina.app.br/api/v1/envelopes/$ID/eventos -H "Authorization: Bearer $ASSINA_CHAVE"
# 4. Depois do webhook envelope.concluido, baixar o assinado (URL de 5 minutos)
curl -s "https://assina.app.br/api/v1/envelopes/$ID/arquivo?versao=final" -H "Authorization: Bearer $ASSINA_CHAVE"Rotas
GET/api/v1/envelopes
Lista os envelopes da conta
200Página da lista400Dados inválidos ou arquivo recusado401Chave ausente, revogada ou de conta suspensa
POST/api/v1/envelopes
Cria um rascunho
Sempre cria um rascunho (nunca envia). Com `arquivo_url` (só https, até 10 MB), o PDF é baixado e validado na hora, e os `campos` podem vir junto. Sem ele, a resposta traz `upload_url` (PUT do PDF, válida por 2 h); depois chame `POST /envelopes/{id}/arquivo`. Repetir a mesma `Idempotency-Key` devolve o mesmo envelope com 200.
{
"titulo": "Contrato de prestação de serviços",
"arquivo_url": "https://exemplo.com.br/contrato.pdf",
"signatarios": [
{
"nome": "Ana Souza",
"email": "ana@exemplo.com.br",
"exigir_cpf": true
},
{
"nome": "Bruno Lima",
"email": "bruno@exemplo.com.br"
}
],
"campos": [
{
"signatario_email": "ana@exemplo.com.br",
"tipo": "assinatura",
"pagina": 2,
"x": 0.1,
"y": 0.8
}
]
}200Mesma Idempotency-Key: o envelope que já existia201Criado400Dados inválidos ou arquivo recusado401Chave ausente, revogada ou de conta suspensa500Erro interno (sem detalhe)
GET/api/v1/envelopes/{id}
Envelope e destinatários
200Envelope401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)
DELETE/api/v1/envelopes/{id}
Exclui um rascunho
Só rascunhos. Fora disso, `409 envelope_nao_e_rascunho` (cancele pelo painel ou por `/cancelar`).
204Excluído401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)409Não é rascunho
GET/api/v1/envelopes/{id}/arquivo
URL temporária do original ou do assinado
200URL de 5 minutos401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)
POST/api/v1/envelopes/{id}/arquivo
Valida o PDF enviado pela upload_url
200Anexado400Dados inválidos ou arquivo recusado401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)409O envelope mudou de situação
POST/api/v1/envelopes/{id}/enviar
Envia para assinatura
Congela o rascunho e manda os convites. Limites: 30 envios em 24 h e o limite de documentos do nível da conta (`429` com `limite` e `usados`).
200Enviado400Dados inválidos ou arquivo recusado401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)409O envelope mudou de situação429Limite atingido
GET/api/v1/envelopes/{id}/eventos
Trilha de auditoria
200Eventos em ordem, encadeados por hash; `divergencia` é null quando a trilha está íntegra401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)
POST/api/v1/envelopes/{id}/cancelar
Cancela um envelope enviado
{
"motivo": "Valor mudou"
}200Cancelado401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)409O envelope mudou de situação
POST/api/v1/envelopes/{id}/lembrar
Manda lembrete
Com `signatario_id`, só para ele; sem, para todos os que estão aguardando. No máximo um lembrete a cada 24 h por pessoa, até 10. Cada lembrete leva um link novo.
200Quantos receberam401Chave ausente, revogada ou de conta suspensa404Envelope não encontrado (inclusive de outra conta)409O envelope mudou de situação429Limite atingido
Erros
Todo erro vem como {codigo, mensagem}. Em dados_invalidos, "campos" diz o que corrigir; em arquivo_invalido, "motivo"; nos 429, "limite" e "usados".
credencial_invalidaChave de API ausente, revogada ou de conta suspensa.dados_invalidosOs dados enviados não passaram na validação. Veja "campos".arquivo_invalidoO arquivo não foi aceito. Veja "motivo".nao_encontradoEnvelope não encontrado.status_mudouO envelope mudou de situação e a ação não vale mais.envelope_congeladoO envelope já foi enviado e não pode ser alterado.envelope_nao_e_rascunhoSó rascunhos podem ser excluídos pela API.limite_diarioLimite de 30 envelopes enviados em 24 horas.limite_do_nivelLimite de documentos do nível da conta.lembrete_recenteEsse destinatário recebeu um lembrete há menos de 24 horas.limite_lembretesEsse destinatário já recebeu 10 lembretes.prazo_encerradoO prazo para assinar terminou.email_falhouNão consegui enviar o e-mail agora. Tente de novo.erro_internoAlgo deu errado. Nada foi alterado. Tente de novo.
Webhooks
Configure a URL (https) em Integrações. Cada evento chega por POST com Assina-Assinatura (HMAC-SHA256 do segredo sobre "t.corpo"), Assina-Entrega e Assina-Evento. Responda 2xx; sem isso, o Assina tenta de novo, até 6 vezes. Confira a assinatura assim:
// Conferir o webhook do Assina (Node 18+, sem dependências).
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const SEGREDO = process.env.ASSINA_WEBHOOK_SEGREDO; // whsec_… (tela Integrações)
createServer((req, res) => {
const partes = [];
req.on("data", (p) => partes.push(p));
req.on("end", () => {
const corpo = Buffer.concat(partes).toString("utf8"); // o corpo cru, antes do JSON.parse
const cab = String(req.headers["assina-assinatura"] ?? "");
const t = /t=(\d+)/.exec(cab)?.[1];
const v1 = /v1=([0-9a-f]{64})/.exec(cab)?.[1];
const esperado = createHmac("sha256", SEGREDO).update(`${t}.${corpo}`).digest("hex");
const recente = Math.abs(Date.now() / 1000 - Number(t)) < 300; // contra reenvio antigo
if (!t || !v1 || !recente || !timingSafeEqual(Buffer.from(v1), Buffer.from(esperado))) {
res.writeHead(401).end();
return;
}
const evento = JSON.parse(corpo); // { evento, envelope, signatario?, ocorrido_em }
console.log(req.headers["assina-entrega"], evento.evento, evento.envelope.id);
res.writeHead(200).end(); // 2xx = entregue; qualquer outra resposta será retentada
});
}).listen(3000);