Limiti di frequenza e idempotenza

Idempotenza

Invii un header Idempotency-Key con una richiesta POST per poterla ritentare in sicurezza. Usi un valore nuovo e univoco per ogni operazione (un UUID, o un id del Suo sistema come onboarding-8841): da 1 a 255 caratteri ASCII stampabili.

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

La prima richiesta con una chiave viene eseguita normalmente e la sua risposta viene memorizzata per 24 ore.
Un nuovo tentativo con la stessa chiave e la stessa richiesta (metodo, percorso, query e corpo) riceve di nuovo la risposta memorizzata, con l’header Idempotent-Replayed: true.
La stessa chiave con una richiesta diversa produce un 422 idempotency-key-reused.
Un nuovo tentativo mentre la prima richiesta è ancora in esecuzione produce un 409 idempotency-in-progress; riprovi poco dopo.
Le risposte 5xx non vengono memorizzate, quindi un nuovo tentativo dopo un errore del server viene eseguito di nuovo.

Le chiavi sono limitate al chiamante: l’organizzazione e la chiave API (o l’utente della dashboard) che le ha inviate. Le operazioni che accettano una chiave sono contrassegnate con un parametro header Idempotency-Key nel riferimento API; tra queste, la creazione di modelli, il caricamento di file, la pubblicazione, la creazione e l’annullamento di buste, il nuovo invio di link, la creazione di sessioni di firma, la creazione di link di firma e di endpoint webhook e la riconsegna di eventi.

Deduplicazione tramite il Suo id

Le chiavi di idempotenza proteggono i nuovi tentativi di una singola richiesta. Per assicurarsi che un oggetto di business venga inviato una sola volta, invii anche un Suo id e dedupeOn:

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

Se esiste già una busta con quell’externalId (nella stessa modalità), POST /v1/envelopes la restituisce con 200 e x-deduplicated: true invece di crearne un’altra. Questo vale indipendentemente da chiavi, giorni e richieste simultanee.

Limiti di frequenza

L’API autenticata (chiavi API) oggi non ha un limite fisso di frequenza delle richieste; l’invio è limitato dal Suo piano. I limiti si applicano dove sono possibili abusi:

Dove	Limite
`POST /v1/public/verify`	60 richieste al minuto per IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 richieste al minuto per IP
`GET /v1/sso/discover`	30 ricerche al minuto per IP
Codici monouso del firmatario	5 codici ogni 15 minuti per sessione; 5 tentativi per codice
Nuovo invio al destinatario	Una volta al minuto per destinatario
Link sempre attivi	Per link: `perEmailPerDay` (predefinito 3), `perIpPerHour` (predefinito 20), `dailyCap` facoltativo
Accesso alla dashboard con password	10 al minuto per IP; 10 ogni 15 minuti per indirizzo e-mail
Registrazione alla dashboard con password	5 al minuto per IP; 5 all’ora per indirizzo e-mail
E-mail di reimpostazione della password	5 ogni 15 minuti per IP; 3 all’ora per indirizzo e-mail
Codici di accesso alla dashboard	3 al minuto per IP

Gli endpoint pubblici soggetti a limiti inviano gli header RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (in secondi). Oltre il limite, l’API risponde 429 con un problema rate-limited, di solito con un header Retry-After in secondi.