Tìm số điện thoại hiện có

Chọn một tiền tố riêng lẻ

Sử dụng các lệnh gọi tra cứu quốc gia và khu vực trong danh mục, sau đó gọi getprefixes mà không nhóm kết quả. Sao chép giá trị của tiền tố đã chọn trong trường uuid. Nếu returns_numbers là 0, tiền tố này sẽ cấp số khi đặt mua; hãy sử dụng giá trị được trả về trong next_function thay vì yêu cầu danh sách các số riêng lẻ.

Duyệt một lô có giới hạn

Đối với tìm kiếm thông thường, hãy dùng compact=1 và đặt kích thước lô mong muốn trong cả đường dẫn lẫn tham số truy vấn quantity, như minh họa bên dưới. Không có tham số trang hoặc con trỏ. Kết quả rút gọn là một mẫu; việc lặp lại yêu cầu không bảo đảm sẽ nhận được trang tiếp theo không trùng lặp. Không được coi kết quả rỗng hoặc ít mục là tổng số lượng số trong kho.

Tìm mẫu chữ số dễ nhớ

Cung cấp number_filter_mode=contains hoặc ends_with cùng với number_filter_value. Giá trị phải chứa 1–15 chữ số. Quá trình tìm kiếm có thể lấy các lô số ứng viên có giới hạn trước khi áp dụng bộ lọc, nên có thể bỏ sót các số phù hợp khác trong kho. Nếu cần một nguồn có hỗ trợ để thực hiện tìm kiếm bắt buộc này, hãy lấy bộ chọn pid từ MultiTEL và dùng filter_required=1; nếu không chọn nguồn hoặc lựa chọn không được hỗ trợ, API sẽ trả về lỗi.

Xem xét số đã chọn

Đọc number, info.uuid, giá trị đã chọn của price[].uuid, tên các tính năng hiện có và các yêu cầu đăng ký từ cùng một kết quả. Mảng price có thể cung cấp nhiều gói cước với số lượng kênh và mức cước khác nhau. Các trường tiền tệ và số lượng có thể được mã hóa dưới dạng chuỗi. Siêu dữ liệu tùy chọn, bao gồm info.state, khác nhau giữa các nguồn; không yêu cầu một cấu trúc trường trạng thái chung cho mọi nguồn hoặc suy ra giá từ mã định danh.

Trong luồng xử lý không truyền dữ liệu liên tục, các số ứng viên được loại bỏ trùng lặp và phân bổ giữa các nguồn trước khi lô đã chọn được sắp xếp theo giá hằng tháng của gói cước đầu tiên. Các luồng xử lý khác có thể bắt đầu truyền dữ liệu sớm hơn, nên không có bảo đảm về thứ tự trên toàn bộ kết quả hoặc việc loại bỏ trùng lặp áp dụng cho mọi yêu cầu. Việc sắp xếp cũng không chứng minh rằng mẫu được trả về chứa số có giá rẻ nhất trong toàn bộ danh mục.

Đặt mua riêng và xác nhận kết quả

Việc tìm kiếm không mua hoặc giữ chỗ bất cứ thứ gì. Hãy lưu số và các mã định danh gói cước được trả về để dùng trong quy trình đặt mua bằng cùng tài khoản. Xem xét gói cước thực tế, các yêu cầu và khoản phí trước khi gửi đơn đặt mua. Các yêu cầu đăng ký có thể làm chậm việc kích hoạt; kết quả tìm kiếm không xác lập thời hạn kích hoạt cố định.

Yêu cầu

Sử dụng tài khoản API MultiTEL đã được kích hoạt: thông tin xác thực HTTP Basic cho tài khoản dùng mật khẩu, hoặc Authorization: Bearer cho tài khoản dùng mã thông báo. Các quyền và hạn chế IP của tài khoản được áp dụng. Xem hướng dẫn xác thực chung.

