Liệt kê các khu vực cung cấp số của một quốc gia

Sau khi chọn quốc gia (và, đối với Hoa Kỳ hoặc Canada, có thể chọn thêm tiểu bang từ getstates), hãy gọi getareas để xem những khu vực có cung cấp số. Hãy lưu giá trị định danh khu vực uuid để dùng ở bước tiếp theo.

Mỗi khu vực dẫn đến một trong hai bước tiếp theo:

• available > 0: next_function là v3/getprefixes/{uuid}, với ?state= được nối thêm khi bạn đã lọc theo tiểu bang. Hãy dùng đường dẫn này để duyệt các đầu số.
• available = 0: khu vực có các đầu số nhưng không còn số trong kho, và next_function là v3/order/{uuid}. Xem tài liệu đặt số để biết các yêu cầu của bước này.

available là tổng số lượng trên toàn khu vực, ngay cả khi bạn lọc theo tiểu bang. Bộ lọc tiểu bang chấp nhận mã hoặc tên đầy đủ, nhưng chỉ áp dụng cho US và CA. Nếu việc lọc theo tiểu bang trả về No areas found, hãy thử lại mà không dùng bộ lọc này. Các kiểm tra được thực hiện theo thứ tự: thiếu mã quốc gia, quốc gia không xác định, bộ lọc tiểu bang dùng cho quốc gia khác, tiểu bang không hợp lệ, không có khu vực phù hợp. Mỗi trường hợp này đều trả về mã 500 hoặc 404 trong status.code, mà không kèm mã trạng thái HTTP tương ứng.

Yêu cầu

Bắt buộc: xác thực HTTP Basic hoặc mã thông báo Bearer (xem phần Xác thực và phản hồi API). Nếu xác thực thất bại, hệ thống trả về HTTP 401 trước khi thực hiện tra cứu.

Dùng GET với isocode trong đường dẫn và các tham số tùy chọn state và pid trong chuỗi truy vấn. Nếu bỏ qua đoạn đường dẫn này, hệ thống sẽ đọc trường isocode được mã hóa theo dạng biểu mẫu để thay thế.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Phản hồi

Dùng cấu trúc bao bọc tiêu chuẩn. Khi thành công, status.code là 200, status.msg là 'Results: N', status.results là N, và response là danh sách được sắp xếp theo tên khu vực. Các trường: uuid (mã định danh khu vực không cần diễn giải cấu trúc, dùng ở bước tiếp theo); country_uuid (mã định danh quốc gia gồm 32 ký tự, không cần diễn giải cấu trúc và không cần dùng về sau); name; area_type và number_type (các thuộc tính mô tả trong danh mục; các mục không nhất thiết thuộc loại số nội hạt); country_iso; is_mobile (0 hoặc 1, lấy từ các cờ di động của khu vực; luôn là 0 đối với US trừ khi tài khoản của bạn được bật quyền sử dụng số di động US); available (tổng số lượng còn trong kho của tất cả đầu số phù hợp trong khu vực, không giới hạn ở tiểu bang được yêu cầu); sms_coverage (0 hoặc 1); returns_numbers (0 hoặc 1, là giá trị cờ cao nhất trong số các đầu số của khu vực); latitude và longitude; state_iso; next_function. state_iso: khi có bộ lọc tiểu bang, đây là mã được xác định từ bộ lọc. Đối với US và CA khi không có bộ lọc, đây là mã của tiểu bang có tên trùng với tên khu vực; nếu không có, dùng giá trị đã lưu của khu vực; nếu vẫn không có, dùng mã suy ra từ dữ liệu đầu số của khu vực. Đối với các quốc gia khác, đây là giá trị đã lưu và có thể rỗng. next_function là 'v3/getprefixes/{uuid}' (nối thêm '?state={code}' khi có lọc) khi available lớn hơn 0, nếu không thì là 'v3/order/{uuid}'. Các khu vực hoàn toàn không có đầu số phù hợp sẽ bị loại khỏi kết quả. Các khu vực có đầu số nhưng không còn số trong kho vẫn được trả về với available bằng 0.

Cấu trúc phản hồi chỉ mang tính minh họa; không phải dữ liệu tài khoản trực tiếp hay báo giá hiện tại.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

Lỗi

• 500: msg 'ISO Code parameter is required': isocode bị thiếu hoặc để trống. Đây là lỗi yêu cầu có thể khắc phục. Không đặt mã trạng thái HTTP tương ứng.
• 404: msg 'Error: no such country': mã quốc gia không được nhận biết. Không đặt mã trạng thái HTTP tương ứng.
• 404: msg 'State filter is only available for US and CA': giá trị state không rỗng đã được gửi cho một quốc gia khác. Không đặt mã trạng thái HTTP tương ứng.
• 404: msg 'Invalid state': state không phải mã hay tên được nhận biết của tiểu bang hoặc tỉnh thuộc quốc gia đó. Không đặt mã trạng thái HTTP tương ứng.
• 404: msg 'No areas found': không có khu vực nào phù hợp với các bộ lọc quốc gia, nguồn kho số và tiểu bang. Không đặt mã trạng thái HTTP tương ứng.
• 401: Thiếu thông tin xác thực hoặc xác thực thất bại. Được gửi kèm mã trạng thái HTTP 401.

Khả năng sử dụng và tác động phát sinh

• Chỉ thực hiện tra cứu cho tài khoản khách hàng. Thao tác này không giữ số, đặt số hay thay đổi bất cứ điều gì.
• available chỉ mang tính thông tin và có thể thay đổi trước bước tiếp theo.