Autenticação

A API autentica servidores com chaves de API da organização. Uma chave pertence a uma organização (não a uma pessoa), tem um conjunto de permissões e funciona em exatamente um modo: teste ou produção.

Enviar a chave

Utilize qualquer um destes cabeçalhos:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

As chaves têm o formato bf_live_… ou bf_test_…. A falta de chave dá um 401 (unauthorized); uma chave mal formada, revogada ou expirada também dá 401. Mantenha as chaves no seu servidor: nunca as inclua num navegador nem numa aplicação móvel. Para assinar no navegador, crie antes uma sessão de assinatura.

Chaves de teste e de produção

	Teste (`bf_test_…`)	Produção (`bf_live_…`)
Documentos	Gerados com a marca de água `TEST`	Sem marca de água
E-mail	Entregue apenas a membros da sua organização	Entregue a todos os destinatários
Faturação	Gratuito e ilimitado, nunca contabilizado	Os envelopes concluídos contam para o seu plano
Dados	Os envelopes, ligações e endpoints de webhook criados com a chave ficam no modo de teste	Modo de produção

O modo vem da chave, nunca do pedido: ?test_mode=true em POST /v1/envelopes só se aplica a sessões do painel. As listas (GET /v1/envelopes, GET /v1/signing-links) só devolvem o modo da chave, e os eventos de um envelope só vão para endpoints de webhook do mesmo modo. Todos os envelopes e payloads de webhook indicam em que modo estão (testMode).

Criar e revogar chaves

As chaves são geridas no painel, em Definições › Chaves de API, pelos membros com a permissão apikey:manage (proprietários e administradores). O segredo é mostrado uma única vez, quando a chave é criada. Pode atribuir a uma chave um nome, um modo, uma validade (de 1 a 365 dias, ou nenhuma) e âmbitos.

Âmbitos

Os âmbitos de uma chave são as permissões da organização que pode utilizar. Por predefinição, uma chave nova recebe as permissões de quem a criou, menos as administrativas (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), e ninguém pode conceder a uma chave uma permissão que não tem. Uma chamada fora dos âmbitos da chave dá um 403 que indica a permissão em falta:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Permissão	O que a chave pode fazer
`template:read`	Listar e ler modelos, versões e os respetivos PDF
`template:write`	Criar modelos, carregar ficheiros, guardar rascunhos, eliminar modelos não utilizados
`template:publish`	Publicar um rascunho como nova versão
`envelope:read`	Listar e ler envelopes, documentos e registos de auditoria; listar ligações de assinatura
`envelope:send`	Criar envelopes, sessões de assinatura e ligações de assinatura; reenviar ligações
`envelope:void`	Anular envelopes em curso
`org:manage`	Gerir endpoints de webhook e reenviar eventos; ler as definições da organização
`billing:manage`	Ler a utilização (`GET /v1/usage`) e os montantes das faturas

Gerir endpoints de webhook exige org:manage, que as chaves não recebem por predefinição: registe os endpoints no painel ou crie explicitamente uma chave com esse âmbito.

O que cada endpoint aceita

Cada operação na referência da API indica os respetivos esquemas de segurança. Em resumo:

Chave de API ou sessão do painel: modelos, envelopes, sessões de assinatura, ligações de assinatura, endpoints de webhook, definições da organização, resumo de faturação e utilização.
Apenas sessão do painel: chaves de API, tokens SCIM, definições da ligação SSO, carregamento do logótipo da organização, checkout e portal de faturação, revelação de um segredo de webhook.
Token do signatário: /v1/signing/*, utilizado pela página alojada e pelo <bf-signing> com um token de sessão (bfs_…) ou com o token de acesso pelo qual este é trocado (bfa_…).
Público: /v1/links/{id} (ligações permanentes), /v1/sso/discover e a API de verificação (/v1/public/*, /.well-known/bona-fide/keys.json).

Iniciar sessão no painel

As pessoas (não os servidores) iniciam sessão no painel em https://app.bonafidesign.com/sign-in. A predefinição é e-mail e palavra-passe; as alternativas são um código de seis dígitos enviado por e-mail (Enviar-me um código por e-mail), uma ligação mágica, uma chave de acesso, Google ou Microsoft e o SSO da sua empresa.

Criar uma conta com palavra-passe envia um e-mail: um código que confirma que o endereço é seu. Até lá, a palavra-passe não permite iniciar sessão. Registar-se com um endereço que já tem conta não altera nada e recebe exatamente a mesma resposta que um registo novo; o titular do endereço recebe um e-mail a explicar como iniciar sessão.
As palavras-passe têm entre 12 e 128 caracteres e são guardadas como hashes scrypt com salt. Uma nova palavra-passe que conste de uma fuga de dados conhecida é recusada: apenas os primeiros cinco caracteres do seu hash SHA-1 são enviados para o Have I Been Pwned (k-anonimato), nunca a palavra-passe. Se esse serviço não responder em dois segundos, a palavra-passe é aceite sem a verificação.
Esqueceu-se da palavra-passe? O e-mail de reposição contém uma ligação para uma página onde escolhe uma nova. A ligação funciona uma vez e expira ao fim de uma hora, e utilizá-la termina a sessão em todos os dispositivos.
Ainda não tem palavra-passe? As contas criadas com um código, uma ligação, uma chave de acesso ou Google / Microsoft continuam a iniciar sessão dessa forma e podem acrescentar uma palavra-passe em Definições › Conta. Definir a primeira palavra-passe exige um início de sessão nos últimos 15 minutos (a página envia-lhe um código por e-mail para confirmar que é o próprio); alterá-la exige a atual. Em ambos os casos, as suas outras sessões são terminadas.
Os erros nunca revelam contas: uma palavra-passe errada, um endereço desconhecido e uma conta sem palavra-passe recebem a mesma resposta, e um pedido de reposição indica sempre que o e-mail está a caminho.
Limites de pedidos: o início de sessão com palavra-passe, o registo e os pedidos de reposição são limitados por endereço IP e por endereço de e-mail; acima do limite, a resposta é 429 até a janela terminar.
SSO da empresa: quando a sua organização impõe o SSO, os membros dos respetivos domínios de e-mail só iniciam sessão através do fornecedor de identidade. As palavras-passe, os códigos e as ligações mágicas são recusados para esses membros; os proprietários mantêm o código por e-mail como acesso de emergência.

IDs de pedido

Todas as respostas incluem um cabeçalho x-request-id, e todos os corpos de erro um requestId. Pode enviar o seu próprio x-request-id (8 a 128 caracteres de A-Z a-z 0-9 . _ -) para correlacionar registos; caso contrário, a API gera um. Indique-o quando contactar o suporte.