手机号

前置条件与状态

手机号采用独立的一次性 code，与登录码和标准 scope 分离。版本须声明 phone.number，平台已启用相应能力，用户在原生界面明确同意，并且宿主具有当前绑定号码的验证证明。

服务端与受控 Test 模拟链路已验证；真实短信和双端原生 UI 尚待验收。不要将模拟成功视为真实手机号验证。

调用流程

1. 小程序在需要号码的场景发起交互，宿主说明用途并取得用户同意。
2. 宿主完成当前绑定手机号验证，由平台签发绑定 App ID 的手机号 code。
3. 小程序把 code 发往自己的业务后端；业务后端持本应用服务凭据兑换。
4. 业务后端按用途处理结果，仅向前端返回业务所需内容。

手机号 code 有效期 5 分钟且只能兑换一次；格式为 mp_phone_ 加 64 位十六进制字符。短信验证码、登录码不能用于此接口。SDK 方法名与事件参数以双端联调版本为准。

应用后端兑换

curl --request POST "$PLATFORM_ORIGIN/miniapp/v1/apps/$APP_ID/phone-number" \
  --header "Authorization: Bearer $APP_SERVICE_CREDENTIAL" \
  --header 'Content-Type: application/json' \
  --data '{"code":"<本次手机号code>"}'

成功返回 200。以下号码是虚构示例：

{
  "code": "miniapp_success",
  "data": {
    "phone_info": {
      "phoneNumber": "8613800000000",
      "purePhoneNumber": "13800000000",
      "countryCode": "86"
    },
    "verification_method": "sms"
  }
}

verification_method 为 mock 时只能用于测试，不能建立已验证真实号码的业务结论。完整参考见兑换手机号。

失败与重试

错误码	处理
miniapp_phone_code_invalid	code 已消费、过期或策略不满足；检查版本/应用资格，重新交互取得 code
miniapp_phone_verification_required	宿主完成当前绑定号码核验后再申请
miniapp_phone_unavailable	依赖暂不可用，保留请求 ID，提示稍后重试

请求不能指定目标用户或号码，也不接受额外 query 参数。拒绝提供手机号不影响普通登录。号码和 code 不写入日志；超时后不要盲目重复兑换同一个 code。