المصادقة واستجابات API

استخدم بيانات اعتماد API

أرسل طلبات v3 عبر HTTPS إلى https://api.multitel.net. تتطلب كل نقطة نهاية في هذا الدليل المصادقة. احتفظ ببيانات الاعتماد على الخادم الخاص بك، ولا تضعها أبدا في JavaScript الخاص بالمتصفح أو الصفحات العامة أو لقطات الشاشة أو نظام التحكم في المصدر.

استخدم أحد أشكال بيانات الاعتماد التالية:

• HTTP Basic مع اسم المستخدم وكلمة المرور API المعدين لحساب MultiTEL الخاص بك.
• رمز Bearer في ترويسة Authorization: Bearer YOUR_API_TOKEN، لحساب API مفعل معد لمصادقة الرمز. لا تقبل طلبات الرمز إلا من العناوين المسموح بها لحساب API ذلك.

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

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

المتغيرات في هذه الأمثلة هي عناصر نائبة لبيانات الاعتماد التي تخزنها بشكل خاص في بيئتك.

معالجة إخفاقات المصادقة

ترسل إخفاقات المصادقة مع حالة HTTP 401. يستخدم الجسم المغلف القياسي، مع status.code مضبوطا على 401 وسلسلة فارغة بصفتها response.

• لا توجد بيانات اعتماد: status.msg هو Username and password are required، وتتضمن الاستجابة تحدي مصادقة Basic.
• تم رفض رمز Bearer: إذا كانت ترويسة Authorization تستخدم مخطط Bearer وكان الرمز غير معروف أو معطلا أو غير مسموح به من عنوانك، status.msg هو Invalid bearer token. لا تجرب أي بيانات اعتماد أخرى عند وجود ترويسة Bearer.
• بيانات اعتماد Basic غير صالحة: status.msg يبدأ ب A valid username and password pair are required.، وتتضمن الاستجابة تحدي مصادقة Basic. يمكن أن تتضمن الرسالة مزيدا من النص التشخيصي، لذا لا تحللها.

لا تعد المحاولة تلقائيا بنفس بيانات الاعتماد. قد تتسبب المحاولات الفاشلة الكثيرة من عنوان واحد خلال فترة قصيرة في حظر الطلبات اللاحقة من ذلك العنوان.

قراءة جسم الاستجابة

معظم نقاط النهاية v3، بما في ذلك getcountries، getstates، getareas و other، تعيد JSON في هذا المغلف:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

هذه استجابة توضيحية لقائمة البلدان، وليست بيانا عن المخزون أو القدرات الحالية.

تبدو استجابة الخطأ كما يلي:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

إذا تعذر ترميز استجابة، فسيحتوي الجسم على status.code 500، status.msg Response encoding error، وكائن فارغ باعتباره response.

نقطة النهاية القديمة GET /v3/countries تعيد {"code": 200, "data": [...]} بدلا من ذلك. تحقق من الاستجابة الموثقة لكل نقطة نهاية. إذا لم يكن الجسم JSON صالحا، على سبيل المثال بعد فشل غير متوقع في الخادم، فاعتبر الطلب فاشلا وأعد المحاولة لاحقا.

رموز نتائج API وحالة HTTP

status.code هو رمز نتيجة API. وهو ليس حالة HTTP. ترسل إخفاقات المصادقة مع HTTP 401. وبخلاف ذلك، تبلغ نقاط نهاية الاكتشاف عن نتائج مثل 404 و 500 فقط في status.code ولا تحدد حالة HTTP مطابقة. لذلك قد تصل نتيجة غير موجودة أو ذات معلمة مفقودة مع حالة HTTP ناجحة. تحقق دائما من status.code قبل استخدام response.

رمز النتيجة 500 مع الرسالة ISO Code parameter is required يعني أن معلمة مطلوبة مفقودة. صحح الطلب بدلا من اعتباره عطلا في الخادم.

اتبع next_function

تتضمن نتائج الاكتشاف next_function. وهو مسار نسبي دون شرطة مائلة بادئة، وأحيانا مع سلسلة استعلام، مثل v3/getareas/US أو v3/getareas/US?state=NY. أضف في بدايته https://api.multitel.net/ لبناء الطلب التالي، ووثق ذلك الطلب بنفس الطريقة. المرشحات الاختيارية التي أرسلتها، مثل pid، لا تحمل إلى next_function. أضفها مرة أخرى إذا كنت تحتاج إليها.

محدد المخزون الاختياري (pid)

getcountries، getstates و getareas تقبل المعلمة الاختيارية pid التي تضيق النتائج إلى مصدر مخزون واحد. استخدمها فقط مع قيمة مقدمة من MultiTEL، سواء في شكلها الرقمي أو في شكلها السداسي العشري المكون من 32 حرفا. احذفها للاستخدام العادي. أرسل pid في سلسلة الاستعلام. إذا لم تتعرف نقطة النهاية على القيمة أو تقبلها، فستتجاهلها دون خطأ، وسيتصرف الطلب كما لو pid تم حذفها.

افصل الاكتشاف عن الطلبات

لا تغير عمليات البحث عن البلدان والولايات والمناطق حسابك. يحدث كتالوج الأرقام الخاصة (other) تفاصيل الكتالوج ويحفظ عروض الأسعار لحسابك، لكنه لا يقدم طلبا. لا يحجز أي طلب اكتشاف رقما، ويمكن أن يتغير المخزون بين الطلبات. راجع المتطلبات والسعر لرقم ما قبل استخدام نقطة نهاية للطلب.

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