توثيق API

المصادقة

تتطلب جميع نقاط النهاية مفتاح API داخل ترويسة الطلب. The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

يتكوّن مفتاحك من 51 حرفًا: البادئة zn_ متبوعة بـ 48 حرفًا عشوائيًا. المفاتيح الصادرة سابقًا بالبادئة ck_ تظل صالحة للاستخدام.

يتوفر مفتاح API في لوحة التحكم ضمن "API Center". يظهر المفتاح النصي مرة واحدة فقط عند الإنشاء؛ احفظه فورا.

تنسيق الاستجابة

تعيد جميع نقاط النهاية JSON.

مثال على استجابة فورية

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

مثال على استجابة دفعة

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

جلب الرصيد

يعيد رصيد USD الحالي للحساب الموثق.

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

json

{ "balance": "5.230000" }

GET /v1/products

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

فهرس المنتجات العام؛ لا يتطلب مفتاح API. يعرض المنتجات الفورية ومنتجات الدفعات المفعّلة، وسلاسلها، والحد الأدنى للكميات. اقرأه قبل الإرسال.

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

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

تفاصيل مفتاح API

يعرض البيانات الوصفية لمفتاح API الخاص بالحساب الموثّق. لا يُعاد المفتاح بنصه الصريح.

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

يُعرض المفتاح بنصه الصريح مرة واحدة عند إنشائه أو تدويره؛ يعرض هذا الطرف قيمة مقنّعة فقط.

رموز الأخطاء

عند الفشل، تحقق من رمز حالة HTTP وحقل message.

جسم الخطأ

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

أخطاء الأعمال تُرجع دائماً رمزاً (code) قابلاً للقراءة آلياً لتتمكن من التفرع برمجياً. أما المعاملات غير الصالحة (التحقق) والمسارات غير الموجودة فتُرجع بنية Laravel القياسية: { "message": "...", "errors": { ... } }. تحقق من المدخلات قبل الإرسال.

خطأ

code	HTTP	الوصف
unauthorized	401	مفتاح API مفقود أو غير صالح أو معطّل.
account_banned	403	الحساب موقوف. تواصل مع الدعم.
invalid_realtime_request	400	طلب فوري غير صالح (مثل رقم هاتف بدون بادئة دولية + عند ترك country فارغاً).
idempotency_key_required	400	الطلبات الفورية تتطلب الترويسة Idempotency-Key.
invalid_idempotency_key	422	معرّف Idempotency-Key غير صالح: من 1 إلى 128 حرفاً من الحروف والأرقام و . _ : -
idempotency_conflict	409	استُخدم نفس المعرّف مع محتوى طلب مختلف.
request_in_progress	409	طلب فوري مطابق قيد المعالجة حالياً. أعد المحاولة بعد قليل (Retry-After: 1).
empty_input	422	الملف المرفوع لا يحتوي على صفوف قابلة للاستخدام.
product_not_found	422	المعرّف الفريد للمنتج غير موجود أو غير مفعّل.
product_mode_not_supported	422	نقطة النهاية هذه لا تقبل هذا النمط من المنتجات (منتجات الفحص الفوري لا تُرسل إلى نقاط المعالجة الجماهيرية).
invalid_country	422	المنتج لا يدعم الدولة المرسلة.
too_few_numbers	422	الإرسال أقل من الحد الأدنى للمنتج.
too_many_numbers	422	الإرسال يتجاوز الحد الأقصى للمنصة.
insufficient_balance	402	الرصيد غير كافٍ. اشحن ثم أعد المحاولة.
realtime_disabled	403	الفحص الفوري غير مفعّل لهذا الحساب.
realtime_rate_limited	429	تجاوزت حد معدل الطلبات الفورية. التزم بـ retry_after.
product_pricing_unavailable	503	لم يتم ضبط أسعار هذا المنتج بعد. تواصل مع الدعم.
detection_capacity_unavailable	503	لا توجد سعة فحص متاحة حالياً. أعد المحاولة لاحقاً.
realtime_route_unavailable	503	لا يوجد مسار فوري متاح. أعد المحاولة لاحقاً.
realtime_fact_cache_unavailable	503	إحدى خدمات الفحص الفوري غير متاحة مؤقتاً. أعد المحاولة لاحقاً.
realtime_rate_limiter_unavailable	503	محدد المعدل غير متاح مؤقتاً. أعد المحاولة لاحقاً.
not_found	404	task_id غير موجود أو تابع لحساب آخر.
result_not_ready	422	المهمة غير مكتملة أو لم يُنشأ ملف النتيجة.
result_expired	404	ملف النتيجة منتهي أو مفقود أو غير متاح.
validation_failed	422	تحقق من الحقول المطلوبة، تنسيق الأرقام، ونوع الملف.
internal_error	500	خطأ داخلي في الخادم. إعادة المحاولة بنفس المعرّف آمنة.

