Limity żądań i idempotencja

Idempotencja

Wyślij nagłówek Idempotency-Key z żądaniem POST, aby można je było bezpiecznie ponowić. Użyj nowej, unikalnej wartości dla każdej operacji (UUID lub identyfikatora z Twojego systemu, np. onboarding-8841): od 1 do 255 drukowalnych znaków ASCII.

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

Pierwsze żądanie z danym kluczem jest wykonywane normalnie, a jego odpowiedź jest przechowywana przez 24 godziny.
Ponowienie z tym samym kluczem i tym samym żądaniem (metoda, ścieżka, parametry zapytania i treść) otrzymuje odtworzoną zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true.
Ten sam klucz z innym żądaniem skutkuje błędem 422 idempotency-key-reused.
Ponowienie w trakcie wykonywania pierwszego żądania skutkuje błędem 409 idempotency-in-progress; spróbuj ponownie za chwilę.
Odpowiedzi 5xx nie są przechowywane, więc ponowienie po błędzie serwera zostanie wykonane od nowa.

Klucze są przypisane do wywołującego: organizacji i klucza API (lub użytkownika panelu), który je wysłał. Operacje, które przyjmują klucz, są oznaczone w dokumentacji API parametrem nagłówka Idempotency-Key; należą do nich tworzenie szablonów, przesyłanie plików, publikowanie, tworzenie i unieważnianie kopert, ponowne wysyłanie linków, tworzenie sesji podpisywania, tworzenie linków do podpisu i punktów końcowych webhooków oraz ponowne dostarczanie zdarzeń.

Deduplikacja według własnego identyfikatora

Klucze idempotencji chronią ponowienia jednego żądania. Aby mieć pewność, że obiekt biznesowy zostanie wysłany tylko raz, wyślij też własny identyfikator i dedupeOn:

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

Jeśli koperta z tym externalId już istnieje (w tym samym trybie), POST /v1/envelopes zwraca ją z 200 i x-deduplicated: true zamiast tworzyć kolejną. Dotyczy to również różnych kluczy, różnych dni i równoległych żądań.

Limity żądań

Uwierzytelnione API (klucze API) nie ma obecnie stałego limitu liczby żądań; wysyłanie jest ograniczone przez Twój plan. Limity obowiązują tam, gdzie możliwe są nadużycia:

Gdzie	Limit
`POST /v1/public/verify`	60 żądań na minutę na adres IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 żądań na minutę na adres IP
`GET /v1/sso/discover`	30 zapytań na minutę na adres IP
Jednorazowe kody dla osób podpisujących	5 kodów na 15 minut na sesję; 5 prób na kod
Ponowne wysyłanie do odbiorcy	Raz na minutę na odbiorcę
Stałe linki	Na link: `perEmailPerDay` (domyślnie 3), `perIpPerHour` (domyślnie 20), opcjonalnie `dailyCap`
Logowanie hasłem do panelu	10 na minutę na adres IP; 10 na 15 minut na adres e-mail
Rejestracja w panelu z hasłem	5 na minutę na adres IP; 5 na godzinę na adres e-mail
Wiadomości e-mail do resetowania hasła	5 na 15 minut na adres IP; 3 na godzinę na adres e-mail
Kody logowania do panelu	3 na minutę na adres IP

Publiczne punkty końcowe z limitem wysyłają nagłówki RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset (w sekundach). Po przekroczeniu limitu API odpowiada 429 z problemem rate-limited, zwykle z nagłówkiem Retry-After podanym w sekundach.