Limites de taxa e idempotência

Idempotência

Envie um cabeçalho Idempotency-Key em um POST para que seja seguro repeti-lo. Use um valor novo e exclusivo por operação (um UUID ou um id do seu próprio sistema, como onboarding-8841): de 1 a 255 caracteres ASCII imprimíveis.

curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-1d0b-4c2a-9a59-3f1f1c7d2b11" \
  -d @envelope.json

A primeira requisição com uma chave é executada normalmente, e a resposta é armazenada por 24 horas.
Uma nova tentativa com a mesma chave e a mesma requisição (método, caminho, query e corpo) recebe a resposta armazenada, com o cabeçalho Idempotent-Replayed: true.
A mesma chave com uma requisição diferente resulta em 422 idempotency-key-reused.
Uma nova tentativa enquanto a primeira requisição ainda está em execução resulta em 409 idempotency-in-progress; tente de novo em instantes.
Respostas 5xx não são armazenadas, então uma nova tentativa depois de um erro do servidor é executada de novo.

As chaves têm escopo no chamador: a organização e a chave de API (ou o usuário do painel) que as enviou. As operações que aceitam uma chave estão marcadas com um parâmetro de cabeçalho Idempotency-Key na referência da API, entre elas criar modelos, enviar arquivos, publicar, criar e anular envelopes, reenviar links, gerar sessões de assinatura, criar links de assinatura e endpoints de webhook e reenviar eventos.

Deduplicação pelo seu próprio id

As chaves de idempotência protegem as novas tentativas de uma requisição. Para garantir que um objeto de negócio seja enviado uma única vez, envie também o seu próprio id e dedupeOn:

{ "template": "tpl_…", "externalId": "user_8841", "dedupeOn": "external_id", "…": "…" }

Se já existir um envelope com esse externalId (no mesmo modo), POST /v1/envelopes o retorna com 200 e x-deduplicated: true em vez de criar outro. Isso vale entre chaves, entre dias e para requisições simultâneas.

Limites de taxa

A API autenticada (chaves de API) não tem hoje um limite fixo de requisições por intervalo; o envio é limitado pelo seu plano. Os limites se aplicam onde há possibilidade de abuso:

Onde	Limite
`POST /v1/public/verify`	60 requisições por minuto por IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 requisições por minuto por IP
`GET /v1/sso/discover`	30 consultas por minuto por IP
Códigos de uso único do signatário	5 códigos a cada 15 minutos por sessão; 5 tentativas por código
Reenvio ao destinatário	Uma vez por minuto por destinatário
Links permanentes	Por link: `perEmailPerDay` (padrão 3), `perIpPerHour` (padrão 20), `dailyCap` opcional
Entrada com senha no painel	10 por minuto por IP; 10 a cada 15 minutos por endereço de e-mail
Cadastro com senha no painel	5 por minuto por IP; 5 por hora por endereço de e-mail
E-mails de redefinição de senha	5 a cada 15 minutos por IP; 3 por hora por endereço de e-mail
Códigos de entrada no painel	3 por minuto por IP

Os endpoints públicos com limite enviam os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (em segundos). Acima do limite, a API responde 429 com um problema rate-limited, geralmente com um cabeçalho Retry-After em segundos.