兑换小程序手机号

POST /wxa/business/getuserphonenumber

与微信 getuserphonenumber 保持相同的路径、鉴权、请求字段和响应字段。draft 应用仅能兑换本应用有效开发调试会话签发的 code，平台从 code 记录重新校验调试上下文，不接受业务后端传入调试凭证。应用未进入普通接口 allowlist 时返回 errcode 48001。

鉴权与参数

使用 HTTPS Query 中的 access_token 鉴权。完整 URL 含凭据，不得写入日志、报错或监控标签。

参数	位置	必填	说明
access_token	query	是

请求体

Content-Type：application/json。

字段	类型	在所属对象中必填	说明与约束
code	string	是	minLength: 1；maxLength: 256

响应

HTTP 200

原始微信格式手机号或错误响应。

结构见完整定义。

完整定义

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

查看 JSON Schema 与响应定义

{
  "openapi": "3.1.0",
  "info": {
    "title": "MetaEco 应用服务端 API",
    "version": "40.68.0"
  },
  "servers": [
    {
      "url": "{platformOrigin}",
      "description": "导入后填写实际 API 入口；文档域名不承载 API",
      "variables": {
        "platformOrigin": {
          "default": "https://api.example.invalid",
          "description": "替换为当前应用分配的 API 网关，示例域名不可访问"
        }
      }
    }
  ],
  "paths": {
    "/wxa/business/getuserphonenumber": {
      "post": {
        "summary": "兑换小程序手机号",
        "description": "与微信 getuserphonenumber 保持相同的路径、鉴权、请求字段和响应字段。draft 应用仅能兑换本应用有效开发调试会话签发的 code，平台从 code 记录重新校验调试上下文，不接受业务后端传入调试凭证。应用未进入普通接口 allowlist 时返回 errcode 48001。",
        "tags": [
          "wechat-compat"
        ],
        "security": [
          {
            "wechatAccessToken": []
          }
        ],
        "operationId": "getWeChatCompatiblePhoneNumber",
        "parameters": [
          {
            "$ref": "#/components/parameters/WeChatAccessToken"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WeChatPhoneRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "原始微信格式手机号或错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/WeChatPhoneResponse"
                    },
                    {
                      "$ref": "#/components/schemas/WeChatError"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "metaEcoBalancePaymentEvent": {
      "post": {
        "summary": "平台向应用后端投递余额支付或退款成功通知",
        "description": "平台向创建支付单时固化的 notify_url 或退款单独指定的 notify_url 发送 HTTPS JSON；同一资金终态对应稳定事件 ID，至少一次投递。接收方必须先使用本应用受信任的 MetaEco 通知公钥验证原始正文，再核对 AppID、业务订单号和金额，并使用应用接口 token 查单确认。成功及已幂等处理的事件应在 5 秒内返回任意 2xx；超时或非 2xx 按退避策略最多尝试 10 次，之后进入死信。重投可有新的时间戳、nonce 和签名，事件正文及 ID 不变。此协议不是微信支付 API v3 通知。",
        "operationId": "receiveMetaEcoBalancePaymentEvent",
        "security": [
          {
            "metaEcoNotificationSignature": []
          }
        ],
        "parameters": [
          {
            "name": "X-MetaEco-Event-ID",
            "in": "header",
            "required": true,
            "description": "必须与正文 id 相同，跨重试不变。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-MetaEco-Key-ID",
            "in": "header",
            "required": true,
            "description": "选择验签公钥，并作为签名串第一行。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-MetaEco-Timestamp",
            "in": "header",
            "required": true,
            "description": "当前投递生成的十进制 Unix 秒；接收方允许的时钟偏差为前后 5 分钟。",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            }
          },
          {
            "name": "X-MetaEco-Nonce",
            "in": "header",
            "required": true,
            "description": "当前投递生成的随机字符串。",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 64
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/MetaEcoPaymentSucceededEvent"
                  },
                  {
                    "$ref": "#/components/schemas/MetaEcoRefundSucceededEvent"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "验签并持久化处理或已幂等处理；任何 2xx 均表示确认接收。"
          },
          "204": {
            "description": "验签并持久化处理或已幂等处理；没有响应正文。"
          },
          "400": {
            "description": "通知字段、身份或金额校验失败；平台会重试至死信。"
          },
          "401": {
            "description": "签名、公钥 ID 或时间窗校验失败；平台会重试至死信。"
          },
          "503": {
            "description": "接收方暂时不可用；平台会重试至死信。"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "wechatAccessToken": {
        "type": "apiKey",
        "in": "query",
        "name": "access_token",
        "description": "GET /cgi-bin/token 返回的两小时应用后端 token。"
      },
      "metaEcoNotificationSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-MetaEco-Signature",
        "description": "Base64 编码的 RSA PKCS#1 v1.5 + SHA-256 签名；签名串为 X-MetaEco-Key-ID、X-MetaEco-Timestamp、X-MetaEco-Nonce、原始 UTF-8 正文逐行连接且正文后再加换行。"
      }
    },
    "parameters": {
      "WeChatAccessToken": {
        "name": "access_token",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "writeOnly": true
        }
      }
    },
    "schemas": {
      "WeChatPhoneRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "writeOnly": true
          }
        }
      },
      "WeChatPhoneResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "errcode",
          "errmsg",
          "phone_info"
        ],
        "properties": {
          "errcode": {
            "type": "integer",
            "const": 0
          },
          "errmsg": {
            "type": "string",
            "const": "ok"
          },
          "phone_info": {
            "type": "object",
            "required": [
              "phoneNumber",
              "purePhoneNumber",
              "countryCode",
              "watermark"
            ],
            "properties": {
              "phoneNumber": {
                "type": "string",
                "description": "用户绑定的手机号；中国大陆号码不带国家码，境外号码带国家码。"
              },
              "purePhoneNumber": {
                "type": "string",
                "description": "不带国家码的手机号。"
              },
              "countryCode": {
                "type": "string"
              },
              "watermark": {
                "type": "object",
                "required": [
                  "timestamp",
                  "appid"
                ],
                "properties": {
                  "timestamp": {
                    "type": "integer"
                  },
                  "appid": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "WeChatError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "errcode",
          "errmsg"
        ],
        "properties": {
          "errcode": {
            "type": "integer",
            "description": "微信兼容数字错误码；-1 表示系统繁忙。"
          },
          "errmsg": {
            "type": "string"
          }
        }
      },
      "MetaEcoPaymentSucceededEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "create_time",
          "event_type",
          "resource"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "稳定事件 ID，重复投递时不变。"
          },
          "create_time": {
            "type": "string",
            "format": "date-time"
          },
          "event_type": {
            "type": "string",
            "const": "TRANSACTION.SUCCESS"
          },
          "resource": {
            "$ref": "#/components/schemas/MetaEcoPaymentSucceededResource"
          }
        }
      },
      "MetaEcoPaymentSucceededResource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "app_id",
          "order_id",
          "business_type",
          "business_order_no",
          "transaction_id",
          "amount_minor",
          "currency",
          "paid_at",
          "status"
        ],
        "properties": {
          "app_id": {
            "type": "string"
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_type": {
            "type": "string",
            "enum": [
              "trade",
              "shop"
            ]
          },
          "business_order_no": {
            "type": "string"
          },
          "transaction_id": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "const": "CNY"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "const": "paid"
          }
        }
      },
      "MetaEcoRefundSucceededEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "create_time",
          "event_type",
          "resource"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "稳定事件 ID，重复投递时不变。"
          },
          "create_time": {
            "type": "string",
            "format": "date-time"
          },
          "event_type": {
            "type": "string",
            "const": "REFUND.SUCCESS"
          },
          "resource": {
            "$ref": "#/components/schemas/MetaEcoRefundSucceededResource"
          }
        }
      },
      "MetaEcoRefundSucceededResource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "app_id",
          "order_id",
          "business_type",
          "business_order_no",
          "transaction_id",
          "amount_minor",
          "currency",
          "paid_at",
          "refund_id",
          "business_refund_no",
          "refund_amount_minor",
          "refunded_at",
          "status"
        ],
        "properties": {
          "app_id": {
            "type": "string"
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_type": {
            "type": "string",
            "enum": [
              "trade",
              "shop"
            ]
          },
          "business_order_no": {
            "type": "string"
          },
          "transaction_id": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "const": "CNY"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "refund_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_refund_no": {
            "type": "string"
          },
          "refund_amount_minor": {
            "type": "integer",
            "minimum": 1
          },
          "refunded_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "const": "refunded"
          }
        }
      }
    }
  }
}

返回 API 目录