Limites de pedidos e idempotência

Idempotência

Envie um cabeçalho Idempotency-Key num POST para que seja seguro repeti-lo. Utilize um valor novo e único por operação (um UUID ou um id do seu próprio sistema, como onboarding-8841): entre 1 e 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

O primeiro pedido com uma chave é executado normalmente e a resposta fica guardada durante 24 horas.
Uma repetição com a mesma chave e o mesmo pedido (método, caminho, query e corpo) recebe novamente a resposta guardada, com o cabeçalho Idempotent-Replayed: true.
A mesma chave com um pedido diferente dá 422 idempotency-key-reused.
Uma repetição enquanto o primeiro pedido ainda está em execução dá 409 idempotency-in-progress; tente novamente daqui a pouco.
As respostas 5xx não são guardadas, pelo que uma repetição após um erro do servidor é novamente executada.

As chaves estão associadas a quem faz a chamada: a organização e a chave de API (ou o utilizador do painel) que as enviou. As operações que aceitam uma chave estão assinaladas com um parâmetro de cabeçalho Idempotency-Key na referência da API, entre elas criar modelos, carregar ficheiros, publicar, criar e anular envelopes, reenviar ligações, criar sessões de assinatura, criar ligações de assinatura e endpoints de webhook e reenviar eventos.

Eliminação de duplicados pelo seu próprio id

As chaves de idempotência protegem as repetições de um pedido. Para garantir que um objeto de negócio só é enviado uma 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 devolve-o com 200 e x-deduplicated: true em vez de criar outro. Isto aplica-se entre chaves, entre dias e a pedidos simultâneos.

Limites de pedidos

A API autenticada (chaves de API) não tem atualmente um limite fixo de pedidos por intervalo; o envio está limitado pelo seu plano. Os limites aplicam-se onde há possibilidade de abuso:

Onde	Limite
`POST /v1/public/verify`	60 pedidos por minuto por IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 pedidos por minuto por IP
`GET /v1/sso/discover`	30 consultas por minuto por IP
Códigos de utilização única 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
Ligações permanentes	Por ligação: `perEmailPerDay` (predefinição 3), `perIpPerHour` (predefinição 20), `dailyCap` opcional
Início de sessão com palavra-passe no painel	10 por minuto por IP; 10 a cada 15 minutos por endereço de e-mail
Registo com palavra-passe no painel	5 por minuto por IP; 5 por hora por endereço de e-mail
E-mails de reposição de palavra-passe	5 a cada 15 minutos por IP; 3 por hora por endereço de e-mail
Códigos de início de sessão 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, normalmente com um cabeçalho Retry-After em segundos.