الكشف في الوقت الفعلي

يجيب الكشف في الوقت الفعلي عن سؤال واحد يخص معرّفًا واحدًا، فورًا: هل هذا الرقم — أو عنوان البريد الإلكتروني هذا — مسجّل على منصة معيّنة؟

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

متى تستخدمه

لديك	استخدم
معرّف واحد أو عدد قليل، وتحتاج الإجابة الآن	الوقت الفعلي
آلاف المعرّفات، ويمكنك الانتظار	الكشف الجماعي

الحالات المعتادة للوقت الفعلي هي التحقق من النماذج عند التسجيل أو الدفع، والاستعلامات الفردية داخل أداة داخلية، وعدد صغير من الفحوص داخل سير عمل قائم بالفعل. أما الجماعي فمصمّم للملفات والمصفوفات الكبيرة: فهو غير متزامن، ويُسعّر لكل صف يُفحص، ويمكن تنزيل المهام المكتملة.

سلسلتان، عقد واحد

تُحمل السلسلة في المسار، ويجب أن تتوافق مع المنتجات التي تختارها:

السلسلة	Endpoint	identifier
الهاتف	POST /v1/realtime/check/phone	رقم بصيغة E.164، على سبيل المثال +8613800138000
البريد الإلكتروني	POST /v1/realtime/check/email	عنوان بريد إلكتروني، على سبيل المثال user@example.com

لا يمكن للطلب أن يخلط بين السلسلتين: اختيار منتج هاتف ومنتج بريد إلكتروني في الطلب نفسه مرفوض. وcountry اختياري لرقم E.164 كامل، ويجب حذفه مع البريد الإلكتروني.

كيف يُحتسب الطلب الواحد

يأخذ الطلب الواحد معرّفًا واحدًا ومن منتج واحد إلى عشرة:

• request_id واحد للطلب
• مدخل واحد لكل منتج في results
• احتساب واحد لكل مدخل

لأن كل مدخل يُفاتر على حدة، يمكن أن ينجح الطلب مع بعض المنتجات ويفشل مع غيرها. ويُبلّغ عن ذلك بالحالة status: partial_succeeded، ويحمل كل مدخل billing_status الخاص به — اقرأها بدلًا من الاعتماد على HTTP 200 وحده.

صفحات هذا القسم

• فحص الهاتف في الوقت الفعلي — نقطة نهاية الهاتف كاملة
• فحص البريد الإلكتروني في الوقت الفعلي — نقطة نهاية البريد الإلكتروني كاملة
• منتجات الوقت الفعلي — القائمة الحيّة للمنتجات التي يمكنك اختيارها، وكيفية قراءة المعرّف منها
• عدم التكرار وإعادة المحاولة — لماذا يُشترط Idempotency-Key، وكيف تتصرّف عمليات إعادة المحاولة
• الفوترة والاسترداد — ما يُحتسب، وما يُسترد، ومتى
• أمثلة cURL / SDK — طلبات جاهزة للنسخ للحالات الشائعة

قبل إجراء أول طلب

1. احصل على مفتاح API — راجع المصادقة.
2. اقرأ معرّفات المنتجات التي تنوي استخدامها من منتجات الوقت الفعلي.
3. أرسل Idempotency-Key فريدًا مع كل طلب؛ فهو مطلوب وليس اختياريًا.