API للمطورين

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

سواء كنت ترغب في أتمتة عمليات التحقق، أو بناء أدوات اختبار، أو تطوير حلول مخصصة، فإن الـ API الخاصة بنا توفر لك المرونة والقوة اللازمة.

الرابط الأساسي للـ API (Base URL): https://recivsms.com/console/v1?api-kay

المصادقة (Authentication)

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

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

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

X-API-KEY: YOUR_API_KEY_HERE

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

GET /numbers

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

معلمات الطلب (Query Parameters):

المعلم (Parameter) الوصف النوع مطلوب مثال
country_code رمز الدولة المكون من حرفين (ISO 3166-1 alpha-2). إذا لم يتم توفيره، سيتم إرجاع أرقام من جميع الدول. String لا FR, EG, US
limit الحد الأقصى لعدد الأرقام المراد إرجاعها (الافتراضي: 20، الأقصى: 100). Integer لا 10

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


curl -X GET "https://api.recivsms.com/v1/numbers?country_code=FR&limit=5" \
     -H "X-API-KEY: YOUR_API_KEY_HERE"
                    

مثال للاستجابة (JSON - Status 200 OK):


{
  "status": "success",
  "data": {
    "numbers": [
      {
        "id": "FR001",
        "phone_number": "+33612345678",
        "country_code": "FR",
        "country_name": "France",
        "status": "online",
        "last_activity_at": "2024-07-29T10:30:00Z"
      },
      {
        "id": "FR002",
        "phone_number": "+33798765432",
        "country_code": "FR",
        "country_name": "France",
        "status": "online",
        "last_activity_at": "2024-07-29T10:25:00Z"
      }
      // ... المزيد من الأرقام
    ],
    "total_count": 2, // إجمالي الأرقام المطابقة للمعايير
    "limit": 5,
    "country_filter": "FR"
  }
}
                    

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

GET /numbers/{number_id}/messages

إرجاع قائمة بالرسائل المستلمة على رقم هاتف معين، معرف بواسطة {number_id}.

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

المعلم (Parameter) الوصف النوع
number_id معرف الرقم الفريد (مثل "FR001" الذي تم الحصول عليه من نقطة النهاية /numbers). String

معلمات الطلب (Query Parameters):

المعلم (Parameter) الوصف النوع مطلوب مثال
limit الحد الأقصى لعدد الرسائل المراد إرجاعها (الافتراضي: 20، الأقصى: 50). Integer لا 10
since_timestamp جلب الرسائل التي وصلت بعد هذا الطابع الزمني (Unix timestamp in seconds or ISO 8601). Integer/String لا 1678886400 أو 2024-07-29T00:00:00Z

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


curl -X GET "https://api.recivsms.com/v1/numbers/FR001/messages?limit=3" \
     -H "X-API-KEY: YOUR_API_KEY_HERE"
                    

مثال للاستجابة (JSON - Status 200 OK):


{
  "status": "success",
  "data": {
    "number_info": {
        "id": "FR001",
        "phone_number": "+33612345678",
        "country_code": "FR"
    },
    "messages": [
      {
        "message_id": "msg_abc123",
        "sender": "Google",
        "body": "Your Google verification code is G-123456.",
        "received_at": "2024-07-29T10:30:00Z"
      },
      {
        "message_id": "msg_def456",
        "sender": "Amazon",
        "body": "رمز التحقق أمازون: 987654.",
        "received_at": "2024-07-29T10:28:15Z"
      }
      // ... المزيد من الرسائل
    ],
    "total_count": 2,
    "limit": 3
  }
}
                    

حدود الطلبات (Rate Limits)

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

  • الخطة المجانية: 60 طلبًا في الدقيقة.
  • الخطط المدفوعة: يرجى مراجعة تفاصيل خطتك لمعدلات أعلى.

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

  • X-RateLimit-Limit: إجمالي عدد الطلبات المسموح بها في الفترة الحالية.
  • X-RateLimit-Remaining: عدد الطلبات المتبقية في الفترة الحالية.
  • X-RateLimit-Reset: الوقت (Unix timestamp) الذي سيتم فيه إعادة تعيين حدودك.

رموز الأخطاء (Error Codes)

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

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

أمثلة شائعة لرموز الأخطاء:

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

عند حدوث خطأ، ستحتوي الاستجابة عادةً على كائن JSON يصف الخطأ بمزيد من التفصيل، مثل:


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