手机号

由用户单次确认号码，小程序取得动态 code，业务后端兑换手机号。开始前核对下列平台条件，并配置业务兑换接口。

平台前置条件

当前手机号准入以关联 MetaEco 入驻核验的企业、政府、媒体或组织主体为条件。资格不足时通过“入驻与主体核验”办理，普通接入无需再提交旧独立功能申请；有效历史 Test 开通记录只适用于 Test。平台暂停或本应用停用手机号时仍阻断使用，恢复由平台按真实主体资格处理。

上传包声明 host-phone-number 或 phone.number 时，提交版本审核就会检查上述资格。未关联、未核验、主体记录异常或类型不符合会分别提示，失败不会生成待审轮次；批准、签名和发布仍会复核。个人主体通过入驻核验也不满足该非个人主体条件。

还须满足本应用普通接口白名单、当前已批准隐私指引中的实际手机号用途及用户同意。正式版要求 active；draft 应用的当前体验包也可使用，但签发与兑换时都要核对该用户仍具备本应用有效体验资格。包声明可使用当前工具输出的 host-phone-number，宿主每次让用户确认号码，不创建持久的手机号 scope。使用支持该流程的宿主版本，联调环境须有可用的短信验证配置。详见隐私指引与功能接入。

Test 本地开发调试有一项限定例外：宿主持有有效开发者调试凭证、调试包声明手机号权限时，draft 应用也可以在开发者本人主动确认后使用其 MetaEco 账号已绑定或经短信验证的真实号码；这一路径不要求非个人主体资格或已批准的隐私指引，不会替应用创建批准或同意记录。应用或平台明确停用手机号时仍不可用。普通上传版本和 Production 仍遵守上段条件；调试会话失效后，已签发但未兑换的 code 也会失效。

小程序调用

手机号能力使用与微信相同的 open-type="getPhoneNumber"。小程序只处理用户操作结果和动态 code，不接收明文手机号，也不调用平台宿主接口。

<button open-type="getPhoneNumber" bindgetphonenumber="onGetPhoneNumber">
  获取手机号
</button>

Page({
  onGetPhoneNumber(event) {
    if (event.detail.errMsg !== 'getPhoneNumber:ok') return
    const code = event.detail.code
    // 将 code 发送到本应用业务后端。
  }
})

code 是不透明动态凭证。小程序不得解析、校验格式或持久保存它。用户拒绝手机号授权不影响普通登录。

宿主授权面板会展示当前 MetaEco 账号绑定的号码。用户也可以在面板内自主添加经短信验证的其他号码，然后选择本次要授权的号码；邮箱注册用户即使尚未绑定账号手机号，也可以通过该入口添加号码。号码选择和验证由宿主完成，小程序不能提交、枚举或读取候选号码。

应用后端兑换

应用后端先按接口 token 指南使用 AppID 和 AppSecret 调用 /cgi-bin/token，确认成功后缓存 access_token，再兑换手机号。手机号 code 与 wx.login code 不可互换；它有效期为 5 分钟且只能消费一次：

本地开发调试仍使用相同流程。draft 应用可获取 token 并兑换本应用有效调试会话签发的 code；后端配置的 AppID/AppSecret 必须与当前小程序一致。后端不接收或传递 debug_session、宿主登录态或调试 token；会话失效、开发权限撤回、应用停用及跨应用 code 均拒绝兑换。

curl --request POST "$PLATFORM_ORIGIN/wxa/business/getuserphonenumber?access_token=$ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"code":"<getPhoneNumber 回调返回的 code>"}'

成功和失败都返回 HTTP 200，并使用微信的 errcode、errmsg 字段。以下号码是虚构示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "phone_info": {
    "phoneNumber": "13800000000",
    "purePhoneNumber": "13800000000",
    "countryCode": "86",
    "watermark": {
      "timestamp": 1780000000,
      "appid": "example-appid"
    }
  }
}

完整字段见兑换小程序手机号。AppSecret、access_token 和手机号只保存在应用后端，不得交给小程序或写入日志。

失败处理

errcode	处理
40014	access_token 无效，重新获取后重试
40029	动态 code 无效或已使用，让用户重新发起授权
48001	应用未进入普通接口白名单，联系平台联调负责人核查
-1	系统繁忙，保留请求 ID 并稍后重试

宿主中的脱敏号码列表、短信验证、号码选择、用户确认和动态凭证签发均由运行时内部完成，不属于小程序或应用后端协议。

预期结果与下一步

业务后端取得 phone_info 并校验 watermark.appid。用户拒绝或兑换失败时正常返回业务提示，不阻断普通登录。完成后在体验版分别测试确认、取消、过期和重复 code。