9. 接口定义

接口列表

以下定义 v1.0.0 核心业务接口，按实体模块组织。所有接口返回统一格式 { code: number, data: any, message: string }。

采购管理

POST /api/purchases —— 创建采购单

Method： POST 描述： 创建采购单，记录供应商、成本、采购日期。

请求参数：

参数	类型	必填	说明
supplier_name	string	是	供应商名称
cost_cny	number	是	采购总成本（CNY）
purchase_date	string	是	采购日期（YYYY-MM-DD）
items	array	是	采购商品列表 [{brand, category, unit_cost}]

响应数据：

{
  "code": 0,
  "data": {
    "purchase_id": "PO-20260512-001",
    "status": "待鉴定"
  },
  "message": "success"
}

鉴定管理

POST /api/auths —— 登记鉴定结果

Method： POST 描述： 为采购单下的商品登记鉴定结果。

请求参数：

参数	类型	必填	说明
purchase_id	string	是	关联采购单 ID
items	array	是	鉴定结果列表 [{sku, result, cost_cny}]
result 取值	string	是	"pass" / "fail"
fail_action	string	否	不通过处理："return" / "scrap"

响应数据：

{
  "code": 0,
  "data": {
    "passed_count": 3,
    "failed_count": 1
  }
}

库存管理

GET /api/inventories —— 查询库存

Method： GET 描述： 按仓库、品牌、品类、状态查询库存。

请求参数：

参数	类型	必填	说明
warehouse_id	string	否	仓库 ID 筛选
status	string	否	库存状态筛选
brand	string	否	品牌筛选
page	number	否	页码，默认 1
size	number	否	每页数量，默认 20

响应数据：

{
  "code": 0,
  "data": {
    "total": 156,
    "items": [
      {
        "sku": "LV-BAG-20260501-001",
        "brand": "LV",
        "category": "包包",
        "grade": "95新",
        "warehouse": "纽约销售仓",
        "status": "在库"
      }
    ]
  }
}

POST /api/inventories/inbound —— 入库

Method： POST 描述： 商品扫码入库到指定仓库。

请求参数：

参数	类型	必填	说明
sku	string	是	商品 SKU
warehouse_id	string	是	目标仓库 ID

调拨管理

POST /api/transfers —— 创建调拨单

Method： POST 描述： 发起跨境仓间调拨。

请求参数：

参数	类型	必填	说明
from_warehouse	string	是	源仓 ID
to_warehouse	string	是	目标仓 ID
sku_list	array	是	调拨商品 SKU 列表
logistics_no	string	否	物流单号

POST /api/transfers/{id}/confirm —— 确认入库

Method： POST 描述： 目标仓确认调拨入库。

销售管理

POST /api/sales —— 创建销售订单

Method： POST 描述： 创建销售订单，自动扣减库存和记录销售池收入。

请求参数：

参数	类型	必填	说明
channel	string	是	whatnot / offline / private
items	array	是	销售商品 [{sku, amount_usd}]
customer_id	string	否	客户 ID

响应数据：

{
  "code": 0,
  "data": {
    "order_id": "SO-20260512-001",
    "platform_fee": 18.00,
    "net_revenue": 132.00,
    "status": "待发货"
  }
}

资金池

GET /api/pools —— 查询资金池状态

Method： GET 描述： 获取双资金池当前余额和流水。

响应数据：

{
  "code": 0,
  "data": {
    "cny_pool": {
      "current_balance": 320000,
      "target_balance": 400000,
      "warn_line": 150000,
      "status": "正常"
    },
    "usd_pool": {
      "current_balance": 18500,
      "status": "正常"
    }
  }
}

分润

POST /api/profit-sharing/calculate —— 计算分润

Method： POST 描述： 对指定日期范围内的已完成订单计算分润金额（预览，不执行）。

请求参数：

参数	类型	必填	说明
start_date	string	是	开始日期
end_date	string	是	结束日期
share_ratio	number	否	分润比例，默认取全局配置

POST /api/profit-sharing/execute —— 执行分润

Method： POST 描述： 确认执行分润，资金从销售池划出。

请求参数：

参数	类型	必填	说明
order_ids	array	是	参与分润的订单 ID 列表
share_ratios	object	否	逐单分润比例，不传则用全局默认