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

توفر واجهة برمجة التطبيقات (API) الخاصة بـ YallaSMS للمطورين طريقة برمجية للوصول إلى الأرقام الوهمية المتاحة واستقبال الرسائل النصية الواردة إليها. تم تصميم الـ API ليكون بسيطًا وسهل الاستخدام، مع الاعتماد على معايير REST القياسية واستخدام تنسيق JSON للطلبات والاستجابات.

سواء كنت تبني تطبيقًا يتطلب التحقق عبر الرسائل القصيرة، أو أداة تسويقية، أو تحتاج ببساطة إلى أتمتة عملية الحصول على الأرقام والرسائل، فإن واجهة برمجة التطبيقات هذه هي بوابتك لتحقيق ذلك.

عنوان URL الأساسي للـ API: https://yallasms.com/developers/v1.php

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

يمكنك الحصول على مفتاح API الخاص بك بعد التسجيل في لوحة تحكم المطورين (الرابط سيكون متاحًا هنا عند إطلاق الخدمة). حافظ على مفتاحك سريًا ولا تشاركه.

GET /v1/numbers HTTP/1.1
Host: api.yallasms.com
X-API-Key: YOUR_API_KEY_HERE
Accept: application/json
نسخ

سيؤدي عدم تضمين مفتاح API صالح إلى استجابة خطأ 401 Unauthorized.

فيما يلي وصف لنقاط النهاية المتاحة في الإصدار الحالي من الـ API.

[
  {
    "name": "السعودية",
    "code": "sa",
    "flag_url": "https://flagcdn.com/w40/sa.png"
  },
  {
    "name": "مصر",
    "code": "eg",
    "flag_url": "https://flagcdn.com/w40/eg.png"
  },
  {
    "name": "الولايات المتحدة",
    "code": "us",
    "flag_url": "https://flagcdn.com/w40/us.png"
  }
]نسخ

[
  {
    "number": "+966 55 123 4567",
    "full_number": "966551234567",
    "country_code": "sa",
    "last_message_at": 1678886400000,
    "is_online": true
  },
  {
    "number": "+966 50 987 6543",
    "full_number": "966509876543",
    "country_code": "sa",
    "last_message_at": 1678885000000,
    "is_online": true
  }
]نسخ

[
  {
    "id": "msg_12345abc",
    "from": "Facebook",
    "content": "123456 هو رمز Facebook الخاص بك",
    "received_at": 1678886450000
  },
  {
    "id": "msg_67890def",
    "from": "Google",
    "content": "G-987654 is your Google verification code.",
    "received_at": 1678886380000
  }
]نسخ

{
  "country_code": "us",
  "duration_minutes": 60 // Optional: how long the number should be reserved
}نسخ

{
  "number": "+1 202 555 0147",
  "full_number": "12025550147",
  "country_code": "us",
  "expires_at": 1678890000000
}نسخ

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

• 200 OK - تم تنفيذ الطلب بنجاح.
• 400 Bad Request - الطلب غير صحيح أو ينقصه معلمات مطلوبة.
• 401 Unauthorized - مفتاح API مفقود أو غير صالح.
• 403 Forbidden - ليس لديك الصلاحية للوصول إلى هذا المورد.
• 404 Not Found - المورد المطلوب (مثل رقم أو دولة) غير موجود.
• 429 Too Many Requests - لقد تجاوزت حد المعدل المسموح به للطلبات.
• 500 Internal Server Error - حدث خطأ غير متوقع في الخادم.

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

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}نسخ

لبدء استخدام واجهة برمجة التطبيقات، ستحتاج أولاً إلى الحصول على مفتاح API الخاص بك.

1. قم بزيارة لوحة تحكم المطورين (الرابط سيكون هنا).
2. أنشئ حسابًا أو سجل الدخول.
3. انتقل إلى قسم مفاتيح API وقم بإنشاء مفتاح جديد.
4. استخدم المفتاح في ترويسة X-API-Key في طلباتك.

استكشف نقاط النهاية