فحص رقم واحد لحظيًا

POST/v1/realtime/check/phone

فحص متزامن لرقم هاتف واحد. يمكن للطلب اختيار عدة منتجات لحظية بواسطة المعرّف، ولا تُستخدم معرفات slug للمنتجات الدفعية.

Idempotency-Key

يجب إرسال Idempotency-Key. إعادة الطلب نفسه بالمفتاح نفسه لا تخصم الرسوم مرتين، وتغيير المحتوى يعيد 409. تشير cached=true إلى نتيجة معاد استخدامها.

المعاملات

الحقل	النوع	مطلوب	الوصف
identifier	string	نعم	رقم هاتف واحد بصيغة E.164، مثل +8613800138000.
country	string	لا	اختياري مع رقم E.164 كامل؛ الرقم المحلي يحتاج رمز دولة ISO مطابقًا. — رموز الدول
product_ids	array	نعم	مصفوفة من 1 إلى 10 معرّفات لمنتجات لحظية.

اختيار المنتجات المراد فحصها

لا تخمّن معرّفات المنتجات: اقرأ id للعنصر الذي تكون فيه mode مساوية لـ realtime من GET /v1/products. أما منتجات الدفعات فتُعنون بـ slug، لذا لا يعمل الـ slug على هذا المسار أبدًا. وتعرض صفحة قائمة المنتجات معرّفات الوقت الفعلي ببادئة # لهذا السبب تحديدًا.

قائمة المنتجات

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

مثال الاستجابة

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    },
    {
      "product_id": 50,
      "product": "tgValid-rt",
      "result": "invalid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:01Z",
      "error_code": null
    }
  ]
}

حقول الاستجابة

الحقل	النوع	الوصف
request_id	string (UUID)	معرّف UUID لهذا الإرسال. اذكره في طلبات الدعم.
identifier	string	المُعرّف الذي جرى فحصه، معادًا كما هو.
series	string	phone أو email.
status	string	succeeded أو partial_succeeded أو failed — مشتقة من عدد النتائج المحتسبة.
request_status	string	حالة دورة الحياة الداخلية للطلب.
total_reserved	number	المبلغ المحجوز قبل تنفيذ الفحوص.
total_charged	number	إجمالي المبلغ المحتسب عن كل منتج في التركيبة.
total_refunded	number	إجمالي المبلغ المسترد عن العناصر التي تعذّر حسمها.
charged_amount	number	صافي المبلغ المحتسب. يساوي دائمًا total_charged.
refunded_amount	number	صافي المبلغ المسترد. يساوي دائمًا total_refunded.
replayed	boolean	true عند إعادة استخدام Idempotency-Key وإرجاع نتيجة مخزّنة.
results	array	عنصر واحد لكل منتج مطلوب، بالترتيب الذي طُلبت به المنتجات.

results[]

الحقل	النوع	الوصف
product_id	integer	معرّف منتج الفوري من الكتالوج.
product	string	المُعرّف النصي للمنتج الذي يُحلّ إليه ذلك المعرّف.
result	string	valid أو invalid أو unknown — ما إذا كان المُعرّف مسجّلًا.
cached	boolean	true عندما يأتي الحكم من الذاكرة المؤقتة. وإصابة الذاكرة المؤقتة تظل محتسبة.
billing_status	string	charged أو refunded.
charged_amount	number	المبلغ المخصوم لهذا المنتج.
refunded_amount	number	المبلغ المسترد لهذا المنتج.
checked_at	string (ISO 8601)	وقت إنتاج الحكم، بتوقيت UTC.
error_code	string | null	سبب تعذّر حسم العنصر، أو null عند نجاحه.

مثال cURL

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47,50]}'

الفوترة والدلالات

يستخدم كل منتج سعر الفحص المثبت للطلب، بما في ذلك نتائج التخزين المؤقت. تُحتسب valid وinvalid فقط، وتُرد رسوم unknown والمهلة والعناصر المشغولة.

يعيد النجاح الجزئي HTTP 200 مع status=partial_succeeded، والفشل الكامل status=failed. افحص billing_status وerror_code لكل عنصر.

الحد الأقصى لـ Idempotency-Key هو 191 بايت ويطبق لكل مستخدم. بعد انتهاء المهلة أو خطأ 500، أعد المحتوى الأصلي بالمفتاح نفسه. تحفظ النتائج 30 يومًا افتراضيًا.

يوضح error_code أخطاء المزود أو سعة القناة أو المهلة أو التخزين المؤقت أو حماية التزامن. العناصر الفاشلة بلا رسوم.

خطأ

نقاط النهاية	المعنى / الإجراء
400	صحح الرقم أو المنتجات أو المفتاح؛ لم يحدث حجز.
401	تحقق من المفتاح وحالة الحساب وصلاحية الوصول؛ لم يحدث حجز.
402	الرصيد غير كافٍ؛ لن يبدأ أي عنصر.
409	أعد المحاولة وفق Retry-After؛ لا يمكن استخدام المفتاح مع محتوى مختلف.
429	انتظر وفق Retry-After؛ لم يحدث حجز.
500	النتيجة غير مؤكدة. أعد المحاولة بالمفتاح الأصلي ولا تنشئ مفتاحًا جديدًا.
503	المسار أو التخزين المؤقت أو محدد السرعة غير متاح؛ حاول لاحقًا.