切换主题
小程序登录凭证校验
GET /sns/jscode2session
微信 auth.code2Session 兼容入口。应用后端使用 AppID、AppSecret 和 wx.login 返回的一次性 code，换取应用内稳定的 openid 与仅保存在应用后端的 session_key。运行实例由平台从登录码内部恢复；平台尚无 UnionID 机制，因此不返回 unionid。
鉴权与参数
使用 HTTPS Query 中的 appid 和 secret 鉴权。完整 URL 含凭据，不得写入日志、报错或监控标签。
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
appid | query | 是 | 当前平台应用 App ID。 |
secret | query | 是 | 当前 AppSecret，只能由应用后端通过 HTTPS 提交且不得记录。 |
js_code | query | 是 | wx.login 返回的 5 分钟一次性登录码。 |
grant_type | query | 是 | 固定为 authorization_code。 |
请求体
无需请求体。
响应
HTTP 200
成功时返回 openid、session_key；失败时返回 errcode、errmsg。响应禁止缓存。
结构见完整定义。
完整定义
下列定义包含引用、Header 和字段约束，来自同一契约的本接口投影。
查看 JSON Schema 与响应定义
json
{
"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": {
"/sns/jscode2session": {
"get": {
"summary": "小程序登录凭证校验",
"description": "微信 auth.code2Session 兼容入口。应用后端使用 AppID、AppSecret 和 wx.login 返回的一次性 code，换取应用内稳定的 openid 与仅保存在应用后端的 session_key。运行实例由平台从登录码内部恢复；平台尚无 UnionID 机制，因此不返回 unionid。",
"tags": [
"runtime"
],
"security": [],
"operationId": "codeToSession",
"parameters": [
{
"name": "appid",
"in": "query",
"required": true,
"description": "当前平台应用 App ID。",
"schema": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]{2,63}$"
}
},
{
"name": "secret",
"in": "query",
"required": true,
"description": "当前 AppSecret，只能由应用后端通过 HTTPS 提交且不得记录。",
"schema": {
"type": "string",
"pattern": "^msec_[0-9a-f]{64}$",
"writeOnly": true
}
},
{
"name": "js_code",
"in": "query",
"required": true,
"description": "wx.login 返回的 5 分钟一次性登录码。",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"writeOnly": true
}
},
{
"name": "grant_type",
"in": "query",
"required": true,
"description": "固定为 authorization_code。",
"schema": {
"type": "string",
"const": "authorization_code"
}
}
],
"responses": {
"200": {
"description": "成功时返回 openid、session_key；失败时返回 errcode、errmsg。响应禁止缓存。",
"headers": {
"X-Request-ID": {
"$ref": "#/components/headers/RequestID"
}
},
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/CodeToSessionSuccess"
},
{
"$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": {
"headers": {
"RequestID": {
"description": "请求追踪 ID，用于关联客户端、网关和服务端日志。",
"schema": {
"type": "string",
"maxLength": 128
}
}
},
"schemas": {
"CodeToSessionSuccess": {
"type": "object",
"additionalProperties": false,
"required": [
"openid",
"session_key"
],
"properties": {
"openid": {
"type": "string",
"pattern": "^oid_[0-9a-f]{48}$",
"description": "本应用内稳定的用户标识；不同应用互不关联。"
},
"session_key": {
"type": "string",
"pattern": "^[A-Za-z0-9+/]{22}==$",
"readOnly": true,
"description": "标准 Base64 编码的 16 字节会话密钥，仅由应用后端保存。"
}
}
},
"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"
}
}
}
},
"securitySchemes": {
"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 正文逐行连接且正文后再加换行。"
}
}
}
}