身份验证与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`	API结果代码，例如 `200`、 `401`、 `404` 或 `500`。
`status.msg`	人类可读的消息。它可以为空。程序逻辑应以 `status.code` 为依据，而不是消息文本。
`status.results`	条目数。对于此处记录的发现端点，在以下情况下存在： `response` 是JSON列表，包括空列表（`0`）。在以下情况下缺失： `response` 为空字符串或 `null`。其他端点负载可能以不同方式报告计数；请遵循其各自的响应文档。
`response`	端点负载。其类型取决于端点和结果。出错时为空字符串。

错误响应如下所示：

{
  "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）刷新目录详细信息并为您的帐户保存价格报价，但它不会下订单。任何发现请求都不会预留号码，并且库存可能在请求之间发生变化。在使用订购端点之前，请查看号码的要求和价格。

对于购买、分配、消息、传真发送和其他操作，请遵循该端点自身的重试规则。如果操作在提交后超时，请在重复之前检查其状态或您的帐户记录。丢失的响应并不证明操作失败。