应用后端兑换手机号

POST /miniapp/v1/apps/{app_id}/phone-number

手机号独立于scope和登录会话。code为5分钟一次性凭证，绑定AppID与当前号码验证证明；模拟号码仅允许Dev/Test白名单应用testing版本及有效测试资格，签发和兑换均检查。宿主确认只能在原生用户同意后执行。请求不接受目标用户/号码或额外query参数。服务未配置时失败关闭。

鉴权与参数

应用后端使用 Authorization: Bearer <本应用服务凭据>。

参数	位置	必填	说明
`app_id`	path	是	{"type":"string","pattern":"^[a-z][a-z0-9_-]{2,63}$"}

请求体

Content-Type：application/json。

字段	类型	在所属对象中必填	说明与约束
`code`	string	是	pattern: ^mp_phone_[a-f0-9]{64}$

响应

HTTP 200

手机号操作成功；mock仅用于测试。

字段	类型	在所属对象中必填	说明与约束
`code`	string	是	description: 请求成功时返回的稳定业务码。；const: miniapp_success
`data`	object	是
`data.phone_info`	object	是
`data.phone_info.phoneNumber`	string	是
`data.phone_info.purePhoneNumber`	string	是
`data.phone_info.countryCode`	string	是
`data.verification_method`	string	是	enum: ["sms","mock"]

HTTP 400

请求参数无效。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 401

服务凭据或运行时会话无效。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 403

权限不足或能力调用被拒绝。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 503

依赖的适配器或存储不可用。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

完整定义

下列定义包含引用、Header 和字段约束，来自同一契约的本接口投影。

查看 JSON Schema 与响应定义

json

{
  "openapi": "3.1.0",
  "info": {
    "title": "MetaEco 应用服务端 API",
    "version": "6.0.0"
  },
  "servers": [
    {
      "url": "{platformOrigin}",
      "description": "导入后填写实际 API 入口；文档域名不承载 API",
      "variables": {
        "platformOrigin": {
          "default": "https://api.example.invalid",
          "description": "替换为当前应用分配的 API 网关，示例域名不可访问"
        }
      }
    }
  ],
  "paths": {
    "/miniapp/v1/apps/{app_id}/phone-number": {
      "post": {
        "summary": "应用后端兑换手机号",
        "description": "手机号独立于scope和登录会话。code为5分钟一次性凭证，绑定AppID与当前号码验证证明；模拟号码仅允许Dev/Test白名单应用testing版本及有效测试资格，签发和兑换均检查。宿主确认只能在原生用户同意后执行。请求不接受目标用户/号码或额外query参数。服务未配置时失败关闭。",
        "tags": [
          "runtime"
        ],
        "security": [
          {
            "serviceCredential": []
          }
        ],
        "operationId": "exchangePhoneNumber",
        "parameters": [
          {
            "$ref": "#/components/parameters/AppID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneCodeExchange"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/PhoneExchanged"
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/RuntimeUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "serviceCredential": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "MiniAppServiceCredential",
        "description": "小程序运行时和内部服务调用使用的短期服务凭据。"
      }
    },
    "parameters": {
      "AppID": {
        "name": "app_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_-]{2,63}$"
        }
      }
    },
    "schemas": {
      "PhoneCodeExchange": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^mp_phone_[a-f0-9]{64}$"
          }
        }
      },
      "SuccessCode": {
        "type": "string",
        "const": "miniapp_success",
        "description": "请求成功时返回的稳定业务码。"
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "PhoneExchanged": {
        "description": "手机号操作成功；mock仅用于测试。",
        "headers": {
          "Cache-Control": {
            "schema": {
              "type": "string",
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "code",
                "data"
              ],
              "properties": {
                "code": {
                  "$ref": "#/components/schemas/SuccessCode"
                },
                "data": {
                  "type": "object",
                  "required": [
                    "phone_info",
                    "verification_method"
                  ],
                  "properties": {
                    "phone_info": {
                      "type": "object",
                      "required": [
                        "phoneNumber",
                        "purePhoneNumber",
                        "countryCode"
                      ],
                      "properties": {
                        "phoneNumber": {
                          "type": "string"
                        },
                        "purePhoneNumber": {
                          "type": "string"
                        },
                        "countryCode": {
                          "type": "string"
                        }
                      }
                    },
                    "verification_method": {
                      "type": "string",
                      "enum": [
                        "sms",
                        "mock"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "请求参数无效。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RuntimeUnauthorized": {
        "description": "服务凭据或运行时会话无效。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "权限不足或能力调用被拒绝。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "依赖的适配器或存储不可用。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}

返回 API 目录

应用后端兑换手机号 ​

鉴权与参数 ​

请求体 ​

响应 ​

HTTP 200 ​

HTTP 400 ​

HTTP 401 ​

HTTP 403 ​

HTTP 503 ​

完整定义 ​