handelsregister.ai
تسجيل الدخول إنشاء حساب
التوثيق الحدود

الحدود

كم طلبًا يمكنك إرساله.

الطلبات في الدقيقة

تسمح كل نقطة نهاية بعدد ثابت من الطلبات في الدقيقة. لنقاط نهاية البيانات ولقراءة الحساب تُحتسب جميع مفاتيح الحساب ورموزه معًا. ويُحتسب كل طلب، حتى المرفوض.

نقطة النهاية
نقطة النهاية ماذا الحد في الدقيقة
fetch-organization ملف الشركة 60
fetch-person ملف الشخص 60
search-organizations البحث والتصدير 60
fetch-document المستندات 5
signals Signals 60
account قراءة الحساب 30
account, auth/tokens إدارة Bearer tokens؛ وإنشاء المفاتيح والمراقبات ونقاط نهاية webhook وتعديلها وحذفها 10
account/webhook-endpoints التحقق من نقطة نهاية webhook واختبارها، وتدوير السرّ 6

يتشارك البحث والمستندات وSignals حصة واحدة من 60 طلب في الدقيقة. وللمستندات أيضًا حد خاص أصغر.

طلبات الكتابة إلى الحساب وMonitoring وwebhooks تُحتسب أيضًا ضمن حد الحساب. الأرقام نفسها مذكورة تحت «التكاليف والحدود» في صفحة كل نقطة نهاية.

الحدود هي نفسها في كل اشتراك أرصدة. إذا احتجت إلى طلبات أكثر في الدقيقة، يمكن لـ عقد Enterprise أن يمنحك حدودًا أعلى.

بلوغ الحد

فوق الحد تجيب الـ API بـ 429. ويخبرك الـ Header ‏Retry-After بعد كم ثانية يمكنك إرسال الطلبات مجددًا. والرقم نفسه موجود في الحقل retry_after.

تُظهر كل استجابة في الـ Headers كم بقي لك من هامش:

الـ Header
الـ Header المعنى مثال
X-RateLimit-Limit حد نقطة النهاية هذه في الدقيقة. 30
X-RateLimit-Remaining كم طلبًا إضافيًا ممكنًا في هذه الدقيقة. 0
Retry-After فقط مع 429: الثواني حتى الطلب الممكن التالي. 17
X-RateLimit-Reset فقط مع 429: الوقت الذي يمكنك فيه المتابعة، كوقت Unix. 1793519682 
1{2  "error": "Too many requests",3  "message": "Rate limit exceeded. Retry after 17 seconds.",4  "retry_after": 175}
429 · مثال على استجابة فوق الحد

عندما ترسل طلبات كثيرة، راقب X-RateLimit-Remaining وأبطئ بنفسك قبل أن تجيب الـ API بـ 429. والطلب فوق الحد لا يكلّف شيئًا.

مهلات الانتظار

تصل معظم الاستجابات خلال ثوانٍ قليلة. أما وضع الذكاء الاصطناعي والميزة news وعمليات جلب الوقت الفعلي وfetch-person والمستندات فتستغرق وقتًا أطول، لأننا نجلب المستندات وبيانات الوقت الفعلي مباشرةً من السجل.

اضبط مهلة الانتظار في عميلك على 120 ثانية على الأقل، خصوصًا للوقت الفعلي وfetch-person والمستندات. فالمهلة القصيرة جدًا تلغي طلبات كانت على وشك الانتهاء.

للمستندات يوجد أيضًا async=true: تجيب الـ API فورًا بـ 202 وتجلب المستند في الخلفية، انظر fetch-document.

إذا لم يُجب مصدر البيانات في الوقت المناسب، تحصل على 408، وللمستندات 504 مع Retry-After. ولا يُحتسب شيء. أعد الطلب بعد قليل. وإذا فشل الجلب المباشر للوقت الفعلي وحده، تحصل على ملف الشركة بالبيانات المخزنة، دون رسوم الوقت الفعلي.

إعادة المحاولة دون احتساب مزدوج

إذا ألغى عميلك طلبًا، فقد يكتمل مع ذلك لدينا ويُحتسب. ومع الـ Header ‏Idempotency-Key لا تكلّف إعادة المحاولة حينها شيئًا.

