البحث عن أرقام هاتف متاحة

اختيار بادئة فردية

استخدم استدعاءات اكتشاف البلدان والمناطق، ثم getprefixes من دون تجميع. انسخ uuid للبادئة المختارة. إذا كانت قيمة returns_numbers هي 0، فتُخصّص البادئة رقمًا عند طلب الشراء؛ استخدم رابط next_function المعاد بدلًا من اشتراط قائمة بأرقام فردية.

تصفح دفعة محدودة

للبحث العادي، استخدم compact=1 وضع حجم الدفعة المطلوب في المسار وفي معامل الاستعلام quantity معًا، كما هو موضح أدناه. لا يوجد معامل صفحة أو مؤشر متابعة. النتيجة المختصرة عينة؛ ولا يضمن تكرار الطلب صفحة تالية لا تتداخل مع السابقة. لا تفسر النتيجة الفارغة أو الصغيرة على أنها إجمالي عدد الأرقام في المخزون.

البحث عن نمط أرقام يسهل تذكّره

قدّم number_filter_mode=contains أو ends_with مع number_filter_value. يجب أن تحتوي القيمة على 1–15 خانة رقمية. قد يجلب البحث دفعات محدودة من الأرقام المرشحة قبل تطبيق المرشح، ولذلك قد يفوّت مخزونًا آخر مطابقًا. إذا احتجت إلى أن يطبق مصدر مدعوم البحث المطلوب، فاحصل على محدّد pid من MultiTEL واستخدم filter_required=1؛ ويؤدي غياب التحديد أو عدم دعمه إلى خطأ في واجهة برمجة التطبيقات.

مراجعة الرقم المختار

اقرأ number، info.uuid، وقيمة price[].uuid المختارة، وأسماء الإمكانات المتاحة ومتطلبات التسجيل من النتيجة نفسها. قد توفر المصفوفة price عدة خطط بأعداد قنوات وأسعار مختلفة. قد تُرمّز الحقول المالية والكميات كسلاسل نصية. تختلف البيانات الوصفية الاختيارية، بما فيها info.state، بين المصادر؛ فلا تشترط صيغة موحدة للولاية أو المقاطعة، ولا تستنتج الأسعار من معرّف.

في المسار الذي لا يستخدم التدفق، تُزال التكرارات من الأرقام المرشحة وتُوزّع عبر المصادر قبل ترتيب الدفعة المختارة بحسب السعر الشهري للخطة الأولى. قد تبدأ مسارات أخرى التدفق مبكرًا، لذلك لا يوجد ضمان شامل للترتيب أو إزالة التكرار ينطبق على جميع الطلبات. ولا يثبت الترتيب أن العينة المعادة تتضمن أرخص رقم في الدليل كله.

الطلب بشكل منفصل وتأكيد النتيجة

لا يشتري البحث أي شيء ولا يحجزه. احتفظ بمعرّفات الرقم والخطة المعادة لاستخدامها في مسار الطلب ضمن الحساب نفسه. راجع الخطة الفعلية والمتطلبات والرسوم قبل إرسال طلب شراء. قد تؤخر متطلبات التسجيل التفعيل؛ ولا تحدد نتيجة البحث مهلة تفعيل ثابتة.

الطلب

استخدم حساب واجهة برمجة تطبيقات MultiTEL مفعّلًا: بيانات اعتماد HTTP Basic لحساب يستخدم كلمة مرور، أو Authorization: Bearer لحساب يستخدم رمزًا. تُطبّق أذونات الحساب وقيود عناوين IP الخاصة به. راجع إرشادات المصادقة العامة.

معاملات المسار ومعاملات استعلام URL. استخدم GET لمسار البحث العام. يقبل المعالج أيضًا بعض قيم النماذج والطلبات، لكنه ليس واجهة بحث بجسم JSON.

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

الاستجابة

كائن JSON واحد يحتوي على status وresponse. عند النجاح، تكون قيمة status.code هي 200، ويكون response مصفوفة من إدخالات الأرقام. يساوي status.results عدد عناصر المصفوفة المعادة؛ وقد تكون قيمة status.msg هي Results: N أو OK في الاستجابة المتدفقة. من دون compact=1، تكتب بعض عمليات البحث المصفوفة response تدريجيًا وتنتهي بـ status، لذلك انتظر جسم JSON كاملًا. هذه ليست صيغة JSON مفصولة بأسطر جديدة. تحقق من status.code حتى عند نجاح النقل عبر HTTP. الحقول المعتادة موضحة أدناه؛ وتختلف البيانات الوصفية الخاصة بالمصادر والحقول الاختيارية. تعامل مع كل معرّف كقيمة غير دالة، واحتفظ بالرقم وقيمة price[].uuid المختارة معه.

بنية الاستجابة للتوضيح فقط؛ لا تتضمن بيانات حساب مباشرة ولا عرض سعر حالي.

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

الأخطاء

• 401: فشلت المصادقة. لا تؤدي بيانات الاعتماد غير الصالحة أو المفقودة، أو رفض الوصول إلى حساب واجهة برمجة التطبيقات، إلى نتائج بحث.
• 404: Invalid prefix ID أو Invalid country أو Invalid area أو No numbers found. اقرأ status.msg؛ فاستجابة الخطأ ليست مصفوفة أرقام.
• 400: NUMBER_FILTER_INVALID في response.code: نمط غير صالح، أو قيمة لا تتكون من 1–15 خانة رقمية، أو filter_required من دون تقديم النمط والقيمة معًا.
• 422: NUMBER_FILTER_UNSUPPORTED في response.code: إما أن البادئة تخصص رقمًا وقت الطلب (reason=order_only_prefix ويحدد next_function مسار الطلب)، أو أن المصدر المحدد صراحةً لا يدعم المرشح المطلوب.

التوفر والآثار الجانبية

• يبحث هذا المعالج عن الأرقام ويجهّز عروض أسعار؛ ولا يقدّم طلب شراء رقم ولا يخصم رسم شراء رقم. يمكنه تحديث ذاكرات التخزين المؤقت للدليل، وإزالة المخزون القديم المخزّن مؤقتًا، وحفظ خطط أسعار ضمن نطاق الحساب، وكتابة سجلات البحث.
• التوفر نتيجة في لحظة معينة، وليس حجزًا. قد يفشل طلب شراء لاحق أو يعيد توفرًا مختلفًا. راجع نتيجة الطلب وطابقها قبل إعادة محاولة الشراء.
• الأسعار خاصة بالحساب. احتفظ بمعرّف الخطة المختارة للحساب نفسه، وراجع شروط الطلب والرسوم بشكل منفصل؛ فنقطة النهاية هذه وحدها لا تثبت أن السعر سيبقى صالحًا حتى طلب شراء لاحق.
• الرقم والأسعار في المثال قيم خيالية لتوضيح بنية الاستجابة، وليست عرض سعر مباشرًا. يجب قراءة الإمكانات وأعداد القنوات والمدة ومعلومات التسجيل من النتيجة الفعلية المختارة.
• تحتوي بعض أوصاف التسجيل على نص منسّق أو روابط. تعامل مع السلاسل المعادة كبيانات غير موثوقة عند عرضها في تطبيقك.
• يعتمد توفر الجوال ومؤشراته على أهلية الحساب والمخزون. لا تثبت بادئة من الدليل أو المؤشر is_mobile وحده إمكانات الجوال لرقم معين.