API de assinatura eletrônica

A API serve para o caso em que o documento nasce no seu sistema: um pedido aprovado, um cadastro concluído, uma proposta aceita. Você manda o PDF e a lista de quem assina; a plataforma cria o envelope, dispara os convites por e-mail e devolve o status a cada consulta.

Todas as rotas ficam sob /v1, respondem JSON e exigem uma chave de API. A versão está no caminho desde a primeira rota: contrato público quebra o sistema do outro lado, que não atualiza quando nós atualizamos.

Todos os exemplos desta página já usam este endereço. Basta trocar o token pelo seu.

Todas as chamadas são feitas sobre HTTPS. Requisição em HTTP puro falha, e não por rigor nosso: uma chave que trafegou sem TLS passou em texto claro por toda a rede no caminho, e deve ser considerada vazada.

Toda requisição leva a chave no cabeçalho Authorization. Requisição sem chave, ou com chave inválida, recebe 401 e não chega a tocar em nada da conta.

Confirma que o token funciona e devolve o que ele pode fazer. Útil para validar a configuração antes de subir a integração — é a primeira chamada que vale a pena fazer depois de criar uma chave.

As chaves são criadas na plataforma, nunca pela API — uma chave não pode emitir outra. Se pudesse, um vazamento pontual viraria acesso permanente e auto-renovável.

O proprietário da conta sempre pode. Qualquer outra pessoa precisa da permissão Chaves de API no perfil de acesso dela. É deliberadamente mais restrito que as outras telas administrativas: uma chave age em nome da conta inteira, por tempo indeterminado e sem segundo fator.

Criar chave também exige que o plano da conta inclua acesso à API. A tela abre sem o recurso para você conseguir consultá-lo, mas a criação é recusada.

Uma integração que só consulta status não deveria conseguir disparar e-mail em nome da conta — e é justamente esse tipo de chave que costuma acabar num repositório público.

A rota recusa com 403 e insufficient_scope quando falta escopo, e a mensagem diz qual está faltando.

Na mesma tela, o botão Revogar ao lado da chave. O efeito é imediato: a próxima requisição com aquele token recebe 401. A chave continua listada como revogada, porque a trilha de auditoria precisa saber que ela existiu e o que fez.

Os envelopes criados por uma chave revogada não são afetados: continuam válidos, assináveis e consultáveis pela plataforma.

Uma conta pode ter até 25 chaves ativas ao mesmo tempo. Revogue as que não estiverem em uso — cada chave viva é uma porta a mais.

Toda rota de escrita aceita — e a criação de envelope exige — o cabeçalho Idempotency-Key.

Use um valor único por operação (um UUID, um ULID ou o id do pedido no seu sistema), entre 8 e 120 caracteres, com letras, números, hífen e underscore. Repetir a mesma chave devolve o mesmo envelope, sem criar nem reenviar nada.

Se a primeira tentativa morreu no meio — a conexão caiu depois de o envelope nascer, mas antes de sair —, repetir com a mesma chave retoma de onde parou: o documento, os signatários e os campos são reescritos com o que veio na repetição, e o envio acontece. Mande o mesmo corpo da primeira vez; um corpo diferente na retomada produz um envelope com o conteúdo novo.

Depois de o envelope ter saído, nada é sobrescrito: a repetição devolve o que existe, intacto.

Cada chave tem um teto próprio, exibido na tela de Chaves de API. O padrão é 10 requisições por segundo; ao ultrapassar, a chave fica bloqueada por 60 segundos e as requisições recebem 429.

A resposta traz o cabeçalho Retry-After em segundos. Respeite-o: repetir antes disso apenas prolonga o bloqueio.

Existe também um teto por endereço de origem, aplicado antes da autenticação, folgado o suficiente para nunca alcançar quem usa a API normalmente. Ele existe para conter enxurrada de requisições sem chave válida. Se você concentra várias integrações atrás de um mesmo IP de saída e vê 429 antes do teto da chave, fale com o suporte.

Qualquer campo que não esteja documentado devolve 400 apontando o nome dele. Um titlle ignorado em silêncio faria você depurar por horas um envelope que saiu diferente do que mandou.

Vale também para os campos que o servidor decide sozinho: workspace_id, api_key_id, origin e created_by_user_id no corpo são recusados, e não silenciosamente descartados.

Toda resposta de /v1 traz o cabeçalho x-request-id, no formato req_…. Guarde-o nos seus próprios logs.

Ao abrir um chamado, mande esse valor em vez de descrever o horário — ele encontra a requisição exata, com o status, a duração e o motivo da recusa. Quem administra a conta vê a mesma linha na tela Logs de integração do painel, onde o histórico dos últimos 30 dias fica disponível com filtros por data, rota e resultado.

type diz o que fazer; code é estável e serve para um switch; message é para o humano que está depurando — não a use em comparações.

