API استئجار الأرقام
استأجر رقمًا لمدة محددة واقرأ كل الرسائل القصيرة التي يستقبلها، عبر نقطة handler_api.php المتوافقة.
كيف يعمل
كل طلب هو GET إلى /stubs/handler_api.php مع api_key و action. ترد إجراءات الاستئجار بصيغة JSON في حالتي النجاح والخطأ.
تقبل إجراءات الاستئجار المصادقة بمفتاح API فقط. رموز جلسة الويب تتلقى WRONG_ACTION.
الأسعار نفسها كما في لوحة الويب وتُخصم بالدولار الأمريكي من محفظتك.
الإجراءات
| الإجراء | المعاملات | ماذا يفعل |
|---|---|---|
getRentServicesAndCountries | country, rent_time | عروض استئجار مسعّرة لبلد ومدة واحدة. services.{code}.cost هو السعر و quant هو المخزون المتاح. |
getRentNumber | service, country, rent_time | يستأجر رقمًا ويخصم من المحفظة. يعيد phone.id و phone.number و phone.endDate. |
getRentStatus | id, page, size | الرسائل التي استقبلها الرقم المستأجر، الأحدث أولًا. page (يبدأ من 0) و size اختياريان. |
setRentStatus | id, status (1 | 2) | status=1 ينهي الاستئجار مبكرًا دون استرداد. status=2 يلغيه؛ يُسترد المبلغ كاملًا فقط إذا لم تصل أي رسالة. |
continueRentNumber | id, rent_time, expectedCharge | يمدد استئجارًا نشطًا بعدد ساعات rent_time ويخصم من المحفظة. |
getRentList | - | استئجاراتك النشطة: id و phone. |
getContinueRentPriceNumber | id, rent_time | سعر تمديد الاستئجار دون خصم. |
رموز البلدان
- الاستئجار متاح في 27 بلدًا: AT, BE, BR, CZ, DE, EE, ES, FI, FR, GB, GE, GR, HR, ID, IT, LV, MD, MY, NL, PL, PT, RO, SE, SI, SK, UA, US. المعامل country إلزامي لاستئجار رقم أو قراءة الأسعار، ويُنصح برمز ISO المكوّن من حرفين. المدد: 24, 72, 168 ساعة.
- لقراءة هذه القائمة عبر الواجهة، استدعِ getRentServicesAndCountries دون country: تتضمن الاستجابة countryList (رموز ISO) وhours وcurrency، دون أسعار أو مخزون. للأسعار والمخزون أرسل country وrent_time.
- يُنصح بإرسال رمز ISO للبلد، مثل country=US أو country=GB. الأحرف الكبيرة والصغيرة مقبولة.
- المعرّفات الرقمية للبلدان ليست متطابقة بين الخدمات. إذا أرسلت رقمًا فاقرأه من استجابة getCountries باستخدام مفتاح API الخاص بك، ولا تنسخه من قائمة مزوّد آخر.
- تقبل إجراءات الاستئجار المعرّف الرقمي فقط للبلدان المتاحة للاستئجار، كما يظهر في getCountries. أي رقم آخر يعيد BAD_COUNTRY؛ وإذا لم تكن متأكدًا فاستخدم رمز ISO.
- الأرقام 42 (DE), 44 (HR), 45 (SE), 47 (NL), 48 (LV), 49 (AT), 51 (TH), 55 (ES), 58 (SI), 62 (CZ), 72 (BR), 77 (FR), 90 (SK), 97 (PT), 115 (GE), 116 (GR), 128 (BE), 175 (FI), 178 (IT) غير مقبولة للاستئجار، لأنها تشير إلى بلد مختلف في خدمات أخرى. تعيد هذه الأرقام دائمًا BAD_COUNTRY_USE_ISO، ولا يُخصم أي مبلغ ولا يُستأجر أي رقم. أرسل رمز ISO بدلًا منها، مثل country=DE. لهذه البلدان يكون الحقل countries في استجابة getRentServicesAndCountries فارغًا.
- يُقبل أيضًا المعرّف النصي للبلد لدينا.
- تُعيد getRentServicesAndCountries المعرّف الرقمي للبلد في countries.
قائمة البلدان ورموزها
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getCountries"عروض الاستئجار لبلد حسب رمز ISO
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries&country=US&rent_time=24"قائمة البلدان المتاحة للاستئجار
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries"الاستجابة
{"countryList":["AT","BE","BR","CZ","DE","EE","ES","FI","FR","GB","GE","GR","HR","ID","IT","LV","MD","MY","NL","PL","PT","RO","SE","SI","SK","UA","US"],"hours":[24,72,168],"currency":840}مثال
الطلب
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentNumber&service=wa&country=US&rent_time=24"الاستجابة
{
"status": "success",
"phone": {
"id": "cm4x9k2...",
"endDate": "2026-11-02T12:00:00",
"number": "15550000001"
}
}الطلب
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentStatus&id=cm4x9k2..."الاستجابة
{
"status": "success",
"quantity": "1",
"values": {
"0": {
"phoneFrom": "WhatsApp",
"text": "Your code: 123456",
"service": "wa",
"date": "2026-11-01 12:05:00"
}
}
}تفاصيل الاستجابة
- معرّف الاستئجار id هو سلسلة نصية (مثل "cm4x9k2...") وليس رقمًا. احفظه كنص.
- تُقرأ المدة بالساعات من rent_time؛ ويُقبل المعامل time أيضًا.
- إذا لم تُرسل مدة، تُستخدم أقصر مدة متاحة (حاليًا 24 ساعة). أرسل rent_time صراحة عند الاستئجار والتمديد.
- قيمة currency هي 840 (دولار أمريكي). cost و price أرقام بالدولار الأمريكي.
- endDate وتواريخ الرسائل بتوقيت UTC، دون لاحقة منطقة زمنية.
- يتم تجاهل المعامل url: الاستئجار لا يرسل webhook. استعلم عبر getRentStatus لقراءة الرسائل الجديدة.
- تُعاد الأخطاء بصيغة {"status":"error","message":"<CODE>"}. أخطاء المصادقة وحد المعدل تبقى بصيغة نص عادي (BAD_KEY، RATE_LIMITED).
- احصل على عرض سعر عبر getContinueRentPriceNumber قبل continueRentNumber. المبلغ المخصوم لا يتجاوز أبدًا آخر عرض سعر عُرض عليك (صالح لمدة 10 دقائق، لنفس الاستئجار ونفس rent_time). المعامل الاختياري expectedCharge (بالدولار، مثلًا 1.334) يخفض هذا الحد فقط ولا يرفعه. إذا تجاوز السعر الحد، أو لم يكن لديك عرض سعر صالح، لا يتم التمديد ولا أي خصم ويُعاد عرض سعر جديد: WRONG_CHARGE مع المبلغ في price. أعد المحاولة بعرض السعر الجديد.
- لا يمكن تمديد الاستئجار إلا بعد انتهاء نافذة الإلغاء المجاني (أول 20 دقيقة)؛ قبل ذلك يعيد continueRentNumber الرمز CONTINUE_TOO_EARLY ولا يُخصم أي مبلغ.
نافذة الإلغاء
يُرفض الإلغاء خلال أول دقيقتين من الاستئجار (CANT_CANCEL).
يمكن الإلغاء المجاني حتى 20 دقيقة بعد بدء الاستئجار. بعد هذه النافذة يُرفض الإلغاء، عادةً مع CANT_CANCEL (وفي حالات نادرة TEMPORARILY_UNAVAILABLE)؛ استخدم status=1 للإنهاء بدلًا منه.
يُسترد مبلغ الاستئجار الملغى كاملًا فقط إذا لم يستقبل أي رسالة.
انتهاء المهلة وإعادة المحاولة
getRentNumber ليس متطابق النتائج: لا تُعد إرساله بعد انتهاء المهلة. استدعِ getRentList أولًا؛ إذا وجدت استئجارًا لا تحتاجه، ألغه بين الدقيقة 2 والدقيقة 20 لاسترداد كامل (دون رسائل مستلمة).
الحدود
الاستئجارات الجديدة محدودة لكل مفتاح API في كل يوم UTC (التمديدات لا تُحتسب): 50 استئجارًا كحد أقصى لكل مفتاح. فوق ذلك: RENT_LIMIT.
يُحتسب getRentNumber و continueRentNumber أيضًا ضمن حصة الشراء اليومية للمفتاح.
هذه الإجراءات متاحة لجميع مفاتيح API في حسابك.
رموز الأخطاء
{ "status": "error", "message": "NO_BALANCE" }NO_ | رصيد المحفظة غير كافٍ. |
NO_ | لا يتوفر رقم لهذه الخدمة والبلد والمدة حاليًا. |
BAD_ | رمز الخدمة مفقود أو غير مدعوم. |
BAD_ | البلد مفقود أو غير معروف أو غير متاح (استخدم رمز ISO). |
BAD_ | المعرّف الرقمي للبلد غير مقبول للاستئجار (يشير إلى بلد مختلف في خدمات أخرى). استخدم رمز ISO؛ ولا يُخصم أي مبلغ. الأرقام المعنية مذكورة في قسم رموز البلدان. تتضمن الاستجابة أيضًا الحقل description بنص مقروء. |
BAD_ | هذه المدة غير متاحة. |
NO_ | المعامل id مفقود. |
INVALID_ | لا يوجد استئجار بهذا المعرّف في حسابك. |
INCORECT_ | يجب أن تكون قيمة status في setRentStatus هي 1 أو 2. |
CANT_ | الإلغاء غير ممكن الآن (خلال أول دقيقتين، أو بعد نافذة الإلغاء المجاني حتى 20 دقيقة). |
ALREADY_ | انتهى الاستئجار بالفعل. |
ALREADY_ | تم إلغاء الاستئجار بالفعل. |
STATUS_ | الاستئجار نشط لكن لم تصل أي رسالة بعد. |
STATUS_ | تم إلغاء الاستئجار. |
STATUS_ | انتهى الاستئجار أو انقضت مدته. |
RENT_ | تم بلوغ حد الاستئجار اليومي لمفتاح API هذا. |
TEMPORARILY_ | مشكلة مؤقتة. في getRentNumber و continueRentNumber لم يتم الخصم أو تم استرداده. في الإلغاء قد تكون النتيجة غير معروفة: تحقق من الاستئجار عبر getRentStatus قبل إعادة المحاولة. |
WRONG_ | continueRentNumber: السعر أعلى من الحد الخاص بك (آخر عرض سعر عُرض عليك، صالح لمدة 10 دقائق، مخفضًا بـ expectedCharge) أو ليس لديك عرض سعر صالح. لم يتم التمديد ولا أي خصم. عرض السعر الجديد في price؛ أعد المحاولة به. |
CONTINUE_ | continueRentNumber: لا يمكن التمديد خلال أول 20 دقيقة من الاستئجار (نافذة الإلغاء المجاني). لم يُخصم أي مبلغ؛ أعد المحاولة بعد ذلك. يعمل getContinueRentPriceNumber في هذه المدة أيضًا. |
ERROR_ | خطأ غير متوقع في الخادم. |
REST API
العمليات نفسها متاحة لجميع مفاتيح API كنقاط JSON ضمن /api/v1/rentals (أرسل المفتاح في الترويسة x-api-key). الحد اليومي للاستئجار لكل مفتاح مشترك مع الإجراءات أعلاه؛ عند تجاوزه ترد واجهة REST بالرمز 429 والسبب rent_daily_cap.
curl -X POST "https://smsbulk.net/api/v1/rentals" \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "serviceCode": "wa", "countryIso": "US", "durationHours": 24 }'التمديد: احصل أولًا على عرض سعر عبر GET /api/v1/rentals/{id}/extend-price، ثم استدعِ POST /api/v1/rentals/{id}/extend. المبلغ المخصوم لا يتجاوز أبدًا آخر عرض سعر عُرض عليك (صالح لمدة 10 دقائق، لنفس الاستئجار ونفس المدة). المعامل الاختياري expectedCharge (بالدولار كنص، مثلًا "1.334") يخفض هذا الحد فقط ولا يرفعه. إذا تجاوز السعر الحد، أو لم يكن لديك عرض سعر صالح، لا يتم التمديد ولا أي خصم وترد الواجهة بالرمز 409 PRICE_CHANGED مع عرض السعر الجديد في currentCharge. أعد المحاولة بعرض السعر الجديد.
خلال أول 20 دقيقة من الاستئجار (نافذة الإلغاء المجاني) يرد POST /api/v1/rentals/{id}/extend بالرمز 409 RENTAL_EXTEND_TOO_EARLY؛ ويتضمن جسم الاستجابة extendAllowedFrom (وقت بصيغة ISO)، وهو اللحظة التي يُقبل التمديد بدءًا منها. لا يُخصم أي مبلغ، وتبقى عروض الأسعار متاحة.