MultiTEL
开发者

POST/v3/directory/{number}

提交电话号码目录条目

提交经授权的运营商目录条目，了解当前实现的收费，并在重试前核对不确定的结果。

本页
  1. 提交运营商目录条目
  2. 账户和号码要求
  3. 表单 POST 请求
  4. 收费和重试行为
  5. 响应
  6. 旧版错误
  7. 重试前先核实

提交运营商目录条目

为您在 MultiTEL 中拥有且符合条件的电话号码提交目录条目所用的姓名和地址。这是一项付费的运营商更新，并非来电者姓名查询、私人通讯录条目，也不是对门户中 LIDB 库存字段的一般更新。

仅提交客户已授权用于目录条目的信息。使用此旧版路由前，请确认运营商支持该号码。经审查的处理程序不会验证服务提供商是否符合条件，也不会验证国际号码格式；它向运营商发送请求时会假定这是北美号码，并移除所存号码的首位数字。

账户和号码要求

请从获准的源 IP 地址通过 HTTPS 使用已启用的 API 账户。该确切号码必须对应此账户下未作废的已购号码记录。请使用库存中完整的国际号码数字，例如受支持北美号码采用国家代码为 1 的格式。请勿使用资费方案标识、号码的 UUID 或属于其他账户的号码。

表单 POST 请求

请将 NUMBER 设为您拥有的号码。请将虚构示例替换为已获授权的目录条目信息。此路由从 POST 中读取表单字段，不会解析 application/json 请求体。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "lastname=EXAMPLE" \
  --data-urlencode "firstname=EXAMPLE" \
  --data-urlencode "streetnum=1" \
  --data-urlencode "streetname=Example" \
  --data-urlencode "streetpredir=N" \
  --data-urlencode "streetpostdir=W" \
  --data-urlencode "city=Example City" \
  --data-urlencode "state=NY" \
  --data-urlencode "postalcode=10001" \
  "https://api.multitel.net/v3/directory/$NUMBER"
目录条目表单字段
字段此 API 是否要求必填含义
lastname是目录条目中的姓氏，或适用的条目名称字段。
city是目录条目中的城市。
postalcode是目录条目中的邮政编码。
state是目录条目中的州或地区，须为受支持运营商所接受的值。
streetname是街道名称。
streetnum是门牌号。
firstname否附加的名字部分。
streetpredir, streetpostdir否适用时，街道名称前后的方位部分。
streettype, location否适用时，街道类型或附加位置说明。

示例中的方位和地址仅为占位内容，并非推荐使用的邮寄地址。请勿向真实客户数据添加虚构方位。API 的必填字段检查较为简单，不能据此确定地址有效或已被运营商接受；旧版网站采用的表单要求也有所不同。

当可选的方位部分缺失或为空时，当前实现可能会发出数组键缺失警告。如果响应格式异常或运营商拒绝该地址，请保留请求参考信息并联系支持人员确认目录条目，不要凭猜测修改地址后反复提交。

收费和重试行为

经审查的处理程序会先检查账户余额是否至少有 10.00 个余额单位，然后才联系运营商。运营商和本地号码更新均报告成功后，程序会从账户余额中扣除 10.00，并记录一笔目录设置交易。这些是当前实现采用的金额，并非新的定价提案；提交前，请根据账户条款确认适用的计费币种和受支持的服务。

此操作没有幂等键、重复订单防护，也没有涵盖运营商提交、本地更新和计费的事务。重复请求若成功，可能再次向运营商提交并再次收费。超时或 API 错误并不能证明运营商拒绝了先前的请求：本地更新失败前，服务提供商可能已经接受了请求。

响应

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": ""
}

正常的成功响应包含值为空字符串的 response，不会返回目录条目标识或完成详情。这表示运营商处理流程和本地更新流程均报告成功，并不证明条目已在所有外部目录中发布、已立即传播，或今后会显示在来电显示中。

旧版错误

目录条目 API 结果代码
API 代码含义
404账户中未找到该号码，或某个必填表单字段为空。
400账户余额低于当前实现收取的费用。
500运营商请求失败，或本地更新失败，而此时运营商可能已经接受了请求。
200已报告成功；响应不包含发布确认。

请同时查看 HTTP 状态及 JSON 中的 status.code/status.msg。身份验证和源 IP 限制也可能导致无法获得可用响应。请勿仅因旧版处理程序没有明确的 HTTP 方法检查，就使用 GET 或查询参数请求更新。

重试前先核实

  1. 发送请求前，请确认号码属于您、运营商符合条件、目录条目数据已获授权，并确认收费。
  2. 仅提交一次并保留账户侧的结果，不要在公开日志或分析数据中暴露客户地址。
  3. 通过受支持的账户操作流程或支持人员，检查已保存的目录条目和交易历史。请预留运营商确认的处理时间；此 API 未规定有保证的传播完成期限。
  4. 结果不确定时，请先让支持人员核对运营商订单和本地计费，再尝试重试。重复提交请求并不是幂等的状态查询。