حدود المعدل

تُحدَّد طلبات واجهة API لكل مفتاح ولكل مجموعة نقاط نهاية:

نقاط النهاية	الحد
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 طلباً / دقيقة لكل مفتاح API (120 / دقيقة لكل IP)
نقاط النهاية: POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	10 طلبات / دقيقة لكل مفتاح API (30 / دقيقة لكل IP)
نقاط النهاية: POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	حاوية رموز لكل مفتاح API: الدفعة 60، إعادة التعبئة 1/ثانية (≈60 / دقيقة بشكل مستمر)؛ لكل حساب: الدفعة 120، إعادة التعبئة 2/ثانية. طبقة IP تسمح بـ 180 / دقيقة. كل استجابة تحمل الترويسة X-RateLimit-Remaining.

عند تجاوز الحد تُرجع الواجهة 429 مع ترويسة Retry-After (وتتضمن الاستجابات الفورية أيضاً حقلاً باسم retry_after). توقف الطلبات للعدد المذكور من الثوانٍ ثم استأنف بتراجع أُسّي.

POST /v1/realtime/check/{series}

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

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

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

المعاملات

الحقل	النوع	مطلوب	الوصف
series	path	نعم	السلسلة: phone أو email؛ يجب أن تطابق سلسلة منتج الوقت الفعلي المحدد.
identifier	string	نعم	معرّف واحد: رقم هاتف بصيغة E.164 أو عنوان بريد إلكتروني صالح.
country	string	لا	للهاتف فقط: اختياري مع رقم E.164 كامل؛ الرقم المحلي يحتاج رمز دولة ISO مطابقًا. اتركه فارغًا للبريد الإلكتروني.
product_ids	array<int>	نعم	مصفوفة من 1 إلى 10 معرّفات لمنتجات لحظية.

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

json

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

مثال cURL

bash

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":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

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

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

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

HTTP	code	المعنى / الإجراء
400	invalid_realtime_request / idempotency_key_required	صحح الرقم أو المنتجات أو المفتاح؛ لم يحدث حجز.
401 / 403	unauthorized / account_banned / realtime_disabled	تحقق من المفتاح وحالة الحساب وصلاحية الوصول؛ لم يحدث حجز.
402	insufficient_balance	الرصيد غير كافٍ؛ لن يبدأ أي عنصر.
409	request_in_progress / idempotency_conflict	أعد المحاولة وفق Retry-After؛ لا يمكن استخدام المفتاح مع محتوى مختلف.
429	realtime_rate_limited	انتظر وفق Retry-After؛ لم يحدث حجز.
503	realtime_route_unavailable / realtime_fact_cache_unavailable / realtime_rate_limiter_unavailable	المسار أو التخزين المؤقت أو محدد السرعة غير متاح؛ حاول لاحقًا.
500	internal_error	النتيجة غير مؤكدة. أعد المحاولة بالمفتاح الأصلي ولا تنشئ مفتاحًا جديدًا.

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

