المطورون API

مقدمة

مرحبًا بك في مستندات واجهة برمجة التطبيقات (API) الخاصة بـ SMSArab. تتيح لك هذه الواجهة دمج خدمة الأرقام العربية الوهمية المؤقتة في تطبيقاتك ومشاريعك الخاصة برمجياً.

يمكنك استخدام الـ API الخاص بنا لطلب أرقام مؤقتة لدول وخدمات محددة، واستقبال رسائل SMS الواردة لهذه الأرقام بسهولة وسرعة.

عنوان URL الأساسي للـ API هو: https://api.smsarab.com

المصادقة

تتم المصادقة على جميع طلبات الـ API باستخدام مفتاح API فريد. يجب عليك تضمين مفتاح الـ API الخاص بك في كل طلب ضمن ترويسة (Header) HTTP باسم X-API-Key.

يمكنك الحصول على مفتاح الـ API الخاص بك من خلال الاتصال بنا عبر الموقع على Contact us .

مثال ترويسة الطلب:

X-API-Key: YOUR_PRIVATE_API_KEY_HERE

ملاحظة هامة: حافظ على سرية مفتاح الـ API الخاص بك ولا تشاركه أبداً. أي طلبات تتم باستخدام مفتاحك تعتبر مسؤوليتك.

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

GET /services

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

مثال الطلب (cURL):

curl -X GET "https://api.smsarab.com/v1/services" \
-H "X-API-Key: YOUR_API_KEY"

مثال الاستجابة (JSON):

{
  "success": true,
  "data": [
    {
      "country_code": "SA",
      "country_name": "السعودية",
      "available_services": [
        {"service_code": "whatsapp", "service_name": "WhatsApp", "cost": 0.5},
        {"service_code": "telegram", "service_name": "Telegram", "cost": 0.4},
        {"service_code": "facebook", "service_name": "Facebook", "cost": 0.3}
      ]
    },
    {
      "country_code": "EG",
      "country_name": "مصر",
      "available_services": [
        {"service_code": "whatsapp", "service_name": "WhatsApp", "cost": 0.4},
        {"service_code": "google", "service_name": "Google", "cost": 0.3}
      ]
    }
    // ... المزيد من الدول
  ]
}

POST /numbers

يطلب رقمًا وهميًا مؤقتًا لخدمة ودولة محددة.

معلمات الطلب (Request Body - JSON):

المعلم	النوع	الحالة	الوصف
`country_code`	String	مطلوب	رمز الدولة (مثل "SA", "EG").
`service_code`	String	مطلوب	رمز الخدمة (مثل "whatsapp", "facebook").

مثال الطلب (cURL):

curl -X POST "https://api.smsarab.com/v1/numbers" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "country_code": "SA",
  "service_code": "whatsapp"
}'

مثال الاستجابة (JSON - نجاح):

{
  "success": true,
  "data": {
    "activation_id": "1a2b3c4d5e",
    "phone_number": "+9665xxxxxxx",
    "country_code": "SA",
    "service_code": "whatsapp",
    "expires_at": "2024-08-01T12:10:00Z",
    "cost": 0.5
  }
}

مثال الاستجابة (JSON - خطأ):

{
  "success": false,
  "error": {
    "code": "NO_NUMBERS_AVAILABLE",
    "message": "لا توجد أرقام متاحة حالياً لهذه الخدمة في هذه الدولة."
  }
}

GET /messages/{activation_id}

يسترجع الرسائل النصية الواردة لرقم تم طلبه مسبقاً باستخدام معرف التفعيل (activation_id).

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

المعلم	النوع	الوصف
`activation_id`	String	معرف التفعيل الفريد الذي تم الحصول عليه عند طلب الرقم.

مثال الطلب (cURL):

curl -X GET "https://api.smsarab.com/v1/messages/1a2b3c4d5e" \
-H "X-API-Key: YOUR_API_KEY"

مثال الاستجابة (JSON - رسائل موجودة):

{
  "success": true,
  "data": {
    "status": "MESSAGES_RECEIVED", // أو "WAITING_FOR_MESSAGE"
    "messages": [
      {
        "sender": "WhatsApp",
        "text": "Your WhatsApp code is 123-456",
        "received_at": "2024-08-01T12:05:30Z"
      }
      // يمكن أن تكون هناك رسائل أخرى
    ]
  }
}

مثال الاستجابة (JSON - لا توجد رسائل بعد):

{
  "success": true,
  "data": {
    "status": "WAITING_FOR_MESSAGE",
    "messages": []
  }
}

POST /numbers/{activation_id}/cancel

يقوم بإلغاء تفعيل الرقم قبل انتهاء صلاحيته (اختياري، لتحرير الرقم مبكرًا).

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

المعلم	النوع	الوصف
`activation_id`	String	معرف التفعيل للرقم المراد إلغاؤه.