Trate qualquer código desconhecido como falha genérica: a lista cresce quando uma regra nova entra, e um switch sem ramo padrão quebraria nesse dia.

A repetição idempotente devolve 201 igual à primeira chamada. O código descreve o RESULTADO — o envelope existe e foi criado por esta requisição lógica —, não quantas vezes a rede tentou.

Listagens usam cursor, não número de página. A lista cresce pela ponta, e paginar por deslocamento faria linhas pularem ou se repetirem entre uma página e a seguinte.

Enquanto has_more for true, mande o next_cursor recebido no parâmetro cursor da próxima chamada.

Cria e envia o envelope numa única chamada. O corpo é multipart/form-data, porque o PDF vai junto — base64 dentro de JSON infla o arquivo em 33% e obriga os dois lados a manter o documento inteiro em memória como texto.

O cabeçalho Idempotency-Key é obrigatório aqui.

Resposta 201. O envelope já saiu e todos os signatários receberam o convite por e-mail — a API só cria envelope em parallel, então não há fila.

Os links vêm na resposta

Cada signatário traz signing_url: é o MESMO endereço que foi para o e-mail dele. Serve para quem entrega por outro canal — o WhatsApp do cliente, o próprio aplicativo —, sem precisar esperar que a pessoa abra a caixa de entrada.

Mande fields quando a assinatura precisar de um lugar determinado: rubrica ao lado de uma cláusula, minuta com espaço reservado, formulário com moldura desenhada. Sem o campo, nada muda — a API posiciona no rodapé da última página como sempre fez.

O sistema de coordenadas

Fração de 0 a 1 da página já renderizada, ou seja depois de aplicar a rotação nativa do PDF. A origem é o canto superior esquerdo.

Fração, e não pontos ou pixels, porque o mesmo envelope é desenhado em escalas diferentes: um valor em pixel amarraria a posição ao zoom de quem gerou a requisição e o campo sairia deslocado no PDF final.

Os três tipos

A data vem do servidor de propósito: um campo preenchido com o relógio do navegador seria prova controlada por quem está sendo auditado. Ela é exibida no fuso da conta.

Todo signatário precisa de uma assinatura

Se você mandar fields, cada pessoa de signers precisa de ao menos um campo do tipo signature obrigatório. Faltando alguém, a criação é recusada com 422 e signer_without_signature_field, e o meta traz os e-mails que ficaram de fora.

Obrigatório porque uma assinatura opcional é uma assinatura que a pessoa pode deixar em branco: ela abriria o documento, concluiria, e o envelope andaria sem a assinatura dela. Campos de rubrica e data podem ser opcionais à vontade — a exigência é sobre a assinatura.

A recusa existe porque a alternativa é pior: um signatário recebe o convite, abre o documento e não tem onde assinar. O envelope trava no meio e quem descobre é o cliente do outro lado — uma linha esquecida no array vira um telefonema.

A parte pré-assinada também precisa de posição

Com pre_signed: true no envelope, o titular da chave entra como parte já assinada — e é num campo que a assinatura salva dele é carimbada no envio. Como o e-mail dele não está em signers, o campo dele é marcado com pre_signed: true em vez de signer_email.

É assim, e não pelo e-mail, pelo mesmo motivo que o envelope não aceita escolher quem pré-assina: a identidade sai da chave autenticada, nunca do payload. Um campo que aceitasse o e-mail do titular seria uma segunda porta para apontar a assinatura salva de alguém.

Lista apenas os envelopes criados por esta chave. Não existe parâmetro que amplie o conjunto.

Estado atual do envelope, com a lista completa de signatários. É a rota para acompanhar o progresso enquanto não houver webhooks.

A resposta tem exatamente o mesmo formato da criação — o mesmo objeto, com os campos de data preenchidos conforme o envelope avança.

É a saída para quando o e-mail não chegou, para quando você perdeu a resposta da criação, e para quando precisa do link de novo porque vai entregá-lo por outro canal. Responde 200 com o envelope inteiro, e a signing_url preenchida só para o signatário reenviado — os outros vêm null, como em qualquer leitura.

Exige envelopes:write, e não envelopes:read: a chamada derruba um link de assinatura, o que é escrita. Não aceita Idempotency-Key — repetir é justamente o que ela faz, e uma chave devolveria em silêncio um link que já não vale.

Cancela o envelope e derruba os links de assinatura de quem ainda não assinou. Quem já tinha assinado permanece registrado — cancelar não apaga o que aconteceu.

É POST e não DELETE porque o envelope continua existindo, com a trilha inteira, que é o que uma auditoria espera encontrar.

reason é opcional, até 500 caracteres, e entra na trilha de auditoria.