يُحتفظ مؤقتًا بالطرف POST /v1/realtime/detect للتوافق مع العملاء القدامى. يجب أن تستخدم التكاملات الجديدة /v1/realtime/check/phone أو /v1/realtime/check/email.

قائمة المنتجات · فردي (لحظي)

تُختار المنتجات الفورية عبر معرّف المنتج والسلسلة؛ لا تستخدم معرّفات منتجات الدفعات.

اسم المنتج	Series	المعرّف	الحد الأدنى
التحقق من رقم Amazon	`phone`	`#53`	1
التحقق من بريد Amazon الإلكتروني	`email`	`#54`	1
التحقق من رقم Apple ID	`phone`	`#57`	1
التحقق من بريد Apple ID الإلكتروني	`email`	`#58`	1
التحقق من رقم BAND	`phone`	`#60`	1
التحقق من رقم Facebook	`phone`	`#51`	1
التحقق من بريد Facebook الإلكتروني	`email`	`#52`	1
التحقق من رقم Instagram	`phone`	`#48`	1
التحقق من بريد Instagram الإلكتروني	`email`	`#49`	1
التحقق من رقم Microsoft	`phone`	`#59`	1
التحقق من رقم Telegram	`phone`	`#50`	1
التحقق من رقم Viber	`phone`	`#55`	1
التحقق من رقم WhatsApp	`phone`	`#47`	1
التحقق من رقم الهاتف على X	`phone`	`#61`	1

POST /v1/detect

إرسال فحص (مصفوفة)

أرسل مصفوفة من أرقام الهاتف أو البريد الإلكتروني للفحص الجماعي غير المتزامن. تُحجز التكلفة مسبقاً وتُرد العناصر غير المعالجة.

يحدد المنتج الحد الأدنى والحد الأقصى للمنصة هو 2,000,000. احذف country للبريد الإلكتروني؛ وهو مطلوب للهاتف.

HTTP 202 Accepted

المعاملات

الحقل	النوع	مطلوب	الوصف
product	string	نعم	Slug المنتج. راجع قائمة المنتجات.
country	string	مطلوب للهاتف؛ يُحذف للبريد الإلكتروني	رمز دولة ISO 3166-1 من حرفين. مطلوب للهاتف ويُحذف للبريد الإلكتروني.
phones	array	نعم	مصفوفة هواتف أو عناوين بريد؛ يحدد المنتج الحد الأدنى والحد الأقصى 2,000,000.

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

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "idempotent_replay": false,
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

إرسال فحص (رفع ملف)

ارفع ملف TXT أو CSV للفحص الجماعي، هاتف أو بريد إلكتروني واحد في كل سطر، بحد أقصى 50 MB.

HTTP 202 Accepted

المعاملات

Content-Type: multipart/form-data

الحقل	النوع	مطلوب	الوصف
product	string	نعم	Slug المنتج
country	string	مطلوب للهاتف؛ يُحذف للبريد الإلكتروني	رمز دولة ISO للهاتف؛ يُحذف للبريد الإلكتروني.
file	file	نعم	ملف TXT أو CSV، هاتف أو بريد إلكتروني واحد في كل سطر، بحد أقصى 50 MB.

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

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "idempotent_replay": false,
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{token}

جلب حالة المهمة

استعلم عن المهمة حتى تصبح مكتملة أو فاشلة. الفاصل الموصى به: 3–5 ثوان.

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

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

حالة المهمة

status	الوصف
pending	في الصف، بانتظار الموارد.
processing	الفحص قيد التنفيذ.
completed	اكتمل الفحص. النتيجة جاهزة للتنزيل.
failed	فشل التنفيذ.

GET /v1/tasks/{token}/result

جلب رابط التنزيل

