Xác thực và phản hồi API

Sử dụng thông tin xác thực API

Gửi yêu cầu v3 qua HTTPS tới https://api.multitel.net. Mọi điểm cuối trong hướng dẫn này đều yêu cầu xác thực. Hãy giữ thông tin xác thực trên máy chủ của bạn và không bao giờ đặt chúng trong JavaScript của trình duyệt, trang công khai, ảnh chụp màn hình hoặc hệ thống quản lý mã nguồn.

Hãy sử dụng một trong các hình thức thông tin xác thực sau:

HTTP Basic với tên người dùng và mật khẩu API đã cấu hình cho tài khoản MultiTEL của bạn.
mã thông báo Bearer trong tiêu đề Authorization: Bearer YOUR_API_TOKEN, dành cho tài khoản API đã bật được cấu hình xác thực bằng mã thông báo. Các yêu cầu mã thông báo chỉ được chấp nhận từ các địa chỉ được phép đối với tài khoản API đó.

Nếu danh sách cho phép IP đã được cấu hình cho tài khoản API của bạn, hãy gửi mọi yêu cầu từ các địa chỉ được phép.

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

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

Các biến trong những ví dụ này là phần giữ chỗ cho thông tin xác thực mà bạn lưu trữ riêng tư trong môi trường của mình.

Xử lý lỗi xác thực

Các lỗi xác thực được gửi với trạng thái HTTP 401. Nội dung sử dụng phong bì chuẩn, với status.code được đặt thành 401 và một chuỗi rỗng làm response.

Không có thông tin xác thực: status.msg là Username and password are required, và phản hồi bao gồm thử thách xác thực Basic.
Mã thông báo Bearer bị từ chối: nếu tiêu đề Authorization sử dụng lược đồ Bearer và mã thông báo không xác định, bị vô hiệu hóa hoặc không được phép từ địa chỉ của bạn, status.msg là Invalid bearer token. Không thử thông tin xác thực nào khác khi có tiêu đề Bearer.
Thông tin xác thực Basic không hợp lệ: status.msg bắt đầu bằng A valid username and password pair are required., và phản hồi bao gồm thử thách xác thực Basic. Thông báo có thể chứa thêm văn bản chẩn đoán, vì vậy đừng phân tích cú pháp nó.

Không tự động thử lại với cùng thông tin xác thực. Nhiều lần thử thất bại từ một địa chỉ trong thời gian ngắn có thể khiến các yêu cầu tiếp theo từ địa chỉ đó bị chặn.

Đọc nội dung phản hồi

Hầu hết các điểm cuối v3, bao gồm getcountries, getstates, getareas và other, trả về JSON trong phong bì này:

{
  "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"
    }
  ]
}

Đây là phản hồi danh sách quốc gia minh họa, không phải là tuyên bố về kho hàng hoặc khả năng hiện tại.

Trường	Ý nghĩa
`status.code`	Mã kết quả API, ví dụ `200`, `401`, `404` hoặc `500`.
`status.msg`	Thông báo mà con người có thể đọc được. Nó có thể để trống. Hãy dựa quyết định của chương trình vào `status.code`, không dựa trên văn bản thông báo.
`status.results`	Số lượng mục. Đối với các điểm cuối khám phá được tài liệu hóa ở đây, trường này xuất hiện khi `response` là danh sách JSON, bao gồm cả danh sách rỗng (`0`). Trường này vắng mặt khi `response` là chuỗi rỗng hoặc `null`. Các tải trọng điểm cuối khác có thể báo cáo số lượng theo cách khác; hãy làm theo tài liệu phản hồi riêng của chúng.
`response`	Tải trọng của điểm cuối. Kiểu của nó phụ thuộc vào điểm cuối và kết quả. Khi lỗi, nó là chuỗi rỗng.

Phản hồi lỗi có dạng như sau:

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

Nếu không thể mã hóa phản hồi, nội dung có status.code 500, status.msg Response encoding error, và một đối tượng rỗng làm response.

Điểm cuối cũ GET /v3/countries trả về {"code": 200, "data": [...]} thay vào đó. Hãy kiểm tra phản hồi đã tài liệu hóa của từng điểm cuối. Nếu nội dung không phải là JSON hợp lệ, ví dụ sau lỗi máy chủ bất ngờ, hãy coi yêu cầu là thất bại và thử lại sau.

Mã kết quả API và trạng thái HTTP

status.code là mã kết quả API. Nó không phải là trạng thái HTTP. Các lỗi xác thực được gửi với HTTP 401. Trong các trường hợp khác, các điểm cuối khám phá báo cáo các kết quả như 404 và 500 chỉ trong status.code và không đặt trạng thái HTTP tương ứng. Do đó, kết quả không tìm thấy hoặc thiếu tham số có thể đến với trạng thái HTTP thành công. Luôn kiểm tra status.code trước khi sử dụng response.

Mã kết quả 500 với thông báo ISO Code parameter is required nghĩa là thiếu một tham số bắt buộc. Hãy sửa yêu cầu thay vì coi đó là sự cố ngừng hoạt động của máy chủ.

Đi theo next_function

Kết quả khám phá bao gồm next_function. Đó là đường dẫn tương đối không có dấu gạch chéo ở đầu, đôi khi kèm chuỗi truy vấn, chẳng hạn như v3/getareas/US hoặc v3/getareas/US?state=NY. Hãy thêm tiền tố https://api.multitel.net/ để tạo yêu cầu tiếp theo, và xác thực yêu cầu đó theo cùng cách. Các bộ lọc tùy chọn bạn đã gửi, chẳng hạn như pid, không được mang sang next_function. Hãy thêm lại chúng nếu bạn cần.

Bộ chọn kho hàng tùy chọn (pid)

getcountries, getstates và getareas chấp nhận một tham số truy vấn pid tùy chọn giúp thu hẹp kết quả về một nguồn kho hàng. Chỉ sử dụng nó với giá trị do MultiTEL cung cấp, ở dạng số hoặc dạng thập lục phân 32 ký tự. Hãy bỏ qua nó khi sử dụng thông thường. Gửi pid trong chuỗi truy vấn. Nếu điểm cuối không nhận ra hoặc không chấp nhận giá trị, nó sẽ bỏ qua mà không báo lỗi, và yêu cầu hoạt động như thể pid đã bị bỏ qua.

Tách khám phá khỏi đơn hàng

Các tra cứu quốc gia, tiểu bang và khu vực không làm thay đổi tài khoản của bạn. Danh mục số đặc biệt (other) làm mới chi tiết danh mục và lưu báo giá cho tài khoản của bạn, nhưng không đặt hàng. Không có yêu cầu khám phá nào giữ chỗ một số, và kho hàng có thể thay đổi giữa các yêu cầu. Hãy xem lại các yêu cầu và giá cho một số trước khi sử dụng điểm cuối đặt hàng.

Đối với mua hàng, gán số, tin nhắn, gửi fax và các hành động khác, hãy làm theo quy tắc thử lại riêng của điểm cuối đó. Nếu một hành động hết thời gian chờ sau khi gửi, hãy kiểm tra trạng thái của nó hoặc hồ sơ tài khoản của bạn trước khi lặp lại. Phản hồi bị mất không chứng minh rằng hành động đã thất bại.