Tham số đường dẫn và tham số truy vấn URL. Sử dụng GET cho quy trình tìm kiếm công khai. Bộ xử lý cũng chấp nhận một số giá trị từ biểu mẫu/yêu cầu, nhưng đây không phải là API tìm kiếm nhận phần thân 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"

Phản hồi

Một đối tượng JSON chứa status và response. Khi thành công, status.code là 200 và response là một mảng các mục số điện thoại. status.results là số phần tử trong mảng được trả về; status.msg có thể là Results: N hoặc OK đối với phản hồi truyền dữ liệu liên tục. Khi không có compact=1, một số tìm kiếm ghi dần mảng response và kết thúc bằng status, vì vậy hãy đợi nhận đầy đủ phần thân JSON. Đây không phải là JSON phân tách bằng ký tự xuống dòng. Kiểm tra status.code ngay cả khi quá trình truyền qua HTTP thành công. Các trường điển hình được trình bày bên dưới; siêu dữ liệu đặc thù theo nguồn và các trường tùy chọn có thể khác nhau. Coi mọi mã định danh là giá trị không thể suy diễn ý nghĩa và lưu số cùng với price[].uuid đã chọn của số đó.

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

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

Lỗi

• 401: Xác thực thất bại. Thông tin xác thực không hợp lệ hoặc bị thiếu, cũng như việc truy cập tài khoản API bị từ chối, sẽ không tạo ra kết quả tìm kiếm.
• 404: Invalid prefix ID, Invalid country, Invalid area hoặc No numbers found. Đọc status.msg; phản hồi lỗi không phải là mảng số điện thoại.
• 400: NUMBER_FILTER_INVALID trong response.code: chế độ không hợp lệ, giá trị không phải là chuỗi 1–15 chữ số, hoặc filter_required không được cung cấp kèm đầy đủ cả chế độ và giá trị.
• 422: NUMBER_FILTER_UNSUPPORTED trong response.code: tiền tố cấp số vào thời điểm đặt mua (reason=order_only_prefix và next_function xác định tuyến đặt mua), hoặc nguồn được chọn rõ ràng không thể hỗ trợ bộ lọc bắt buộc.

Tình trạng sẵn có và tác động phụ

• Bộ xử lý này tìm kiếm và chuẩn bị báo giá; nó không gửi đơn đặt mua số hoặc ghi nợ khoản phí mua số. Nó có thể làm mới bộ nhớ đệm danh mục, xóa dữ liệu kho số đã lỗi thời trong bộ nhớ đệm, lưu các gói cước trong phạm vi tài khoản và ghi nhật ký tìm kiếm.
• Tình trạng sẵn có là kết quả tại một thời điểm, không phải là việc giữ chỗ. Đơn đặt mua sau đó có thể thất bại hoặc trả về tình trạng sẵn có khác. Đối chiếu kết quả đặt mua trước khi thử mua lại.
• Giá được áp dụng riêng cho từng tài khoản. Lưu mã định danh gói cước đã chọn để dùng với cùng tài khoản và xem xét riêng các điều khoản cùng khoản phí của đơn đặt mua; chỉ riêng điểm cuối này không chứng minh rằng giá sẽ còn hiệu lực cho đến lần đặt mua sau.
• Số và giá trong ví dụ là dữ liệu giả định để minh họa cấu trúc phản hồi, không phải báo giá trực tiếp. Phải đọc các tính năng, số lượng kênh, thời hạn và thông tin đăng ký từ kết quả thực tế đã chọn.
• Một số mô tả đăng ký chứa văn bản có định dạng hoặc liên kết. Hãy coi các chuỗi được trả về là dữ liệu không đáng tin cậy khi hiển thị chúng trong ứng dụng của bạn.
• Tình trạng sẵn có của số di động và các cờ phụ thuộc vào việc tài khoản có đủ điều kiện hay không và kho số. Chỉ riêng tiền tố trong danh mục hoặc cờ is_mobile không xác lập các tính năng di động của một số cụ thể.