بوابة المطورين والتكامل البرمجي

مرحباً بك في التوثيق الرسمي لواجهة YallaSMS البرمجية. صُممت بنيتنا التحتية بمعايير المؤسسات الكبرى (Enterprise Grade) لضمان أعلى مستويات الاستقرار، الأمان، والسرعة الفائقة لدمج خدمة استقبال رسائل SMS والأرقام الوهمية في أنظمتك.

ابدأ التكامل الآن

مقدمة معمارية النظام

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

  • صيغة البيانات: يتم إرسال واستقبال جميع البيانات بتنسيق application/json النظيف.
  • التوافق: تدعم الواجهة التكامل مع كافة لغات البرمجة الحديثة (Java, PHP, Python, Node.js, C# وغيرها).
  • الترميز: تدعم الـ API معيار UTF-8 بالكامل لضمان قراءة نصوص الرسائل والرموز بشكل صحيح.
رابط الخادم الأساسي (Base URL):
https://api.yallasms.com/v1

المصادقة وحماية الطلبات

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

تحذير أمني: لا تقم بمشاركة مفتاح API الخاص بك مطلقاً، ولا تضعه في أكواد الواجهة الأمامية (Client-Side Javascript) المكشوفة.

HTTP Header Example 
GET /v1/account/balance HTTP/1.1
Host: api.yallasms.com
X-API-Key: ylsms_live_8f9a2b4c6d8e...
Accept: application/json

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

GET /account/balance

الاستعلام عن الرصيد وحالة الحساب

تقوم هذه الدالة بإرجاع رصيدك الحالي المتوفر في المحفظة بالإضافة إلى عملة الحساب.

JSON Response 
{
  "status": "success",
  "data": {
    "balance": 150.75,
    "currency": "USD",
    "account_status": "active"
  }
}
GET /countries

استعلام عن الدول المتاحة

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

JSON Response 
[
  {
    "name_ar": "السعودية",
    "name_en": "Saudi Arabia",
    "country_code": "SA",
    "dial_code": "+966"
  },
  {
    "name_ar": "الولايات المتحدة",
    "name_en": "United States",
    "country_code": "US",
    "dial_code": "+1"
  }
]
GET /numbers/{country_code}

جلب الأرقام المتاحة لدولة محددة

تستخدم لجلب الأرقام الجاهزة للاستخدام لدولة معينة. استبدل {country_code} برمز الدولة (مثل SA, US).

المتغير (Parameter)النوعالإلزاميةالوصف (Description)
country_codeStringإلزامي بالرابطرمز الدولة ISO (مثل: uk, sa).
limitIntegerاختياري (Query)تحديد عدد النتائج الراجعة (افتراضي: 20، أقصى: 100).
GET /messages/{full_number}

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

يعيد قائمة بالرسائل النصية التي تم استقبالها على رقم محدد تم حجزه مسبقاً. مرر الرقم الكامل بدون رمز +.

JSON Response Example 
{
  "number": "12025550147",
  "messages": [
    {
      "msg_id": "msg_98x7asdf",
      "sender": "WhatsApp",
      "content": "Your WhatsApp code is 142-990.",
      "received_at": "2024-10-30T14:22:00Z"
    }
  ]
}
POST /numbers/request

طلب وحجز رقم جديد (شراء مؤقت)

تستخدم لطلب حجز رقم خاص لخدمة معينة. يتم خصم الرصيد تلقائياً عند نجاح العملية.

Request Body (JSON) 
{
  "country_code": "US",
  "service": "telegram", // تحديد الخدمة المراد التسجيل بها
  "duration": 20 // المدة بالدقائق للانتظار
}

الويب هوك (Webhooks) - التحديث الفوري

بدلاً من إرسال طلبات متكررة لمعرفة ما إذا كانت هناك رسالة جديدة (Polling)، ننصحك بشدة باستخدام خاصية الـ Webhook.

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

Webhook Payload (POST to your server) 
{
  "event": "message.received",
  "data": {
    "number": "447700900123",
    "sender": "Facebook",
    "text": "332901 is your Facebook verification code."
  }
}

أمثلة التكامل البرمجي (Snippets)

لتسهيل عملية الدمج، تفضل هذه الأمثلة السريعة بلغات البرمجة الأكثر شيوعاً لجلب رصيد الحساب.

مثال بلغة Java (OkHttp)

Java 
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.yallasms.com/v1/account/balance")
  .get()
  .addHeader("X-API-Key", "YOUR_API_KEY_HERE")
  .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

مثال بلغة PHP (cURL)

PHP 
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.yallasms.com/v1/account/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY_HERE",
    "Accept: application/json"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

معالجة الأخطاء والقيود (Rate Limits)

لضمان استقرار الشبكة وعدالة الاستخدام، يتم تطبيق قيود على معدل الطلبات المسموح بها (Rate Limiting). يتم السماح بـ 60 طلب في الدقيقة لكل مفتاح API.

رموز حالة HTTP المستخدمة لمعالجة الأخطاء:

كود الحالة (Status)الاسمالسبب ومعنى الخطأ
200 OKنجاحتمت معالجة الطلب وإرجاع البيانات بنجاح.
400 Bad Requestطلب غير صالحبيانات مفقودة أو مُنسقة بشكل خاطئ في الطلب المرسل.
401 Unauthorizedغير مصرحمفتاح X-API-Key غير موجود، أو غير صالح، أو الحساب موقوف.
402 Payment Requiredالرصيد غير كافٍحاولت حجز رقم ورصيدك الحالي لا يغطي تكلفة العملية.
404 Not Foundغير موجودالمسار المطلوب غير متوفر، أو الرقم الذي تبحث عنه غير مسجل لك.
429 Too Many Requestsتجاوز الحدلقد تجاوزت حد 60 طلباً في الدقيقة. يرجى إبطاء الطلبات.
500 Internal Errorخطأ بالخادمحدث خطأ استثنائي في خوادمنا. فريقنا يتلقى تنبيهاً فورياً للتعامل معه.