بيانات الأرقام في تطبيقك.

01 / مرجع API

متابعة توفر الأرقام من مصدر واحد

تعرض واجهة حالة الأرقام بيانات الأرقام المجانية العامة وأرقام الأعضاء المدرجة في الموقع. يمكنك استخدامها لبناء دليل أرقام، أو اختيار دولة وتطبيق، أو متابعة الأرقام النشطة.

02 / البدء السريع

أرسل أول طلب

تواصل مع إدارة الموقع لطلب API token. بعد الموافقة على الوصول، استبدل YOUR_API_TOKEN في المثال أو اضبط متغير RECEIVE_SMS_API_TOKEN على خادمك.

curl --get 'https://receive-smss.live/api/public/numbers' \
  --header 'X-API-Key: YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'access=public' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'

// Server-side JavaScript (Node.js). Keep the token on your server.
const token = process.env.RECEIVE_SMS_API_TOKEN;
if (!token) throw new Error('Set RECEIVE_SMS_API_TOKEN first');

const url = new URL('https://receive-smss.live/api/public/numbers');
url.search = new URLSearchParams({
  status: 'active', access: 'public', limit: '20', offset: '0'
}).toString();

const response = await fetch(url, {
  headers: { 'X-API-Key': token, Accept: 'application/json' },
  signal: AbortSignal.timeout(10000)
});

if (!response.ok) {
  throw new Error('API request failed: HTTP ' + response.status);
}

const data = await response.json();
console.log(data.numbers);

# Python 3 standard library. Keep the token on your server.
import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({
    'status': 'active', 'access': 'public', 'limit': 20, 'offset': 0
})
request = Request(
    'https://receive-smss.live/api/public/numbers?' + query,
    headers={
        'X-API-Key': os.environ['RECEIVE_SMS_API_TOKEN'],
        'Accept': 'application/json',
    },
)

try:
    with urlopen(request, timeout=10) as response:
        data = json.load(response)
    print(data['numbers'])
except HTTPError as error:
    raise RuntimeError('API request failed: HTTP ' + str(error.code)) from error
except URLError as error:
    raise RuntimeError('Could not reach the API') from error

الأمثلة للشرح. هذه الصفحة لا ترسل طلبات API ولا تنشئ رموز وصول.

03 / المصادقة

استخدم API token للمصادقة

أرسل الرمز الذي تحصل عليه من الإدارة في ترويسة X-API-Key. رمز API منفصل عن كلمة مرور حسابك وجلسة تسجيل الدخول إلى الموقع.

X-API-Key: YOUR_API_TOKEN
Accept: application/json

إذا كان برنامجك يستخدم ترويسة Bearer، أرسل الرمز نفسه بالطريقة التالية. الرمز مفتاح API وليس رمز OAuth. عند إرسال الترويستين، تكون الأولوية لترويسة X-API-Key.

Authorization: Bearer YOUR_API_TOKEN

04 / عرض الأرقام

اعرض الأرقام وحالتها

يعيد الطلب بيانات الأرقام المطابقة وإجمالي النتائج ومعلومات تقسيمها. جميع معاملات البحث اختيارية، ويمكن دمجها لتحديد النتائج المطلوبة.

القيم غير المعروفة في status أو access تعيد الفلتر إلى all. تُضبط القيم الرقمية ضمن النطاق المسموح. إذا لم توجد نتائج للدولة أو التطبيق، تعود مصفوفة numbers فارغة.

05 / صيغة الاستجابة

اقرأ الاستجابة

البيانات التالية افتراضية لتوضيح بنية الاستجابة. لا تمثل مخزون الموقع الحالي أو رقم هاتف متاحًا للاستخدام.

{
  "success": true,
  "generatedAt": "2026-10-29T12:00:00.000Z",
  "filters": {
    "status": "active",
    "access": "public",
    "country": null,
    "app": null
  },
  "counts": {
    "total": 1,
    "active": 1,
    "inactive": 0,
    "returned": 1
  },
  "paging": {
    "limit": 20,
    "offset": 0,
    "hasMore": false
  },
  "numbers": [
    {
      "number": "+12025550123",
      "status": "active",
      "access": "public",
      "type": "mobile",
      "country": {
        "code": "US",
        "slug": "usa",
        "name": "United States",
        "nameAr": "الولايات المتحدة",
        "phoneCode": "+1"
      },
      "region": null,
      "apps": [
        "whatsapp"
      ],
      "receivedCount": 12,
      "lastMessageAt": "2026-10-29T11:58:00.000Z",
      "url": "https://receive-smss.live/sms/usa/12025550123",
      "addedAt": "2026-10-01T09:00:00.000Z",
      "updatedAt": "2026-10-29T11:58:00.000Z"
    }
  ]
}

06 / تقسيم النتائج

انتقل إلى الدفعة التالية

ابدأ بقيمة offset=0. إذا كانت paging.hasMore تساوي true، زِد offset بمقدار counts.returned مع إبقاء الفلاتر نفسها. توقف عندما تصبح hasMore بقيمة false. قد يتغير المخزون بين الطلبات؛ احذف الأرقام المكررة عند تجميع عدة دفعات.

// Keep the same filters and page size on every request.
// After each successful response:
if (data.paging.hasMore) {
  const nextOffset = data.paging.offset + data.counts.returned;
  // Use nextOffset as the offset parameter for the next page.
}

07 / حدود الطلبات

التزم بحد الطلبات

تشترك الطلبات الصادرة من عنوان IP واحد في الحد نفسه. تتضمن استجابة 429 ترويسة Retry-After: 60. انتظر قبل المحاولة مجددًا، وتجنب تشغيل حلقات متابعة متوازية.

يمكن تخزين الاستجابة الناجحة مؤقتًا لمدة 30 ثانية، مع مهلة stale-while-revalidate تبلغ 60 ثانية. راعِ هذا التأخير عند عرض الحالة. تكرار الاستعلام لا يسرّع وصول رسائل SMS.

08 / الأخطاء

تعامل مع الأخطاء حسب حالة HTTP

{
  "success": false,
  "error": "Invalid API key."
}

09 / إرشادات الربط

اضبط الربط على خادمك

10 / الأسئلة الشائعة

قبل بدء الربط