555 lines
19 KiB
Markdown
555 lines
19 KiB
Markdown
## 文档概述
|
||
- 接口总数：25个
|
||
- API版本：linkedmall/2023-09-30
|
||
- RegionId：cn-zhangjiakou（华北3 张家口）
|
||
- Endpoint：`linkedmall.cn-zhangjiakou.aliyuncs.com`
|
||
- HTTP基础Path前缀：`/opensaas-s2b/opensaas-s2b-biz-trade/v2`
|
||
- 签名类型：ROA签名，SDK内部自动处理
|
||
- 金额单位：分（整数，long/int64）
|
||
- 区域编码divisionCode：必须使用五级（乡镇街道级别）编码
|
||
|
||
## 认证与安全
|
||
- 使用RAM子账号AccessKey（AccessKeyId / AccessKeySecret），禁止主账号AK
|
||
- 授予LinkedMall对应OpenAPI最小权限
|
||
- 业务前置资源：purchaserId（采购方ID）、shopId（店铺ID），由LinkedMall控制台分配
|
||
- 签名类型为ROA签名，SDK内部自动处理，业务无需实现签名算法
|
||
- 使用通用OpenApiClient（darabonba-openapi/v2）发起ROA调用
|
||
|
||
## 公共返回结构体
|
||
所有接口返回外层统一格式：
|
||
```go
|
||
type CommonResponse struct {
|
||
RequestId string `json:"RequestId"`
|
||
Success bool `json:"Success"`
|
||
Code string `json:"Code"`
|
||
Message string `json:"Message"`
|
||
SubCode string `json:"SubCode"`
|
||
SubMessage string `json:"SubMessage"`
|
||
Data interface{} `json:"Data"` // 业务数据，不同接口Data内部结构不同
|
||
}
|
||
```
|
||
公共Code枚举：
|
||
- `SUCCESS`：业务调用成功
|
||
- 其他：业务失败，看SubCode、SubMessage定位原因
|
||
> 注意：HTTP 200 不代表业务成功，必须判断 `Success==true`
|
||
|
||
## SDK客户端初始化
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"github.com/alibabacloud-go/darabonba-openapi/v2/client"
|
||
"github.com/alibabacloud-go/tea/v2"
|
||
)
|
||
|
||
func NewLinkedMallClient(accessKeyId, accessKeySecret string) (*client.Client, error) {
|
||
config := &client.Config{
|
||
AccessKeyId: tea.String(accessKeyId),
|
||
AccessKeySecret: tea.String(accessKeySecret),
|
||
RegionId: tea.String("cn-zhangjiakou"),
|
||
Endpoint: tea.String("linkedmall.cn-zhangjiakou.aliyuncs.com"),
|
||
ReadTimeout: tea.Int(30000),
|
||
ConnectTimeout: tea.Int(10000),
|
||
}
|
||
return client.NewClient(config)
|
||
}
|
||
```
|
||
调用示例：
|
||
```go
|
||
cli, err := NewLinkedMallClient("AKxxx", "SKxxx")
|
||
resp, err := cli.RoaRequest(
|
||
tea.String("POST"),
|
||
tea.String("/opensaas-s2b/opensaas-s2b-biz-trade/v2/xxx"),
|
||
nil, // query map[string]*string
|
||
bodyObj, // post json body
|
||
nil, // header
|
||
)
|
||
```
|
||
|
||
## 接口列表
|
||
|
||
### 接口 1：ListPurchaserShops 获取采购方店铺列表
|
||
- 路径：`/purchaser-shops`
|
||
- 方法：GET
|
||
- 描述：分页获取采购方店铺列表
|
||
|
||
#### 请求参数（Query）
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PageNum | int | 否 | 页码，默认1 |
|
||
| PageSize | int | 否 | 每页条数，最大100 |
|
||
|
||
#### 响应Data结构体
|
||
```go
|
||
type ListPurchaserShopsRespData struct {
|
||
Total int64 `json:"Total"`
|
||
PageNum int `json:"PageNum"`
|
||
PageSize int `json:"PageSize"`
|
||
ShopList []PurchaserShopItem `json:"ShopList"`
|
||
}
|
||
type PurchaserShopItem struct {
|
||
ShopId string `json:"ShopId"`
|
||
PurchaserId string `json:"PurchaserId"`
|
||
ShopName string `json:"ShopName"`
|
||
ShopStatus string `json:"ShopStatus"`
|
||
}
|
||
```
|
||
|
||
### 接口 2：GetPurchaserShop 获取采购方店铺详情
|
||
- 路径：`/purchaser-shops/{ShopId}`
|
||
- 方法：GET
|
||
- 描述：获取单个采购店铺详情
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| ShopId | string | Path | 是 | 店铺ID |
|
||
|
||
#### 响应Data结构体
|
||
```go
|
||
type GetPurchaserShopRespData struct {
|
||
ShopId string `json:"ShopId"`
|
||
PurchaserId string `json:"PurchaserId"`
|
||
ShopName string `json:"ShopName"`
|
||
ShopStatus string `json:"ShopStatus"`
|
||
ContactInfo string `json:"ContactInfo"`
|
||
}
|
||
```
|
||
|
||
### 接口 3：ListSelectionProducts 查询选品池商品列表
|
||
- 路径：`/selection-products`
|
||
- 方法：GET
|
||
- 描述：分页查询选品池商品列表
|
||
|
||
#### 请求参数（Query）
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PageNum | int | 否 | 页码 |
|
||
| PageSize | int | 否 | 最大100 |
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
|
||
#### 响应Data结构体
|
||
```go
|
||
type ListSelectionProductsRespData struct {
|
||
Total int64 `json:"Total"`
|
||
PageNum int `json:"PageNum"`
|
||
PageSize int `json:"PageSize"`
|
||
ProductList []SelectionProductItem `json:"ProductList"`
|
||
}
|
||
type SelectionProductItem struct {
|
||
ProductId string `json:"ProductId"`
|
||
Title string `json:"Title"`
|
||
MainImage string `json:"MainImage"`
|
||
BrandName string `json:"BrandName"`
|
||
CategoryId string `json:"CategoryId"`
|
||
}
|
||
```
|
||
|
||
### 接口 4：GetSelectionProduct 查询选品池商品详情
|
||
- 路径：`/selection-products/{ProductId}`
|
||
- 方法：GET
|
||
- 描述：查询单个商品详情，支持传入divisionCode校验区域可售库存
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| ProductId | string | Path | 是 | 商品ID |
|
||
| PurchaserId | string | Query | 是 | 采购方ID |
|
||
| DivisionCode | string | Query | 否 | 五级乡镇区域编码，传后返回该区域可售状态 |
|
||
|
||
#### 响应Data结构体
|
||
```go
|
||
type GetSelectionProductRespData struct {
|
||
ProductId string `json:"ProductId"`
|
||
Title string `json:"Title"`
|
||
MainImage string `json:"MainImage"`
|
||
Images []string `json:"Images"`
|
||
BrandName string `json:"BrandName"`
|
||
CategoryId string `json:"CategoryId"`
|
||
Desc string `json:"Desc"`
|
||
SkuList []SelectionSkuItem `json:"SkuList"`
|
||
CanSale bool `json:"CanSale"` // 传入divisionCode才有效，该区域是否可售
|
||
StockQuantity int64 `json:"StockQuantity"`
|
||
}
|
||
type SelectionSkuItem struct {
|
||
SkuId string `json:"SkuId"`
|
||
SkuSpec string `json:"SkuSpec"`
|
||
SalePrice int64 `json:"SalePrice"` // 单位分
|
||
MarketPrice int64 `json:"MarketPrice"`
|
||
StockQuantity int64 `json:"StockQuantity"`
|
||
}
|
||
```
|
||
|
||
### 接口 5：GetSelectionProductSaleInfo 查询选品池商品销售信息
|
||
- 路径：`/selection-products/{ProductId}/sale-info`
|
||
- 方法：GET
|
||
- 描述：查询商品可售、价格库存快照
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| ProductId | string | Path | 是 | 商品ID |
|
||
| PurchaserId | string | Query | 是 | 采购方ID |
|
||
| DivisionCode | string | Query | 否 | 五级乡镇区域编码 |
|
||
|
||
### 接口 6：ListSelectionProductSaleInfos 批量查询商品销售信息
|
||
- 路径：`/selection-products:batch-sale-info`
|
||
- 方法：POST
|
||
- 描述：批量查询商品销售信息
|
||
|
||
#### 请求Body
|
||
```json
|
||
{
|
||
"PurchaserId": "xxx",
|
||
"ProductIdList": ["p1","p2"],
|
||
"DivisionCode": "五级编码"
|
||
}
|
||
```
|
||
|
||
### 接口 7：ListSelectionSkuSaleInfos 批量SKU销售信息
|
||
- 路径：`/selection-skus:batch-sale-info`
|
||
- 方法：POST
|
||
- 描述：批量查询SKU销售信息
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| SkuIdList | []string | 是 | SKU ID列表 |
|
||
| DivisionCode | string | 否 | 五级乡镇区域编码 |
|
||
|
||
### 接口 8：ListCategories 查询类目列表
|
||
- 路径：`/categories`
|
||
- 方法：GET
|
||
- 描述：查询类目列表
|
||
|
||
#### 请求参数（Query）
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| ParentCategoryId | string | 否 | 父类目ID（不传查一级类目） |
|
||
|
||
### 接口 9：SearchProducts 搜索选品池商品
|
||
- 路径：`/selection-products:search`
|
||
- 方法：POST
|
||
- 描述：搜索选品池商品
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| Keyword | string | 否 | 关键词 |
|
||
| CategoryId | string | 否 | 类目ID |
|
||
| PageNum | int | 否 | 页码 |
|
||
| PageSize | int | 否 | 每页条数 |
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
|
||
### 接口 10：SelectionGroupAddProduct 选品池商品入库
|
||
- 路径：`/selection-group/products:add`
|
||
- 方法：POST
|
||
- 描述：选品池商品入库
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| ShopId | string | 是 | 店铺ID |
|
||
| ProductIdList | []string | 是 | 商品ID列表 |
|
||
|
||
### 接口 11：SelectionGroupRemoveProduct 选品池商品出库
|
||
- 路径：`/selection-group/products:remove`
|
||
- 方法：POST
|
||
- 描述：选品池商品出库
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| ShopId | string | 是 | 店铺ID |
|
||
| ProductIdList | []string | 是 | 商品ID列表 |
|
||
|
||
### 接口 12：RenderPurchaseOrder 采购单渲染（下单预校验）
|
||
- 路径：`/purchase-orders:render`
|
||
- 方法：POST
|
||
- 描述：下单前必须调用，获取实时价格、校验商品是否可售
|
||
|
||
#### 请求Body
|
||
```go
|
||
type RenderPurchaseOrderReq struct {
|
||
PurchaserId string `json:"PurchaserId"`
|
||
ShopId string `json:"ShopId"`
|
||
DivisionCode string `json:"DivisionCode"` // 五级乡镇编码
|
||
ItemList []RenderOrderItem `json:"ItemList"`
|
||
ReceiverInfo ReceiverInfo `json:"ReceiverInfo"`
|
||
}
|
||
type RenderOrderItem struct {
|
||
SkuId string `json:"SkuId"`
|
||
Quantity int64 `json:"Quantity"`
|
||
}
|
||
type ReceiverInfo struct {
|
||
ReceiverName string `json:"ReceiverName"`
|
||
ReceiverPhone string `json:"ReceiverPhone"`
|
||
ProvinceCode string `json:"ProvinceCode"`
|
||
CityCode string `json:"CityCode"`
|
||
DistrictCode string `json:"DistrictCode"`
|
||
TownCode string `json:"TownCode"`
|
||
DetailAddress string `json:"DetailAddress"`
|
||
}
|
||
```
|
||
#### 响应Data
|
||
渲染后的价格、商品校验结果、不可售原因、预估运费。
|
||
|
||
### 接口 13：SplitPurchaseOrder 采购单渲染并拆单
|
||
- 路径：`/purchase-orders:split-render`
|
||
- 方法：POST
|
||
- 描述：采购单渲染并拆单，返回拆成多份子单结构
|
||
|
||
#### 请求Body
|
||
结构和RenderPurchaseOrderReq完全一致
|
||
|
||
#### 响应Data
|
||
返回拆成多份子单结构，用于前端展示，拆单结果用于创建采购单入参。
|
||
|
||
### 接口 14：CreatePurchaseOrder 创建采购单【异步】
|
||
- 路径：`/purchase-orders`
|
||
- 方法：POST
|
||
- 描述：⚠️重要：接口只返回采购单号，不代表下单成功，必须等待回调通知，再查询订单接口
|
||
|
||
#### 请求Body
|
||
```go
|
||
type CreatePurchaseOrderReq struct {
|
||
PurchaserId string `json:"PurchaserId"`
|
||
ShopId string `json:"ShopId"`
|
||
OuterPurchaseOrderId string `json:"OuterPurchaseOrderId"` // 外部业务唯一单号，幂等
|
||
DivisionCode string `json:"DivisionCode"`
|
||
ReceiverInfo ReceiverInfo `json:"ReceiverInfo"`
|
||
SubOrderList []CreateSubOrderItem `json:"SubOrderList"` // SplitPurchaseOrder返回的子单
|
||
}
|
||
type CreateSubOrderItem struct {
|
||
SkuId string `json:"SkuId"`
|
||
Quantity int64 `json:"Quantity"`
|
||
}
|
||
```
|
||
#### 响应Data结构体
|
||
```go
|
||
type CreatePurchaseOrderRespData struct {
|
||
PurchaseOrderId string `json:"PurchaseOrderId"` // 阿里云采购单号
|
||
}
|
||
```
|
||
|
||
### 接口 15：GetPurchaseOrderStatus 获取采购单状态
|
||
- 路径：`/purchase-orders/{PurchaseOrderId}/status`
|
||
- 方法：GET
|
||
- 描述：获取采购单状态
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| PurchaseOrderId | string | Path | 是 | 采购单ID |
|
||
| PurchaserId | string | Query | 是 | 采购方ID |
|
||
|
||
#### 响应Data
|
||
采购单状态枚举：INIT、PROCESS、SUCCESS、FAIL、CLOSED
|
||
|
||
### 接口 16：GetOrder 获取订单详情
|
||
- 路径：`/orders/{OrderId}`
|
||
- 方法：GET
|
||
- 描述：获取订单详情
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| OrderId | string | Path | 是 | 订单ID |
|
||
| PurchaserId | string | Query | 是 | 采购方ID |
|
||
|
||
#### 响应Data
|
||
订单主信息、商品明细、实付金额、状态、收货信息
|
||
|
||
### 接口 17：QueryOrders 查询订单列表
|
||
- 路径：`/orders`
|
||
- 方法：GET
|
||
- 描述：查询订单列表
|
||
|
||
#### 请求参数（Query）
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| PurchaseOrderId | string | 否 | 采购单ID |
|
||
| PageNum | int | 否 | 页码 |
|
||
| PageSize | int | 否 | 每页条数 |
|
||
| StartTime | string | 否 | 开始时间 |
|
||
| EndTime | string | 否 | 结束时间 |
|
||
|
||
### 接口 18：ListLogisticsOrders 查询订单物流信息
|
||
- 路径：`/orders/{OrderId}/logistics`
|
||
- 方法：GET
|
||
- 描述：查询订单物流信息
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| OrderId | string | Path | 是 | 订单ID |
|
||
| PurchaserId | string | Query | 是 | 采购方ID |
|
||
|
||
#### 响应Data
|
||
运单号、物流公司、物流轨迹数组
|
||
|
||
### 接口 19：ConfirmDisburse 确认收货
|
||
- 路径：`/orders/{OrderId}:confirm-disburse`
|
||
- 方法：POST
|
||
- 描述：确认收货
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| OrderId | string | Path | 是 | 订单ID |
|
||
|
||
#### 请求Body
|
||
```json
|
||
{"PurchaserId":"xxx"}
|
||
```
|
||
|
||
### 接口 20：RenderRefundOrder 售后渲染预校验
|
||
- 路径：`/refund-orders:render`
|
||
- 方法：POST
|
||
- 描述：售后渲染预校验
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| OrderId | string | 是 | 订单ID |
|
||
| OrderItemId | string | 是 | 订单商品明细ID |
|
||
| RefundQuantity | int64 | 是 | 退款数量 |
|
||
| RefundType | string | 是 | 退款类型（仅退款/退货退款） |
|
||
|
||
### 接口 21：CreateRefundOrder 创建售后单
|
||
- 路径：`/refund-orders`
|
||
- 方法：POST
|
||
- 描述：创建售后单
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| OrderId | string | 是 | 订单ID |
|
||
| OrderItemId | string | 是 | 订单商品明细ID |
|
||
| RefundQuantity | int64 | 是 | 退款数量 |
|
||
| RefundAmount | int64 | 是 | 退款金额（单位分） |
|
||
| RefundType | string | 是 | 退款类型 |
|
||
| RefundReason | string | 是 | 退款原因 |
|
||
| OuterRefundNo | string | 是 | 外部售后单号 |
|
||
|
||
### 接口 22：CancelRefundOrder 取消售后单
|
||
- 路径：`/refund-orders/{RefundOrderId}:cancel`
|
||
- 方法：POST
|
||
- 描述：取消售后单
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| RefundOrderId | string | Path | 是 | 售后单ID |
|
||
|
||
#### 请求Body
|
||
```json
|
||
{"PurchaserId":"xxx"}
|
||
```
|
||
|
||
### 接口 23：GetRefundOrder 获取售后单详情
|
||
- 路径：`/refund-orders/{RefundOrderId}`
|
||
- 方法：GET
|
||
- 描述：获取售后单详情
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| RefundOrderId | string | Path | 是 | 售后单ID |
|
||
| PurchaserId | string | Query | 是 | 采购方ID |
|
||
|
||
### 接口 24：CreateGoodsShippingNotice 回填退货物流运单
|
||
- 路径：`/refund-orders/{RefundOrderId}:fill-logistics`
|
||
- 方法：POST
|
||
- 描述：回填退货物流运单
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| RefundOrderId | string | Path | 是 | 售后单ID |
|
||
|
||
#### 请求Body参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PurchaserId | string | 是 | 采购方ID |
|
||
| LogisticsCompany | string | 是 | 物流公司 |
|
||
| TrackingNumber | string | 是 | 运单号 |
|
||
|
||
### 接口 25：QueryChildDivisionCode 查询子区域编码
|
||
- 路径：`/divisions:children`
|
||
- 方法：GET
|
||
- 描述：查询子区域编码，不传返回省级；传入省返回市，传入市返回区，传入区返回乡镇（五级）
|
||
|
||
#### 请求参数（Query）
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| ParentDivisionCode | string | 否 | 父区域编码 |
|
||
|
||
#### 响应Data
|
||
DivisionCode列表、名称、层级；下单、商品可售校验必须拿到乡镇级DivisionCode
|
||
|
||
## 错误码
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| ShopTypeInvalid | SKU属于经销集采店铺，不可下单 | 过滤SKU |
|
||
| SkuPriceUnique | SKU价格非最新 | 重新调用RenderPurchaseOrder获取最新价格再下单 |
|
||
| PurchaseOrderNotFound | 采购单号不存在 | 核对入参PurchaseOrderId |
|
||
| RefundNumberMustLessThanOrder | 退款数量大于订单商品数量 | 修正退款数量 |
|
||
| RefundAmountMustLessThanOrder | 退款金额大于实付金额 | 修正退款金额 |
|
||
| HasNoPrivilege | RAM无接口权限 | 检查RAM授权策略 |
|
||
| OrderNotFound | 订单ID不存在 | 核对OrderId |
|
||
| ShopNotFind | 店铺不存在 | 核对ShopId/PurchaserId |
|
||
| SavePurchaseOrderError | 保存采购单服务端异常 | 短间隔重试 |
|
||
| OuterPurchaseOrderIdExist | 外部业务单号重复 | 更换OuterPurchaseOrderId，做好幂等 |
|
||
|
||
## 回调通知
|
||
### 消息回调（异步通知）规范
|
||
CreatePurchaseOrder创建采购单后，阿里云主动POST回调业务配置的回调地址。
|
||
|
||
1. 请求方式：POST，Content-Type: application/json
|
||
2. 业务侧需要返回 `{"success":true}` 告知阿里云消费成功；否则阿里云会重试推送。
|
||
3. 回调Body公共字段：
|
||
```json
|
||
{
|
||
"EventCode": "PURCHASE_ORDER_CHANGE",
|
||
"PurchaseOrderId": "xxx",
|
||
"OrderIdList": ["附属真实订单ID数组"],
|
||
"Status": "SUCCESS/FAIL",
|
||
"RequestId": "xxx"
|
||
}
|
||
```
|
||
EventCode枚举：
|
||
- PURCHASE_ORDER_CHANGE：采购单状态变更
|
||
- ORDER_STATUS_CHANGE：订单状态变更
|
||
- REFUND_ORDER_CHANGE：售后单变更
|
||
|
||
业务处理逻辑：收到回调后，调用对应查询接口拉取最新业务数据做本地状态同步。
|
||
|
||
## 完整业务调用流程
|
||
1. 调用 `QueryChildDivisionCode` 获取五级乡镇divisionCode（收货地址对应的区域编码）
|
||
2. 调用 `ListSelectionProducts` / `SearchProducts` 获取选品池商品SkuId
|
||
3. 调用 `RenderPurchaseOrder` 预渲染校验商品可售、价格
|
||
4. 调用 `SplitPurchaseOrder` 获取拆单结果
|
||
5. 调用 `CreatePurchaseOrder`，传入外部唯一业务单号OuterPurchaseOrderId，拿到PurchaseOrderId
|
||
6. **等待阿里云消息回调通知**
|
||
7. 回调收到事件，调用`GetPurchaseOrderStatus`看采购单状态；拿到附属OrderId调用`GetOrder`同步订单入库本地库
|
||
8. 后续：查物流、确认收货；产生售后调用售后接口
|
||
|
||
> ❗禁止：CreatePurchaseOrder同步返回成功直接标记本地订单成功。
|
||
|
||
## 开发注意事项
|
||
1. 金额全部为**分（int64）**，Go使用int64，不要float64；JSON序列化不要丢失long精度
|
||
2. DivisionCode必须五级乡镇，否则商品可售校验错误
|
||
3. OuterPurchaseOrderId外部采购单号全局唯一，用于幂等防重复下单
|
||
4. CreatePurchaseOrder异步，依赖回调；不能轮询频率过高
|
||
5. RAM子账号最小权限，AK禁止硬编码代码，环境变量配置
|
||
6. 所有接口必须判断外层返回`Success==true`，HTTP 200不等于业务成功
|
||
7. 分页接口PageSize上限100，不要传超大值
|
||
8. 回调接口做好幂等，同一个事件可能多次推送 |