MultiTEL
开发者

POST/v3/number_identity/{number}

提交号码注册资料

将已保存的注册资料关联到已购买的号码，并在受支持的情况下请求运营商审核。

本页
  1. 准备已保存的资料和号码
  2. 提交关联请求
  3. 区分关联与批准
  4. 处理错误，避免创建重复任务
  5. 一次性文件限制
  6. 保护注册信息

准备已保存的资料和号码

使用此流程将已保存的注册资料关联到已购买的号码，并为受支持的运营商号码请求注册审核。此接口并非适用于所有号码提供商的通用激活 API。请求成功不代表文件已获批准，也不代表号码已激活。

使用已启用的 MultiTEL API 账户，通过 HTTPS 访问，并遵循该账户配置的凭据和 IP 限制。未被删除的资料以及已购买且未作废的号码都必须属于您的账户。

  1. 创建一份注册资料，或选择现有资料。请保留从 create_document 获取的本地资料 uuid；get_document 会以 id 的形式返回同一本地引用。
  2. 向运营商提交时，资料中必须包含已保存的身份和地址引用。提交前，请通过相应流程附上所需的证明材料和补充文件。
  3. 检查号码和资料是否符合相关国家及号码的要求。不要认为已保存的资料就已获准用于所有号码。

提交关联请求

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

路径中应填写已购买的电话号码，而非其 UUID、PBX 分机号或身份 ID。处理程序会移除号码中的非数字字符。请使用包含国家代码的完整国际号码。示例为虚构内容，必须替换为您自己的号码和已保存的本地资料引用。

注册提交字段
字段是否必填含义
document_uuid是已保存的本地资料的准确 uuid。不要用经过掩码处理的远程 identity_id、address_id、上传 ID 或返回的 registration_details_id 值替代。
service_description否对预期服务的描述，会转交给运营商进行验证。开头和结尾的空格会被移除。
onetime_files取决于工作流程用于运营商一次性文件的数组。当前处理程序会移除数组内字符串首尾的空白并直接转发，不会解析本地上传引用。尚未确认其与 create_encrypt_files 返回的掩码 ID 是否兼容；使用此字段前，请先查看下方的一次性文件限制说明。

对于多部分请求，数组通过重复的 onetime_files[] 字段传入。也接受带有 Content-Type: application/json 的 JSON 请求，其属性会合并到表单载荷中。省略路径中的号码时，可以在载荷中提供 number。为避免歧义，建议使用上方明确指定号码的路径。

区分关联与批准

请同时查看 HTTP 结果和 JSON 中的 status.code。即使 HTTP 状态为 200，JSON 中也可能包含错误。运营商处理成功时会报告：Address verification task created; awaiting carrier review. 此示例使用虚构引用。

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

与提供商相关的标识符是经过掩码处理的引用，并不是可以相互替换的本地资料 ID。document_uuid 仍是您提交的本地资料引用。在此处理程序的运营商处理分支中，registration_details_id 是对该本地引用进一步进行哈希运算得到的值；后续资料请求或提交请求中，不要用它替换 document_uuid。

部分已分配号码仅在本地关联身份，而不会创建运营商验证任务。成功时返回 Identity associated.，并附带空的 response 数组。这不会创建运营商审核任务，也不代表已获批准。门户中有较新的关联流程，其提供商处理方式和重复提交检查与此端点不同。

处理错误，避免创建重复任务

API 代码 400 表示缺少号码或资料引用。代码 404 表示账户无法使用该资料或号码，或运营商库存中没有该号码。代码 422 可能报告缺少身份或地址引用、卖方要求或运营商验证拒绝。缺少回调配置可能产生 503，创建任务时的传输失败可能产生 502。请阅读消息以及任何 requirement_diagnostics，不要以相同方式处理所有失败。

运营商处理分支可能在要求验证、回调配置检查或任务创建完成之前，就更新本地的待注册标记。因此，出现错误并不意味着本地状态未发生变化，仅有待处理标记也不能证明任务存在。不要将这些标记视为已获批准或请求已送达的确认。

即使后续本地数据库操作失败，提供商也可能已接受任务；此辅助函数在报告成功前，并不会检查每一次本地写入的结果。此处理程序没有客户端幂等性参数，也没有防止重复提交的机制。遇到超时、错误或不确定的结果后，请先在门户中查看该号码的注册历史，或联系支持团队，再决定是否重新提交。仅凭本地记录缺失，不能证明提供商未收到任何内容。

一次性文件限制

处理程序接受 onetime_files，并将每个非空字符串转发到运营商的加密文件关联中。它不会查询所属账户的上传记录，也不会将外部掩码上传 ID 转换为提供商的文件 ID。离线审计验证的是转发行为，并未验证文件是否成功附加到运营商端。

不要认为将 create_encrypt_files 返回的文件 ID 复制到此字段，就能完成一次性协议流程。号码需要这些文件时，请使用门户，或向 MultiTEL 确认受支持的标识符使用流程。这仍是 API 审查中尚未解决的部分，并非经过端到端验证的示例。

保护注册信息

仅提交您有权用于该号码的信息和文件。确保资料及验证引用关联到正确的账户，并避免在日志中记录完整的注册载荷。此请求不会删除或替换所有先前的证明材料或验证记录。运营商审核、激活和数据保留是彼此独立的流程。