المعجم

تُعرَّف المصطلحات كما يستخدمها الـ API. وحيث يكون للكلمة أيضًا معنى يومي أوسع، فالمعنى المعتمد هو معنى الـ API.

المعرّفات والمنتجات

المصطلح	المعنى
المعرّف	الشيء الواحد الذي يدور عليه فحص الوقت الفعلي: رقم هاتف واحد أو عنوان بريد إلكتروني واحد. والإرسال الجماعي يحمل قائمة منها.
series	ما إذا كان المعرّف `phone` أو `email`. فالمنتجات ونقاط النهاية والطلبات كلها خاصة بسلسلة، ولا يجوز للطلب أن يخلط السلاسل بأي معنى إلا بمعنى أنه يجب ألا يخلطها إطلاقًا.
المنتج	هدف فحص واحد — منصة، مع نوع الفحص المُجرى عليها. و”WhatsApp Number Checker” و”WhatsApp Activity Details” منتجان مختلفان، وإن كان كلاهما يتعلق بـ WhatsApp.
منتج الوقت الفعلي	منتج يُستخدم عبر نقاط النهاية المتزامنة. ويُعنون بـ ID الرقمي الخاص به.
منتج جماعي	منتج يُستخدم عبر نقاط النهاية غير المتزامنة. ويُعنون بـ slug الخاص به.
ID	العدد الصحيح الذي يحدد منتج وقت فعلي، ويُطبع كـ `#47` في الكتالوج. والمعرّفات هي ما يأخذه `product_ids`.
slug	السلسلة النصية التي تحدد منتجًا جماعيًا، مثل `waValid`. ومعرّفات slug هي ما يأخذه حقل `product`.
النمط	`realtime` أو `async`. والمنتج ينتمي إلى واحد فقط، والنمط يقرر أي نقاط نهاية تقبله.

لا يُحلّ ID وقت فعلي أبدًا على نقطة نهاية جماعية، ولا يُحلّ slug جماعي على نقطة نهاية وقت فعلي. وخلطهما هو خطأ التكامل الأكثر شيوعًا، ولا يحسمه أي من الجانبين بصمت — لكنهما يفشلان بطرق مختلفة، لأن الجانبين يتحققان بطريقتين مختلفتين:

يُتحقق من product_ids كمصفوفة من الأعداد الصحيحة، فيُرفض slug النصي بـ 400 invalid_realtime_request قبل حدوث أي بحث عن منتج.
يُبحث عن الحقل الجماعي product بـ slug، فيُعثر على slug منتج وقت فعلي — ثم يُرفض بـ 422 product_mode_not_supported، لأن نقاط النهاية غير المتزامنة لا تقبل إلا منتجات غير متزامنة.

الأحكام

المصطلح	المعنى
مسجّل	ما يجيب عنه الفحص فعلًا: هل هذا المعرّف مسجّل على هذه المنصة؟ وهو ليس بيانًا عن كون الرقم أو العنوان صحيحًا نحويًا، أو يمكن الوصول إليه، أو قيد الخدمة.
`valid`	مؤكَّد كمسجّل. محتسب.
`invalid`	مؤكَّد كغير مسجّل. محتسب — فالإجابة السلبية إجابة أيضًا.
`unknown`	لم يستطع المزوّد حسمه. غير محتسب؛ ومسترد.
مخزّن مؤقتًا	قُدِّم الحكم من واقعة مخزّنة بدلًا من سؤال مورّد. وإصابة الذاكرة المؤقتة تظل محتسبة.
التركيبة	طلب وقت فعلي واحد، ومعرّف واحد، والمنتجات من واحد إلى عشرة التي فُحص مقابلها. ويمكن أن تنجح التركيبة جزئيًا — راجع `partial_succeeded`.

الأموال

المصطلح	المعنى
الحجز	أخذ المبلغ مقدمًا قبل تنفيذ العمل. وكل إرسال يُحجز مقابل رصيد الحساب.
التسوية	تقرير الاحتساب النهائي لمدخل فردي بمجرد معرفة حكمه.
الاسترداد	إعادة المبلغ المحجوز لمدخل لم يُنتج حكمًا قابلاً للاستخدام.
billing_status	حقل لكل مدخل: `charged` أو `refunded`. اقرأ هذا بدلًا من الاستنتاج من حالة HTTP.
`total_reserved`	محجوز قبل تنفيذ العمل. ويساوي دائمًا `total_charged + total_refunded`.
`charged_amount`	صافي المبلغ المحتسب. و`refunded_amount` هو صافي المبلغ المسترد.

الطلبات والمهام

المصطلح	المعنى
`request_id`	UUID يحدد إرسالًا واحدًا للوقت الفعلي. اذكره في طلبات الدعم.
`task_id`	الرمز الذي يحدد إرسالًا جماعيًا واحدًا، ويُعاد عند الإرسال. وهو أيضًا المعامل `{token}` في مسار نقاط نهاية المهمة — قيمة واحدة، واسمان في التوثيق.
`Idempotency-Key`	ترويسة يوفّرها المستدعي، مطلوبة في نداءات الوقت الفعلي، وتجعل إعادة المحاولة آمنة: فالمفتاح نفسه مع الجسم نفسه يعيد النتيجة المخزّنة بدلًا من الاحتساب مرة أخرى.
الإعادة	جاءت الاستجابة من نتيجة مخزّنة لا من عمل جديد. `replayed` في استجابة الوقت الفعلي، و`idempotent_replay` في الإرسال الجماعي. والإعادة لا تحرّك أي مبلغ.
`recovery_pending`	المهمة الجماعية في قائمة الانتظار، لكن محاسبتها لا تزال قيد التسوية.

عدّادات المهمة

المصطلح	المعنى
`submitted`	الصفوف التي أرسلتها.
`prefiltered`	الصفوف المستبعدة قبل الفحص — أسطر مشوّهة مثلًا.
`deduped`	الصفوف المكررة المحذوفة.
`total`	الصفوف المفحوصة فعلًا: `submitted` ناقص `prefiltered` ناقص `deduped`.
`processed`	الصفوف التي أنهتها القناة المصدر حتى الآن.
`unknown_unprocessed`	الصفوف التي لم تُحسم أبدًا. وهذه هي التي تُسترد.

الحدود ومدة الاحتفاظ

المصطلح	المعنى
الحد لكل مفتاح	الميزانية المرتبطة بمفتاح API الخاص بك. وهذا هو ما يجب التخطيط عليه.
الحد لكل IP	سقف أخشن يتقاسمه كل مفتاح خلف عنوان واحد. وليس تحكمًا في الوصول.
مدة الاحتفاظ	مدة بقاء السجل. سجلات الوقت الفعلي ونتائج الإعادة: 30 يومًا. ملفات النتائج الجماعية: 7 أيام.