A resposta é o envelope no formato de sempre, já com status: "cancelled", cancelled_at preenchido e cada signatário pendente em status: "cancelled". Quem já havia assinado permanece como signed.

Baixa os arquivos do envelope. A resposta é o conteúdo em si, com Content-Disposition: attachment — nunca um link temporário, para que o download continue dentro da sua autorização e apareça na trilha de auditoria da conta.

O Content-Type acompanha o artefato: application/pdf, application/json ou application/zip. O nome do arquivo vem no Content-Disposition, derivado do título do envelope e já higienizado — no curl, -O -J o respeita.

Você cadastra uma URL sua e escolhe os eventos. Quando um deles acontece, enviamos um POST com content-type application/json e um cabeçalho de assinatura. Responder qualquer 2xx encerra a entrega; qualquer outra coisa — inclusive um redirecionamento, que nós não seguimos — conta como falha e entra na fila de retentativa.

Dá para cadastrar de dois jeitos: na tela de Webhooks da plataforma, ou pelas rotas /v1/webhooks descritas adiante. Os dois cadastros são independentes de propósito — veja Isolamento por chave.

Mandar ["*"] inscreve também nos eventos que entrarem no produto depois, sem você precisar voltar aqui.

Campos de data por evento

O id e o tipo vêm repetidos no cabeçalho e no corpo de propósito: assim você deduplica e roteia antes de fazer o JSON.parse, que é justamente o que não deve acontecer antes de a assinatura ser conferida.

A mensagem assinada é o timestamp, um ponto literal, e o corpo cru — nesta ordem, sem espaços.

Confira três coisas, nesta ordem: o timestamp está dentro de 300 segundos do seu relógio; o HMAC recalculado bate; e a comparação foi feita em tempo constante. Só depois faça o JSON.parse.

O contador de falhas é de falhas consecutivas: uma entrega bem-sucedida o zera. Quando um endpoint é suspenso, quem administra a conta recebe o aviso na plataforma e na trilha de auditoria — nunca por webhook, porque avisar por webhook que o webhook está quebrado não chegaria a ninguém.

Todas devolvem o mesmo objeto de endpoint — e nenhuma devolve o segredo, com uma exceção explicada abaixo.

curl -X POST https://apisign.bitsai.app/v1/webhooks \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: webhook-producao-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Produção",
    "url": "https://seusite.com.br/leggal/events",
    "events": ["envelope.signed", "envelope.completed", "document.ready"]
  }'

{
  "id": "d3f8a1b2-4c56-4e78-9a0b-1c2d3e4f5a6b",
  "name": "Produção",
  "url": "https://seusite.com.br/leggal/events",
  "status": "active",
  "subscribed_events": ["envelope.signed", "envelope.completed", "document.ready"],
  "secret": "whsec_4f1a...c8d2",
  "secret_last_four": "c8d2",
  "secret_rotated_at": "2025-03-18T14:00:00.000Z",
  "failure_count": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2025-03-18T14:00:00.000Z",
  "updated_at": "2025-03-18T14:00:00.000Z"
}

curl https://apisign.bitsai.app/v1/webhooks \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"

curl -X PATCH https://apisign.bitsai.app/v1/webhooks/d3f8a1b2-4c56-4e78-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Produção",
    "url": "https://seusite.com.br/leggal/events/v2",
    "events": ["*"],
    "rotate_secret": true
  }'

curl -X DELETE https://apisign.bitsai.app/v1/webhooks/d3f8a1b2-4c56-4e78-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"

Outra chave da mesma conta não o lista, não o altera e não o revoga — recebe 404, igual a um id que não existe. O que foi cadastrado na tela da plataforma também é invisível para qualquer chave, e vice-versa.

Isso é mais restritivo que o resto da API de propósito. Um endpoint de webhook decide para onde os dados da conta vão: se uma chave pudesse reapontar o endpoint de outra, uma única chave vazada redirecionaria os webhooks da empresa inteira. Ler dado alheio é grave; desviar o fluxo é pior.

Na plataforma, criar o envelope, anexar o PDF, definir signatários, posicionar campos e enviar são cinco telas porque há alguém decidindo entre uma e outra. Numa integração não há: o seu sistema já sabe tudo quando chama.

Expor os cinco passos produziria rascunhos órfãos toda vez que a integração falhasse no meio — e você não teria como terminá-los, já que posicionar campo exige a tela.

Sem fields, cada signatário recebe um campo de assinatura obrigatório no rodapé da última página, em grade de duas colunas, preenchida de baixo para cima. Se não couber, transborda para a página anterior — nunca para uma folha nova, porque acrescentar página mudaria o documento que você enviou.

Cabem 18 assinaturas por página. Se a lista de signatários não couber nas páginas do documento, a criação é recusada com 422 e o número exato de vagas disponíveis.

