הגבלות קצב ואידמפוטנטיות

אידמפוטנטיות

שולחים כותרת Idempotency-Key בבקשת POST כדי שיהיה בטוח לנסות אותה שוב. יש להשתמש בערך חדש וייחודי לכל פעולה (UUID, או מזהה מהמערכת שלכם כמו onboarding-8841): 1 עד 255 תווי 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

הבקשה הראשונה עם מפתח רצה כרגיל, והתגובה שלה נשמרת ל-24 שעות.
ניסיון חוזר עם אותו מפתח ואותה בקשה (שיטה, נתיב, שאילתה וגוף) מקבל שוב את התגובה השמורה, עם הכותרת Idempotent-Replayed: true.
אותו מפתח עם בקשה אחרת מחזיר 422 idempotency-key-reused.
ניסיון חוזר בזמן שהבקשה הראשונה עדיין רצה מחזיר 409 idempotency-in-progress; מנסים שוב כעבור רגע.
תגובות 5xx אינן נשמרות, כך שניסיון חוזר אחרי שגיאת שרת רץ מחדש.

המפתחות תחומים למבצע הקריאה: הארגון ומפתח ה-API (או משתמש לוח הבקרה) ששלחו אותם. פעולות שמקבלות מפתח מסומנות בפרמטר כותרת Idempotency-Key במדריך העזר ל-API, ביניהן יצירת תבניות, העלאת קבצים, פרסום, יצירה וביטול של מעטפות, שליחה חוזרת של קישורים, יצירת סשני חתימה, יצירת קישורי חתימה ונקודות קצה של webhook, ושליחה חוזרת של אירועים.

מניעת כפילויות לפי מזהה משלכם

מפתחות אידמפוטנטיות מגנים על ניסיונות חוזרים של בקשה אחת. כדי לוודא שאובייקט עסקי יישלח רק פעם אחת, שולחים גם מזהה משלכם ואת dedupeOn:

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

אם כבר קיימת מעטפה עם ה-externalId הזה (באותו מצב), POST /v1/envelopes מחזיר אותה עם 200 ו-x-deduplicated: true במקום ליצור מעטפה נוספת. זה תקף בין מפתחות, בין ימים ובין בקשות מקבילות.

הגבלות קצב

ל-API עם הזדהות (מפתחות API) אין כיום מגבלה קבועה על קצב הבקשות; השליחה מוגבלת לפי התוכנית שלכם. המגבלות חלות היכן שייתכן ניצול לרעה:

היכן	מגבלה
`POST /v1/public/verify`	60 בקשות בדקה לכל IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 בקשות בדקה לכל IP
`GET /v1/sso/discover`	30 בדיקות בדקה לכל IP
קודים חד-פעמיים לחותמים	5 קודים ב-15 דקות לכל סשן; 5 ניסיונות לכל קוד
שליחה חוזרת לנמען	פעם בדקה לכל נמען
קישורים קבועים	לכל קישור: `perEmailPerDay` (ברירת מחדל 3), `perIpPerHour` (ברירת מחדל 20), `dailyCap` אופציונלי
כניסה ללוח הבקרה עם סיסמה	10 בדקה לכל IP; 10 ב-15 דקות לכל כתובת אימייל
הרשמה ללוח הבקרה עם סיסמה	5 בדקה לכל IP; 5 בשעה לכל כתובת אימייל
אימיילים לאיפוס סיסמה	5 ב-15 דקות לכל IP; 3 בשעה לכל כתובת אימייל
קודי כניסה ללוח הבקרה	3 בדקה לכל IP

נקודות קצה ציבוריות מוגבלות שולחות את הכותרות RateLimit-Limit, RateLimit-Remaining ו-RateLimit-Reset (בשניות). מעבר למגבלה, ה-API עונה 429 עם בעיית rate-limited, בדרך כלל עם כותרת Retry-After בשניות.