การตรวจสอบสิทธิ์และการตอบสนอง 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) รีเฟรชรายละเอียดแค็ตตาล็อกและบันทึกใบเสนอราคาสำหรับบัญชีของคุณ, แต่ไม่ได้สั่งซื้อ. คำขอค้นหาไม่มีการจองหมายเลข, และสินค้าคงคลังอาจเปลี่ยนแปลงระหว่างคำขอ. ตรวจสอบข้อกำหนดและราคาสำหรับหมายเลขก่อนใช้เอนด์พอยต์การสั่งซื้อ.

สำหรับการซื้อ, การกำหนดหมายเลข, ข้อความ, การส่งแฟกซ์ และการดำเนินการอื่นๆ, ให้ปฏิบัติตามกฎการลองใหม่ของเอนด์พอยต์นั้น. หากการดำเนินการหมดเวลาหลังจากส่ง, ให้ตรวจสอบสถานะหรือบันทึกบัญชีของคุณก่อนทำซ้ำ. การตอบสนองที่สูญหายไม่ได้พิสูจน์ว่าการดำเนินการล้มเหลว.