API استئجار الأرقام

API استئجار الأرقام

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

إجراءات الاستئجار متاحة لجميع مفاتيح API، مع حد يومي لكل مفتاح (راجع الحدود).

كيف يعمل

كل طلب هو GET إلى /stubs/handler_api.php مع api_key و action. ترد إجراءات الاستئجار بصيغة JSON في حالتي النجاح والخطأ.

تقبل إجراءات الاستئجار المصادقة بمفتاح API فقط. رموز جلسة الويب تتلقى WRONG_ACTION.

الأسعار نفسها كما في لوحة الويب وتُخصم بالدولار الأمريكي من محفظتك.

الإجراءات

الإجراءالمعاملاتماذا يفعل
getRentServicesAndCountriescountry, rent_timeعروض استئجار مسعّرة لبلد ومدة واحدة. services.{code}.cost هو السعر و quant هو المخزون المتاح.
getRentNumberservice, country, rent_timeيستأجر رقمًا ويخصم من المحفظة. يعيد phone.id و phone.number و phone.endDate.
getRentStatusid, page, sizeالرسائل التي استقبلها الرقم المستأجر، الأحدث أولًا. page (يبدأ من 0) و size اختياريان.
setRentStatusid, status (1 | 2)status=1 ينهي الاستئجار مبكرًا دون استرداد. status=2 يلغيه؛ يُسترد المبلغ كاملًا فقط إذا لم تصل أي رسالة.
continueRentNumberid, rent_time, expectedChargeيمدد استئجارًا نشطًا بعدد ساعات rent_time ويخصم من المحفظة.
getRentList-استئجاراتك النشطة: id و phone.
getContinueRentPriceNumberid, 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_BALANCEرصيد المحفظة غير كافٍ.
NO_NUMBERSلا يتوفر رقم لهذه الخدمة والبلد والمدة حاليًا.
BAD_SERVICEرمز الخدمة مفقود أو غير مدعوم.
BAD_COUNTRYالبلد مفقود أو غير معروف أو غير متاح (استخدم رمز ISO).
BAD_COUNTRY_USE_ISOالمعرّف الرقمي للبلد غير مقبول للاستئجار (يشير إلى بلد مختلف في خدمات أخرى). استخدم رمز ISO؛ ولا يُخصم أي مبلغ. الأرقام المعنية مذكورة في قسم رموز البلدان. تتضمن الاستجابة أيضًا الحقل description بنص مقروء.
BAD_TIMEهذه المدة غير متاحة.
NO_ID_RENTالمعامل id مفقود.
INVALID_PHONEلا يوجد استئجار بهذا المعرّف في حسابك.
INCORECT_STATUSيجب أن تكون قيمة status في setRentStatus هي 1 أو 2.
CANT_CANCELالإلغاء غير ممكن الآن (خلال أول دقيقتين، أو بعد نافذة الإلغاء المجاني حتى 20 دقيقة).
ALREADY_FINISHانتهى الاستئجار بالفعل.
ALREADY_CANCELتم إلغاء الاستئجار بالفعل.
STATUS_WAIT_CODEالاستئجار نشط لكن لم تصل أي رسالة بعد.
STATUS_CANCELتم إلغاء الاستئجار.
STATUS_FINISHانتهى الاستئجار أو انقضت مدته.
RENT_LIMITتم بلوغ حد الاستئجار اليومي لمفتاح API هذا.
TEMPORARILY_UNAVAILABLEمشكلة مؤقتة. في getRentNumber و continueRentNumber لم يتم الخصم أو تم استرداده. في الإلغاء قد تكون النتيجة غير معروفة: تحقق من الاستئجار عبر getRentStatus قبل إعادة المحاولة.
WRONG_CHARGEcontinueRentNumber: السعر أعلى من الحد الخاص بك (آخر عرض سعر عُرض عليك، صالح لمدة 10 دقائق، مخفضًا بـ expectedCharge) أو ليس لديك عرض سعر صالح. لم يتم التمديد ولا أي خصم. عرض السعر الجديد في price؛ أعد المحاولة به.
CONTINUE_TOO_EARLYcontinueRentNumber: لا يمكن التمديد خلال أول 20 دقيقة من الاستئجار (نافذة الإلغاء المجاني). لم يُخصم أي مبلغ؛ أعد المحاولة بعد ذلك. يعمل getContinueRentPriceNumber في هذه المدة أيضًا.
ERROR_SQLخطأ غير متوقع في الخادم.

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)، وهو اللحظة التي يُقبل التمديد بدءًا منها. لا يُخصم أي مبلغ، وتبقى عروض الأسعار متاحة.