Esse é o padrão porque cobre o caso comum sem exigir que você abra o PDF: a praxe brasileira assina no fim do documento, e calcular coordenada de um arquivo que você mandou mas não desenhou é onde a maioria erra — e o erro só apareceria no PDF assinado, quando já não dá para corrigir sem cancelar.

Quando a posição importa, mande fields: a tabela completa, o sistema de coordenadas e as regras estão em Posicionar campos. O padrão continua valendo para quem não manda nada.

signing_order na API aceita apenas parallel, que também é o padrão. Mandar sequential devolve 400.

O motivo é o link. No paralelo, todos os signatários recebem o token no envio, e é por isso que POST /v1/envelopes consegue devolver o signing_url de cada um. No sequencial só o primeiro recebe: o link do segundo nasce quando o primeiro assina, dias depois, sem nenhuma requisição por perto — e como guardamos apenas o hash do token, ele não teria como ser buscado nem por você nem por nós. A resposta traria um link de três, e os outros dois não existiriam em lugar nenhum.

A fila sequencial continua na plataforma, onde a tela mostra de quem é a vez e o e-mail é o único canal de entrega.

Com pre_signed: true, o titular da chave entra no envelope como parte já assinada, e a assinatura salva no perfil dele é aplicada no momento do envio. É o caso de quem dispara contrato padrão e só precisa que o cliente assine o lado dele.

Quem é essa pessoa não é escolha sua: nome e e-mail saem da conta, do usuário que criou a chave. Um campo que aceitasse e-mail permitiria apontar a assinatura salva de terceiro para um contrato qualquer, e o resultado teria aparência de prova.

Ela fica fora da fila de assinatura, então não altera a ordem dos demais, e o certificado registra que a autorização foi a posse da chave — não uma sessão interativa.

Se você também mandar fields, reserve um campo para ela com pre_signed: true — é nesse campo que a assinatura salva é carimbada. Ver Posicionar campos.

Se a conta exige documento de todo signatário, require_cpf: false não a desliga — uma conta que definiu a exigência não deixa de exigir porque a chamada veio de um sistema. Quando a política é opcional, o campo da requisição vale.

O CPF coletado nunca sai pela API: a resposta traz apenas document_last_four, o suficiente para conferir identidade sem revelar o documento.

Duas integrações da mesma empresa não se veem, e nenhuma delas lê o que foi criado à mão na plataforma. Uma chave vazada compromete a integração dela — não o arquivo da conta inteira.

O workspace nunca vem da URL nem do corpo: ele sai do contexto da chave autenticada. Mandar workspace_id no corpo devolve 400.

Existe também draft, mas envelope criado pela API nunca fica nesse estado — ele nasce enviado.

Só a partir de completed os artefatos assinados existem: pedi-los antes devolve 404 com artifact_not_ready.

Em envelope criado pela API, todos nascem pending com invited_at preenchido: o convite de todo mundo sai no envio. Num envelope sequencial da plataforma, quem ainda não foi chamado também aparece como pending — ali o que diferencia os dois é justamente invited_at estar vazio.

Sem expires_at, vale o prazo padrão configurado na conta, calculado no fuso dela e sempre no fim do dia — um envelope criado às 23h com prazo de 7 dias não expira às 23h do sétimo dia, cortando o dia útil do signatário pela metade.

O link de assinatura nunca vive mais que o envelope: se o prazo for curto, o link vence junto.

Estourar a cota devolve 402 com billing_error e o código envelope_quota_exceeded, e nenhum envelope é criado — nem rascunho.

A família é billing_error justamente para você não perder tempo relendo o payload: não há campo errado, o que falta é contrato.

1. Confirme a chave antes de qualquer coisa.

curl https://apisign.bitsai.app/v1/me \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"

2. Crie o envelope. Guarde o id devolvido junto do seu registro — é por ele que você consulta depois.

curl -X POST https://apisign.bitsai.app/v1/envelopes \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: pedido-48219" \
  -F "file=@contrato.pdf;type=application/pdf" \
  -F "title=Contrato de prestação de serviços" \
  -F 'signers=[{"name":"Maria Silva","email":"maria@exemplo.com.br"}]'

3. Acompanhe. Enquanto não houver webhooks, consulte o envelope de tempos em tempos — a cada poucos minutos basta, e o limite de 10 requisições por segundo é folgado para isso.

curl https://apisign.bitsai.app/v1/envelopes/813720b6-… \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"

4. Quando o status for completed, baixe o que precisar. O pacote traz tudo de uma vez.

curl -O -J https://apisign.bitsai.app/v1/envelopes/813720b6-…/artifacts/package \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"

5. Precisou desistir? Cancele. Os links de quem ainda não assinou deixam de funcionar.

curl -X POST https://apisign.bitsai.app/v1/envelopes/813720b6-…/cancel \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido cancelado pelo cliente"}'