توثيق واجهة برمجة التطبيقات (API) - SMSArab

حالة الـ API: جاهز للعمل (الإصدار: 1.0 Stable)

مرحبًا بك في التوثيق الرسمي لواجهة برمجة تطبيقات SMSArab. يوفر هذا الـ API وصولاً برمجياً للحصول على أرقام هواتف افتراضية واستقبال رسائل SMS الواردة إليها.

عنوان URL الأساسي

جميع طلبات الـ API يجب أن توجه إلى عنوان URL الأساسي التالي:

https://api.smsarab.com

المصادقة (Authentication)

تتم المصادقة باستخدام مفتاح API يتم تمريره في ترويسة (Header) كل طلب.

يجب تضمين الترويسة التالية:

X-API-Key: YOUR_API_KEY

استبدل YOUR_API_KEY بمفتاح الـ API الخاص بك الذي تحصل عليه من لوحة التحكم (غير متوفر في هذه النسخة الوهمية).

نقاط النهاية (Endpoints)

الحصول على الأرقام المتاحة

GET /v1/numbers

يقوم بإرجاع قائمة بالأرقام الافتراضية المتاحة حاليًا للاستخدام.

المعاملات الاختيارية (Query Parameters):

المعامل النوع الوصف
country string فلترة الأرقام حسب رمز الدولة (مثال: 'US', 'GB', 'FR'). إذا لم يتم تحديده، يتم إرجاع أرقام من جميع الدول المتاحة.
limit integer عدد النتائج الأقصى لكل صفحة (الافتراضي: 20، الأقصى: 100).

مثال على الاستجابة (Success 200 OK):

{
  "status": "success",
  "data": [
    {
      "id": "num_abc123",
      "number": "+12025550123",
      "country_code": "US",
      "country_name": "United States",
      "is_active": true
    },
    {
      "id": "num_def456",
      "number": "+447700900123",
      "country_code": "GB",
      "country_name": "United Kingdom",
      "is_active": true
    }
    // ... more numbers
  ],
   "pagination": {
     "total": 50,
     "limit": 20,
     "next_cursor": "cursor_xyz"
   }
}

الحصول على الرسائل لرقم محدد

GET /v1/numbers/{number_id}/messages

يقوم بإرجاع قائمة برسائل SMS الواردة لرقم محدد عن طريق الـ ID الخاص به.

معاملات المسار (Path Parameters):

المعامل النوع الوصف
{number_id} string المعرف الفريد (ID) للرقم الذي تم الحصول عليه من نقطة النهاية /v1/numbers. (مطلوب)

المعاملات الاختيارية (Query Parameters):

المعامل النوع الوصف
since timestamp (ISO 8601) جلب الرسائل التي وصلت بعد هذا التاريخ والوقت.
limit integer عدد الرسائل الأقصى (الافتراضي: 50، الأقصى: 200).

مثال على الاستجابة (Success 200 OK):

{
  "status": "success",
  "data": [
    {
      "message_id": "msg_ghi789",
      "from_number": "Google", // Or the sender number
      "text": "رمز التحقق الخاص بك هو 123456",
      "received_at": "2024-05-21T10:30:00Z"
    },
    {
       "message_id": "msg_jkl012",
      "from_number": "Facebook",
      "text": "98765 هو كود فيسبوك الخاص بك",
      "received_at": "2024-05-21T10:25:00Z"
    }
     // ... more messages
  ]
}

التعامل مع الأخطاء

في حالة حدوث خطأ، سيقوم الـ API بإرجاع استجابة JSON تحتوي على وصف للخطأ ورمز الحالة المناسب (مثل 4xx أو 5xx).

مثال على استجابة خطأ (Error 404 Not Found):

{
  "status": "error",
  "error_code": "NOT_FOUND",
  "message": "Number with the specified ID was not found."
}

أمثلة برمجية

مثال باستخدام cURL (الحصول على الأرقام):

curl --request GET \
  --url 'https://api.smsarab.com/v1/numbers?country=US' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json'

مثال باستخدام Python (الحصول على الرسائل):

import requests

api_key = 'YOUR_API_KEY'
number_id = 'num_abc123'
base_url = 'https://api.smsarab.com'

headers = {
    'X-API-Key': api_key,
    'Accept': 'application/json'
}

response = requests.get(f'{base_url}/v1/numbers/{number_id}/messages', headers=headers)

if response.status_code == 200:
    messages = response.json()
    print(messages)
else:
    print(f'Error: {response.status_code} - {response.text}')