{ "openapi": "3.0.3", "info": { "title": "店铺开放 API · 兼容共享协议", "version": "213.0", "description": "服务端表单 POST 接口。新 SDK 默认 v2 HMAC-SHA256：绑定方法、标准路径、120 秒时间窗口、nonce 与 RFC3986 规范表单。旧 MD5 仅用于兼容，可在迁移后关闭。" }, "servers": [ { "url": "/", "description": "部署此文档的站点根地址" } ], "paths": { "/shared/authentication/connect": { "post": { "operationId": "connect", "summary": "连接与余额", "description": "验证商户 ID、签名及当前余额。只读，不扣款。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "shopName": { "type": "string" }, "balance": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "shopName": "示例商店", "balance": "100.00" } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/items": { "post": { "operationId": "items", "summary": "分类与商品列表", "description": "返回分类数组，每个分类的 children 是商品。无分页参数；数组可能为空。仅包含分类启用、商品上架且开放 API，并通过会员可见性检查的商品。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "additionalProperties": true } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": [ { "id": 1, "name": "邮箱账号", "children": [ { "id": 101, "code": "MAIL-DEMO", "name": "示例邮箱", "factory_price": 0.035, "api_status": 1, "status": 1, "minimum": 1, "maximum": 100, "delivery_way": 0, "draft_status": 0, "config": "", "widget": null } ] } ] } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/item": { "post": { "operationId": "item", "summary": "单个商品详情", "description": "仍返回“分类 → children”结构，不是单个平铺对象。使用商品 code，不使用本地商品 ID 或上游 shared_code。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "sharedCode": { "type": "string", "description": "商品 code；注意是驼峰名称" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "sharedCode" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "additionalProperties": true } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": [ { "id": 1, "name": "邮箱账号", "children": [ { "code": "MAIL-DEMO", "name": "示例邮箱", "factory_price": 0.035, "config": "", "widget": null } ] } ] } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/inventory": { "post": { "operationId": "inventory", "summary": "库存与价格", "description": "下单前刷新库存。count 为库存提示，不是锁库承诺；手动发货商品可能返回 99999，不代表真实卡密数。多种类价格见 config.category_factory，勿将 factory_price=0 误作免费。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "sharedCode": { "type": "string", "description": "商品 code" }, "race": { "type": "string", "description": "种类键，无种类传空字符串" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "sharedCode" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "delivery_way": { "type": "integer" }, "draft_status": { "type": "integer" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "user_price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "factory_price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "config": { "type": "string" }, "is_category": { "type": "boolean" } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "count": 100, "delivery_way": 0, "draft_status": 0, "price": 0.3, "user_price": 0.25, "factory_price": 0.035, "is_category": false, "config": "" } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/inventoryState": { "post": { "operationId": "inventoryState", "summary": "购买数量预检", "description": "校验当前库存及可选卡密。成功仅代表本次预检通过，实际下单仍可能因库存变化失败。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "shared_code": { "type": "string", "description": "商品 code；此接口使用下划线" }, "num": { "type": "integer", "description": "购买数量，正整数", "minimum": 1 }, "card_id": { "type": "integer", "description": "无预选传 0", "minimum": 0 }, "race": { "type": "string", "description": "无种类传空字符串" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "shared_code", "num" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "array", "items": {} } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": [] } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/draftCard": { "post": { "operationId": "draftCard", "summary": "预选卡密列表", "description": "仅用于 draft_status=1 的商品。返回预选说明和卡 ID，不返回未购买的卡密。返回分页字段以服务端为准。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "sharedCode": { "type": "string", "description": "商品 code" }, "page": { "type": "integer", "description": "页码，建议从 1 开始", "minimum": 1 }, "limit": { "type": "integer", "description": "每页数量，建议 20", "minimum": 1 }, "race": { "type": "string", "description": "无种类传空字符串" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "sharedCode", "page", "limit" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "draft": { "type": "string" } } } }, "total": { "type": "integer" }, "current_page": { "type": "integer" } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "current_page": 1, "data": [ { "id": 42, "draft": "示例预选说明" } ], "total": 1 } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/trade": { "post": { "operationId": "trade", "summary": "创建并付款", "description": "使用商户余额支付，成功即可能扣款。商品 widget 额外字段按名称平铺提交并一起签名。request_no 是接入建议的必填项；旧服务端并未实现严格的并发幂等承诺。超时必须先查原单，不能自动重下。 request_no 只能为1–64位受限 ASCII，不能为0；服务端采购前校验。", "tags": [ "订单" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "shared_code": { "type": "string", "description": "商品 code" }, "num": { "type": "integer", "description": "购买数量，正整数", "minimum": 1 }, "request_no": { "type": "string", "description": "接入方业务单号，建议 商户ID-UUID；防止重复提交", "minLength": 1, "maxLength": 64, "pattern": "^(?!0$)[A-Za-z0-9][A-Za-z0-9_-]{0,63}$" }, "contact": { "type": "string", "description": "联系方式；根据商品要求填写" }, "card_id": { "type": "integer", "description": "无预选传 0", "minimum": 0 }, "device": { "type": "integer", "description": "设备标识，默认 0", "minimum": 0 }, "password": { "type": "string", "description": "查单密码，默认空" }, "race": { "type": "string", "description": "商品种类键，默认空" }, "from": { "type": "integer", "description": "默认 0", "minimum": 0 }, "coupon": { "type": "string", "description": "必须为空，优惠券已停用" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "shared_code", "num", "request_no", "contact" ], "additionalProperties": true, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "amount": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "tradeNo": { "type": "string" }, "secret": { "type": "string", "nullable": true, "description": "可能为空或处理中提示，不用作完成判定" } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "url": null, "amount": 0.04, "tradeNo": "905488631289636187", "secret": "示例交付内容" } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/integration212/orderStatus": { "post": { "operationId": "orderStatus", "summary": "准确查询发货状态", "description": "v212 新增只读接口，只返回当前商户自己的订单；不触发采购、补单、退款或同步。state=delivered 才交付 secret。pending 时 secret=null；服务类商品的 secret 可能是完成说明，不一定为账号密码。 标记已发货但内容为空返回 attention 和 result_available=false。", "tags": [ "订单" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "trade_no": { "type": "string", "description": "本站订单号；与 request_no 二选一", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]{1,32}$" }, "request_no": { "type": "string", "description": "接入方业务单号；与 trade_no 二选一", "minLength": 1, "maxLength": 64, "pattern": "^(?!0$)[A-Za-z0-9][A-Za-z0-9_-]{0,63}$" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign" ], "additionalProperties": false, "oneOf": [ { "required": [ "trade_no" ], "not": { "required": [ "request_no" ] } }, { "required": [ "request_no" ], "not": { "required": [ "trade_no" ] } } ], "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "required": [ "trade_no", "request_no", "payment_status", "delivery_status", "state", "secret", "next_poll_seconds", "result_available" ], "properties": { "trade_no": { "type": "string" }, "request_no": { "type": "string" }, "payment_status": { "type": "integer", "description": "1 已付款，其他值不当作付款成功" }, "delivery_status": { "type": "integer", "description": "1 本站已完成交付" }, "state": { "type": "string", "enum": [ "unpaid", "pending", "delivered", "attention" ] }, "amount": { "type": "string" }, "currency": { "type": "string", "enum": [ "CNY" ] }, "quantity": { "type": "integer" }, "secret": { "type": "string", "nullable": true, "description": "仅 delivered 时返回交付内容；服务商品可能为完成说明" }, "next_poll_seconds": { "type": "integer", "nullable": true, "description": "pending 为 5；其他状态为 null" }, "result_available": { "type": "boolean" } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "trade_no": "905488631289636187", "request_no": "1001-demo-001", "payment_status": 1, "delivery_status": 1, "state": "delivered", "amount": "0.04", "currency": "CNY", "quantity": 1, "secret": "example@example.com----EXAMPLE_ONLY", "next_poll_seconds": null, "result_available": true } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/query": { "post": { "operationId": "query", "summary": "旧版按本站单号查询", "description": "status 是付款状态，不能当作发货完成。旧接口可能返回处理中提示；新接入使用 orderStatus。widget 结构与商品有关，不应对外直接展示内部字段。", "tags": [ "订单" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "tradeNo": { "type": "string", "description": "本站订单号，驼峰", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]{1,32}$" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "tradeNo" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "status": { "type": "integer", "description": "付款状态，不是发货状态" }, "secret": { "type": "string", "nullable": true }, "widget": { "type": "object", "nullable": true, "additionalProperties": true } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "secret": "示例内容或处理中提示", "widget": null, "status": 1 } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/commodity/query2": { "post": { "operationId": "query2", "summary": "旧版按接入方单号查询", "description": "查询范围限定当前商户。请求名称是 requestNo，而创建订单时是 request_no；新接入推荐 orderStatus。", "tags": [ "订单" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "requestNo": { "type": "string", "description": "接入方单号，驼峰", "minLength": 1, "maxLength": 64, "pattern": "^(?!0$)[A-Za-z0-9][A-Za-z0-9_-]{0,63}$" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "requestNo" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "status": { "type": "integer", "description": "付款状态，不是发货状态" }, "secret": { "type": "string", "nullable": true }, "widget": { "type": "object", "nullable": true, "additionalProperties": true } } } } }, "examples": { "success": { "value": { "code": 200, "msg": "success", "data": { "secret": "示例内容或处理中提示", "widget": null, "status": 1 } } }, "businessError": { "value": { "code": 500, "msg": "库存不足" } } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } }, "/shared/integration212/quote": { "post": { "operationId": "quote", "summary": "指定数量试算", "description": "只读本站规则，精确单价与现有结算金额分开返回；不锁库存。特殊动态计价商品拒绝通用试算。", "tags": [ "商品与账户" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "商户 ID" }, "sign": { "type": "string", "pattern": "^(?:[a-f0-9]{32}|[a-f0-9]{64})$", "description": "v2 为 HMAC-SHA256；v1 为 MD5；按文档生成，不是 Bearer Token" }, "shared_code": { "type": "string", "description": "商品 code；此接口使用下划线" }, "num": { "type": "integer", "description": "购买数量，正整数", "minimum": 1, "maximum": 999999 }, "race": { "type": "string", "description": "无种类传空字符串" }, "signature_version": { "type": "string", "enum": [ "1", "2" ], "description": "新客户端使用 2；不传按旧版 1 处理" }, "timestamp": { "type": "string", "pattern": "^[0-9]{10}$", "description": "v2 必填 Unix 秒，允许偏差 120 秒" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "v2 必填，每次请求生成新的随机值，不可重复" } }, "required": [ "app_id", "sign", "shared_code", "num" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "signature_version": { "enum": [ "2" ] } }, "required": [ "signature_version", "timestamp", "nonce" ] }, { "properties": { "signature_version": { "enum": [ "1" ] } } } ] } ] } } } }, "responses": { "200": { "description": "必须同时检查 JSON code；HTTP 200 不保证业务成功。示例中的字段为文档示意。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer" }, "race": { "type": "string" }, "unit_price": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{5}$" }, "amount": { "type": "string" }, "currency": { "type": "string", "enum": [ "CNY" ] }, "binding": { "type": "boolean", "enum": [ false ] } } } } }, "example": { "code": 200, "msg": "success", "data": { "code": "MAIL-DEMO", "quantity": 100, "race": "", "unit_price": "0.03500", "amount": "3.50", "currency": "CNY", "binding": false } } } } }, "default": { "description": "网络、鉴权、限流或服务器异常；不得自动重试付款操作。" } } } } }, "components": { "schemas": { "Envelope": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer", "description": "200 为业务成功；其他值检查 msg，不依赖固定错误编号" }, "msg": { "type": "string" }, "data": { "description": "不同接口可能是数组、对象或空数组", "nullable": true } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "factory_price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "user_price": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "价格可含 5 位小数；金额用十进制定点数处理，最终以订单 amount 为准" }, "minimum": { "type": "integer" }, "maximum": { "type": "integer" }, "config": { "type": "string", "description": "INI 文本；种类在 category，拿货价在 category_factory" }, "widget": { "type": "string", "nullable": true, "description": "商品动态表单 JSON 文本，按实际返回解析" }, "delivery_way": { "type": "integer", "enum": [ 0, 1 ] }, "draft_status": { "type": "integer", "enum": [ 0, 1 ] } }, "additionalProperties": true } } } }