Assina

API do Assina

Crie, envie e acompanhe envelopes a partir do seu sistema. JSON, campos em português, autenticação por chave.

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

  • 200 Página da lista
  • 400 Dados inválidos ou arquivo recusado
  • 401 Chave 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
    }
  ]
}
  • 200 Mesma Idempotency-Key: o envelope que já existia
  • 201 Criado
  • 400 Dados inválidos ou arquivo recusado
  • 401 Chave ausente, revogada ou de conta suspensa
  • 500 Erro interno (sem detalhe)

GET/api/v1/envelopes/{id}

Envelope e destinatários

  • 200 Envelope
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope 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`).

  • 204 Excluído
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)
  • 409 Não é rascunho

GET/api/v1/envelopes/{id}/arquivo

URL temporária do original ou do assinado

  • 200 URL de 5 minutos
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)

POST/api/v1/envelopes/{id}/arquivo

Valida o PDF enviado pela upload_url

  • 200 Anexado
  • 400 Dados inválidos ou arquivo recusado
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)
  • 409 O 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`).

  • 200 Enviado
  • 400 Dados inválidos ou arquivo recusado
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)
  • 409 O envelope mudou de situação
  • 429 Limite atingido

GET/api/v1/envelopes/{id}/eventos

Trilha de auditoria

  • 200 Eventos em ordem, encadeados por hash; `divergencia` é null quando a trilha está íntegra
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)

POST/api/v1/envelopes/{id}/cancelar

Cancela um envelope enviado

{
  "motivo": "Valor mudou"
}
  • 200 Cancelado
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)
  • 409 O 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.

  • 200 Quantos receberam
  • 401 Chave ausente, revogada ou de conta suspensa
  • 404 Envelope não encontrado (inclusive de outra conta)
  • 409 O envelope mudou de situação
  • 429 Limite 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".

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);