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
الحصول على قائمة الأرقام المتاحة
نقطة النهاية هذه تقوم بإرجاع قائمة بجميع الأرقام العامة المتاحة حاليًا على المنصة، مع إمكانية التصفية حسب الدولة.
معلمات الطلب (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"
}
}
الحصول على الرسائل لرقم معين
إرجاع قائمة بالرسائل المستلمة على رقم هاتف معين، معرف بواسطة {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."
}
}