توثيق API — BulkChecker

المصادقة

تتطلب جميع نقاط النهاية مفتاح API داخل ترويسة الطلب.

http

X-API-Key: YOUR_API_KEY

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

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

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

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

GET /v1/balance

جلب الرصيد

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

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

json

{ "balance": "5.230000" }

POST /v1/detect

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

أرسل مصفوفة من أرقام الهاتف للفحص. تتم المعالجة بشكل غير متزامن. يتم خصم التكلفة مسبقا؛ والأرقام غير المفحوصة ترد تلقائيا.

من 1,000 إلى 2,000,000 رقم لكل طلب. أرسل رمز الدولة، مثل +8613800138000.

المعاملات

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

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

json

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

POST /v1/detect/file

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

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

المعاملات

Content-Type: multipart/form-data

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

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

json

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

GET /v1/tasks/{task_id}

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

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

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

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "whatsapp-active",
  "country": "CN",
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "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/{task_id}/result

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

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

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

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0
  }
}

رموز الأخطاء

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

HTTP	خطأ	الحل
401	Unauthenticated	تحقق من وجود ترويسة X-API-Key وصحتها.
402	Insufficient balance.	رصيد الحساب غير كاف. اشحن الرصيد ثم أعد المحاولة.
404	Not found	task_id غير موجود أو تابع لحساب آخر.
422	فشل التحقق من البيانات	تحقق من الحقول المطلوبة، تنسيق الأرقام، ونوع الملف.
429	Too Many Requests	Endpoints الفحص محدودة بـ 10 طلبات في الدقيقة.

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

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

اسم المنتج	Slug
فحص أرقام Amazon	`amazonValid`
فحص البريد الإلكتروني لـ Amazon	`amazonemailValid`
فحص أرقام Apple ID	`appleidValid`
فحص البريد الإلكتروني لـ Apple ID	`appleidEmailValid`
فحص أرقام BAND	`bandValid`
فحص أرقام Binance	`binanceValid`
فحص البريد الإلكتروني لـ Binance	`binanceEmailValid`
فحص أرقام CoinW	`coinwValid`
فحص البريد الإلكتروني لـ CoinW	`coinwEmailValid`
فحص أرقام Facebook	`fbValid`
فحص البريد الإلكتروني لـ Facebook	`fbemailValid`
استعلام HLR	`hlr-lookup`
فحص أرقام HTX	`htxValid`
فحص البريد الإلكتروني لـ HTX	`htxEmailValid`
فحص أرقام iMessage	`imessageValid`
فحص أرقام Instagram	`instagram`
فحص البريد الإلكتروني لـ Instagram	`insEmailValid`
فحص أرقام KuCoin	`kucoinValid`
فحص البريد الإلكتروني لـ KuCoin	`kucoin`
العمر والجنس في LINE	`lineGender`
فحص أرقام LINE	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
فحص أرقام Microsoft	`microsoftValid`
فحص أرقام RCS	`RCSValid`
فحص أرقام Signal	`signalValid`
فحص أرقام Snapchat	`snapchatValid`
ملف Telegram الكامل	`tgGender`
فحص أرقام Telegram	`tgValid`
فحص نشاط Telegram	`tgActive`
البحث عن اسم مستخدم TikTok	`tkUsername`
فحص أرقام Viber	`viberValid`
فحص نشاط Viber	`viberActive`
ملف WhatsApp الكامل	`wsGender`
فحص أرقام WhatsApp	`wsValid`
فحص نشاط WhatsApp	`wsActive`
العمر والجنس في Zalo	`zaloGender`
فحص أرقام Zalo	`zaloValid`
تصفية نشاط الإنترنت	`internet-activity-filter`
فحص حالة الرقم	`phone-status-check`
فحص طراز الهاتف	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

أمثلة كاملة

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

1. جلب الرصيد

bash

curl -X GET "https://api.bulkchecker.io/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"

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

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "whatsapp-active",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. رفع ملف

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "product=whatsapp-active" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

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

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_API_KEY"

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

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_API_KEY"