对接文档去除上游概念,只展示商户对接平台
- 文档移除所有上游/发货平台/BFF 表述:接口字段说明、示例、推荐流程全部中性化 - 代码用户可见文案同步中性化:提交发货 message、错误提示、发货配置相关措辞 - 概述去掉 /api/open/v1 上游链路提示
This commit is contained in:
@@ -42,8 +42,8 @@ const orderFields: ParamSpec[] = [
|
||||
{ name: 'currency', type: 'string', desc: '货币,默认 POINT' },
|
||||
{ name: 'buyer_reference', type: 'string', desc: '买家标识/备注' },
|
||||
{ name: 'data', type: 'object', desc: '下单时透传的请求数据(原样回显)' },
|
||||
{ name: 'result', type: 'object', desc: '发货平台回调的结果数据(原样回显)' },
|
||||
{ name: 'provider_order_no', type: 'string', desc: '发货平台侧单号' },
|
||||
{ name: 'result', type: 'object', desc: '平台发货处理的结果数据(原样回显)' },
|
||||
{ name: 'provider_order_no', type: 'string', desc: '平台发货单号' },
|
||||
{ name: 'failure_reason', type: 'string', desc: '最近一次失败原因' },
|
||||
{ name: 'created_at', type: 'datetime', desc: '创建时间' },
|
||||
{ name: 'delivered_at', type: 'datetime', desc: '交付时间' },
|
||||
@@ -127,7 +127,7 @@ const deliverySubmitResponseExample = `{
|
||||
"data": {
|
||||
"order_no": "FO20260730000123",
|
||||
"status": "delivering",
|
||||
"message": "已提交上游发货,等待发货结果回传",
|
||||
"message": "已提交发货,等待发货结果回传",
|
||||
"provider_order_no": "provider-1",
|
||||
"game_account": {
|
||||
"game_account": "4808146277",
|
||||
@@ -197,7 +197,7 @@ export const endpoints: EndpointSpec[] = [
|
||||
{ name: 'sku', type: 'string', required: true, desc: '商品标识,取自商品列表', example: 'suit_pink_sheep' },
|
||||
{ name: 'quantity', type: 'int', desc: '数量,默认 1', example: '1' },
|
||||
{ name: 'buyer_reference', type: 'string', desc: '买家标识/备注', example: 'buyer-001' },
|
||||
{ name: 'data', type: 'object', desc: '透传业务数据(最长 2048 字节)。自建发货页模式会原样返回给「查询发货数据」用于预填/展示;回调 payload 也会带回;约定字段 game_account/game_channel/role_name 会同步给上游查单' },
|
||||
{ name: 'data', type: 'object', desc: '透传业务数据(最长 2048 字节)。自建发货页模式会原样返回给「查询发货数据」用于预填/展示;回调 payload 也会带回;约定字段 game_account/game_channel/role_name 会用于发货处理' },
|
||||
],
|
||||
requestExample: `{
|
||||
"client_order_no": "shop-10001",
|
||||
@@ -319,7 +319,7 @@ export const endpoints: EndpointSpec[] = [
|
||||
{ name: 'role_name', type: 'string', desc: '角色名' },
|
||||
{ name: 'pay_score', type: 'int', desc: '消耗积分' },
|
||||
{ name: 'data', type: 'object', desc: '下单时透传的业务数据(原样返回,可用于预填玩家编号/展示区服)' },
|
||||
{ name: 'good', type: 'object', desc: '上游商品详情' },
|
||||
{ name: 'good', type: 'object', desc: '商品展示详情' },
|
||||
],
|
||||
notes: [
|
||||
'该接口返回的是结构化数据,适合商户自有页面渲染。',
|
||||
@@ -356,7 +356,7 @@ export const endpoints: EndpointSpec[] = [
|
||||
method: 'POST',
|
||||
path: '/api/client/v1/orders/{order_no}/delivery/submit',
|
||||
title: '提交发货',
|
||||
summary: '提交发货到上游并进入发货中状态',
|
||||
summary: '提交发货并进入发货中状态',
|
||||
scope: 'orders:write',
|
||||
pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
|
||||
bodyParams: [
|
||||
@@ -372,13 +372,13 @@ export const endpoints: EndpointSpec[] = [
|
||||
{ name: 'order_no', type: 'string', desc: '平台订单号' },
|
||||
{ name: 'status', type: 'string', desc: '提交后的订单状态' },
|
||||
{ name: 'message', type: 'string', desc: '处理结果说明' },
|
||||
{ name: 'provider_order_no', type: 'string', desc: '上游订单号' },
|
||||
{ name: 'game_account', type: 'object', desc: '上游绑定结果' },
|
||||
{ name: 'upstream_order', type: 'object', desc: '上游创建结果' },
|
||||
{ name: 'provider_order_no', type: 'string', desc: '平台发货单号' },
|
||||
{ name: 'game_account', type: 'object', desc: '账号绑定结果' },
|
||||
{ name: 'upstream_order', type: 'object', desc: '发货提交结果' },
|
||||
],
|
||||
notes: [
|
||||
'同一订单重复提交应直接返回已有结果,不应重复创建上游队列。',
|
||||
'提交成功后,最终成功/失败仍以 `ship_notify` 回传结果为准。',
|
||||
'同一订单重复提交应直接返回已有结果,不应重复发起发货。',
|
||||
'提交成功后,最终成功/失败以平台发货结果回传为准。',
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -308,7 +308,6 @@ function OverviewSection() {
|
||||
面向商户系统调用的开放 API。凭证在「开放 API / API 密钥」创建,
|
||||
采用 <Text code>X-App-Key</Text> + HMAC-SHA256 签名鉴权。
|
||||
发货链路同时支持「返回签名链接」和「返回结构化数据」两种模式。
|
||||
<Text code>/api/open/v1</Text> 仍是上游回调链路,和本页的商户 API 分开。
|
||||
</>
|
||||
}
|
||||
>
|
||||
@@ -472,7 +471,7 @@ const callbackEvents = [
|
||||
{
|
||||
event: 'order.shipping.updated',
|
||||
desc: '发货状态变化:提交发货(delivering)、发货成功(delivered)、发货失败(ship_failed)',
|
||||
trigger: '提交发货 / 上游回传发货结果',
|
||||
trigger: '提交发货 / 发货结果回传',
|
||||
},
|
||||
{
|
||||
event: 'order.cancelled',
|
||||
@@ -724,11 +723,11 @@ function StatusSection() { return (
|
||||
↓
|
||||
POST /orders 下单(client_order_no 幂等)
|
||||
↓
|
||||
拿响应里的 order_no 进入发货平台链接
|
||||
拿响应里的 order_no 进入发货链接
|
||||
↓
|
||||
发货平台查询订单并执行发货
|
||||
买家在发货页绑定账号并提交发货
|
||||
↓
|
||||
发货平台通过上游回调更新 order_status
|
||||
平台完成发货处理并更新 order_status
|
||||
↓
|
||||
GET /orders/{order_no} 轮询,或接收 order.shipping.updated 回调`}</pre>
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user