مثال الطلب (cURL):

curl -X POST "https://api.smsarab.com/v1/numbers/1a2b3c4d5e/cancel" \
-H "X-API-Key: YOUR_API_KEY"

مثال الاستجابة (JSON):

{
  "success": true,
  "message": "تم إلغاء تفعيل الرقم بنجاح."
}

GET /balance

يسترجع رصيد حسابك الحالي (إذا كانت الخدمة مدفوعة).

مثال الطلب (cURL):

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

مثال الاستجابة (JSON):

{
  "success": true,
  "data": {
    "balance": 45.75,
    "currency": "USD" // أو SAR, EGP, etc.
  }
}

حدود الاستخدام (Rate Limiting)

لحماية مواردنا وضمان جودة الخدمة للجميع، نطبق حدودًا على عدد الطلبات التي يمكنك إجراؤها خلال فترة زمنية معينة.

الحد العام: 120 طلبًا في الدقيقة لكل مفتاح API.
حد طلب الأرقام: 10 طلبات في الدقيقة لنقطة النهاية POST /numbers.

إذا تجاوزت هذه الحدود، ستتلقى استجابة بالخطأ 429 Too Many Requests. يمكنك التحقق من الترويسات (Headers) التالية في الاستجابة لمعرفة حالة الحد الحالي:

X-RateLimit-Limit: الحد الأقصى لعدد الطلبات المسموح به في الفترة الزمنية.
X-RateLimit-Remaining: عدد الطلبات المتبقية في الفترة الحالية.
X-RateLimit-Reset: وقت إعادة تعيين الحد (بتوقيت Unix timestamp).

معالجة الأخطاء

تستخدم واجهة برمجة التطبيقات (API) رموز حالة HTTP القياسية للإشارة إلى نجاح أو فشل الطلب.

2xx: تشير إلى النجاح.
4xx: تشير إلى خطأ من جانب العميل (مثل طلب غير صحيح، مصادقة فاشلة، تجاوز الحد).
5xx: تشير إلى خطأ من جانب الخادم (نادر، يرجى المحاولة مرة أخرى أو الاتصال بالدعم).

في حالة حدوث خطأ (4xx أو 5xx)، غالبًا ما تحتوي الاستجابة على كائن JSON يوفر تفاصيل إضافية حول الخطأ:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY", // مثال لرمز الخطأ
    "message": "مفتاح API المقدم غير صالح أو مفقود." // مثال لرسالة الخطأ
  }
}

رموز الحالة الشائعة:

الرمز	الوصف
`200 OK`	تم تنفيذ الطلب بنجاح.
`201 Created`	تم إنشاء المورد بنجاح (مثلاً عند طلب رقم جديد).
`400 Bad Request`	الطلب غير صحيح أو يحتوي على معلمات مفقودة/غير صالحة.
`401 Unauthorized`	المصادقة فاشلة (مفتاح API غير صالح أو مفقود).
`404 Not Found`	المورد المطلوب (مثل activation_id) غير موجود.
`429 Too Many Requests`	تم تجاوز حد الطلبات المسموح به.
`500 Internal Server Error`	حدث خطأ غير متوقع في الخادم.

أمثلة برمجية

مثال باستخدام PHP (cURL)

مثال لطلب رقم واتساب سعودي باستخدام PHP و cURL.

 'SA',
    'service_code' => 'whatsapp'
]);

$ch = curl_init($apiUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey,
    'Content-Length: ' . strlen($data)
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['success']) {
    echo "تم طلب الرقم بنجاح:\n";
    print_r($result['data']);
} else {
    echo "حدث خطأ:\n";
    if(isset($result['error'])) {
        print_r($result['error']);
    } else {
        echo "HTTP Code: " . $httpCode . "\n";
        echo "Response: " . $response . "\n";
    }
}

?>

مثال باستخدام Python (requests)

مثال للحصول على الرسائل لرقم معين باستخدام Python ومكتبة requests.

import requests
import json

api_key = "YOUR_API_KEY"
activation_id = "1a2b3c4d5e" # استبدل بالمعرف الصحيح
api_url = f"https://api.smsarab.com/v1/messages/{activation_id}"

headers = {
    "X-API-Key": api_key
}

try:
    response = requests.get(api_url, headers=headers)
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()

    if result.get("success"):
        print("الاستجابة:")
        print(json.dumps(result.get("data"), indent=2, ensure_ascii=False))
    else:
        print("فشل الطلب:")
        print(json.dumps(result.get("error"), indent=2, ensure_ascii=False))

except requests.exceptions.RequestException as e:
    print(f"حدث خطأ في الاتصال: {e}")
except json.JSONDecodeError:
    print(f"استجابة غير صالحة (ليست JSON): {response.text}")