حدود المعدل وعدم التكرار

عدم التكرار

أرسل الترويسة 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 بالثواني.