اختر مفتاحًا منفصلًا لكل طلب وأرسله دون تغيير مع إعادة المحاولة. للمفتاح من 1 إلى 128 حرفًا: حروف وأرقام ونقطة وشرطة سفلية ونقطتان وشرطة، ويبدأ بحرف أو رقم.

طلب مع مفتاح idempotency 
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: hetzner-profile-2026-11-01" \
  --data-urlencode "q=Ansbach HRB 6089"
الحالة
الحالة نقاط نهاية البيانات Monitoring وwebhooks
المفتاح إلزامي لا، اختياري نعم، وإلا 428
النافذة الزمنية 24 ساعة 24 ساعة
المفتاح نفسه، المعاملات نفسها النتيجة مرة أخرى، دون احتساب الاستجابة المخزنة مع حالتها
المفتاح نفسه، معاملات مختلفة 422 idempotency_key_reused 409 idempotency_conflict
بعد خطأ يبقى المفتاح متاحًا يعود الخطأ نفسه، ويلزم مفتاح جديد

نقاط نهاية البيانات

تقبل fetch-organization وfetch-person وsearch-organizations وfetch-document المفتاح كخيار. إذا كررت طلبًا بالمفتاح نفسه والمعاملات نفسها خلال 24 ساعة، تحصل على النتيجة مرة أخرى، دون احتساب.

تحمل الاستجابة الأولى الـ Header ‏Idempotency-Status: created، وكل إعادة Idempotency-Status: replayed وmeta.request_credit_cost: 0. ولا تحتاج الإعادة إلى رصيد.

وحدها النتيجة المسلَّمة تربط المفتاح. لذا يمكنك بعد خطأ الاستمرار في استخدام المفتاح نفسه. والمفتاح نفسه مع معاملات مختلفة يعطي 422 مع idempotency_key_reused. وتتجاهل نقاط نهاية البيانات المفتاح بصيغة مختلفة، لذا التزم بالصيغة تمامًا. لا تقبل signals مفتاح idempotency. 

1{2  "error": "idempotency_key_reused",3  "message": "This Idempotency-Key was already used with different parameters.",4  "meta": {5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}
422 · مثال على استجابة: المفتاح نفسه مع معاملات مختلفة

Monitoring وwebhooks

طلبات الكتابة إلى /v1/account/monitors و/v1/account/webhook-endpoints و/v1/account/webhook-deliveries تحتاج إلى المفتاح. ودونه تجيب الـ API بـ 428؛ والمفتاح بصيغة خاطئة يعطي 400.

خلال 24 ساعة يُرجع المفتاح نفسه مع المعاملات نفسها الاستجابة المخزنة مع حالتها، إضافةً إلى Idempotency-Status: replayed. وينطبق ذلك أيضًا على الأخطاء. لذا لمحاولة جديدة، مثل التحقق مرة أخرى، تستخدم مفتاحًا جديدًا.

المفتاح نفسه مع معاملات مختلفة يعطي 409 مع idempotency_conflict. وإذا كان الطلب الأول لا يزال قيد التنفيذ، تحصل على 409 مع idempotency_in_progress.

خطّط لإعادة المحاولة

ليس كل خطأ يستحق محاولة ثانية. هكذا تتصرف:

  • أعد المحاولة: 408، و429 بعد Retry-After، و5xx. انتظر أطول بين المحاولات في كل مرة، مثلًا 2 و4 و8 ثوانٍ، وتوقف بعد بضع محاولات.
  • أصلح أولًا، ثم أعد الإرسال: 400 و401 و402 و403 و404 و422. إرسال الطلب نفسه مرة أخرى يجلب النتيجة نفسها.
  • أرسل مفتاح idempotency مع الطلبات المدفوعة. حينها لا تكلّف إعادة المحاولة بعد الإلغاء شيئًا.
الأخطاء جميع رموز الحالة وما يمكنك فعله. الفوترة ما تكلفة كل طلب ومتى لا يُحتسب شيء. إثراء بيانات العملاء جلب شركات كثيرة دفعة واحدة، مع الحدود وإعادة المحاولة.