بعد الاكتمال، احصل على رابط تنزيل ملف النتائج. تحفظ الملفات افتراضيا لمدة 7 أيام (حسب إعداد النظام result_retention_days).

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

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

تنزيل النتيجة

ينزّل ملف نتيجة مهمة مكتملة ما دام ضمن فترة الاحتفاظ.

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

Content-Type: application/zip (or text/csv for a single result).

يعيد هذا الطرف ملفًا بدل JSON. يعيد 404/422 عندما لا تكون المهمة جاهزة أو منتهية أو غير متاحة أو تخص حسابًا آخر.

قائمة المنتجات · جماعي (غير متزامن)

استخدم قيمة slug في حقل product عند إرسال المهمة.

اسم المنتج	المعرّف	الحد الأدنى
التحقق من رقم Amazon	`amazonValid`	500
التحقق من بريد Amazon الإلكتروني	`amazonEmailValid`	1000
التحقق من رقم Apple ID	`appleidValid`	2000
التحقق من بريد Apple ID الإلكتروني	`appleidEmailValid`	1000
التحقق من رقم BAND	`bandValid`	500
التحقق من رقم Binance	`binanceValid`	2000
التحقق من بريد Binance الإلكتروني	`binanceEmailValid`	2000
التحقق من رقم CoinW	`coinwValid`	2000
التحقق من بريد CoinW الإلكتروني	`coinwEmailValid`	2000
التحقق من رقم Facebook	`fbValid`	500
التحقق من بريد Facebook الإلكتروني	`fbEmailValid`	1000
التحقق من رقم HTX	`htxValid`	1000
التحقق من بريد HTX الإلكتروني	`htxEmailValid`	2000
التحقق من رقم iMessage	`imessageValid`	2000
التحقق من رقم Instagram	`insValid`	500
التحقق من بريد Instagram الإلكتروني	`insEmailValid`	1000
التحقق من رقم KuCoin	`kucoinValid`	1000
التحقق من بريد KuCoin الإلكتروني	`kucoinEmailValid`	2000
العمر والجنس في LINE	`lineGender`	2000
التحقق من رقم LINE	`lineValid`	2000
الملف الكامل لـ Linkedin	`linkedinGender`	2000
التحقق من رقم Linkedin	`linkedinValid`	2000
التحقق من رقم Microsoft	`microsoftValid`	500
التحقق من دعم RCS	`rcsValid`	1000
التحقق من رقم Signal	`signalValid`	2000
التحقق من رقم Snapchat	`snapchatValid`	500
الملف الكامل لـ Telegram	`tgGender`	500
التحقق من رقم Telegram	`tgValid`	1000
فحص نشاط Telegram	`tgActive`	500
البحث عن اسم مستخدم TikTok	`tiktokUsername`	2000
التحقق من رقم Viber	`viberValid`	1000
فحص نشاط Viber	`viberActive`	1000
الملف الكامل لـ WhatsApp	`waGender`	1000
التحقق من رقم WhatsApp	`waValid`	1000
تفاصيل نشاط WhatsApp	`waActive`	500
التحقق من رقم الهاتف على X	`twitterValid`	2000
التحقق من بريد X الإلكتروني	`twitterEmailValid`	2000
العمر والجنس في Zalo	`zaloGender`	500
التحقق من رقم Zalo	`zaloValid`	2000
تصفية نشاط الإنترنت	`live-activity-filter`	2000
التحقق من حالة الرقم	`phone-status-check`	2000
حالة تشغيل الهاتف	`phone-onoff-check`	1500
فحص طراز الهاتف	`phone-model-detection`	500
استعلام HLR	`hlr-lookup`	2000

أمثلة كاملة

انسخ وشغل أمثلة cURL هذه — واستبدل YOUR_KEY_HERE والمعاملات.

1. جلب الرصيد

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

2. إرسال مهمة فحص

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. رفع ملف

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. الاستعلام عن حالة المهمة

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

5. جلب رابط التنزيل

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"