订单管理接口

订单管理接口用于平台与商户之间进行订单数据交互，包括订单推送、状态更新、查询等功能。

# 1. 订单推送通知

POST {merchant_callback_url}/order/new

平台将新订单推送给商户系统。

请求参数

参数名 类型 必填 描述
order_id String 是 平台订单号
order_time String 是 下单时间，格式：yyyy-MM-dd HH:mm:ss
pay_time String 是 支付时间，格式：yyyy-MM-dd HH:mm:ss
total_amount Decimal 是 订单总金额
pay_amount Decimal 是 实付金额
discount_amount Decimal 否 优惠金额
delivery_fee Decimal 否 配送费
pay_type Integer 是 支付方式：1-微信，2-支付宝，3-银行卡，4-余额
buyer_info Object 是 买家信息
delivery_info Object 是 配送信息
items Array 是 订单商品列表
remark String 否 订单备注

buyer_info对象结构：

字段名 类型 必填 描述
buyer_id String 是 买家ID
buyer_name String 是 买家姓名
buyer_phone String 是 买家手机号

delivery_info对象结构：

字段名 类型 必填 描述
delivery_type Integer 是 配送方式：1-自提，2-商家配送，3-第三方配送
receiver_name String 是 收货人姓名
receiver_phone String 是 收货人手机号
province String 是 省份
city String 是 城市
district String 是 区/县
address String 是 详细地址
longitude Double 否 经度
latitude Double 否 纬度
expected_delivery_time String 否 期望送达时间，格式：yyyy-MM-dd HH:mm:ss

items数组中每个商品对象结构：

字段名 类型 必填 描述
item_id String 是 订单项ID
sku_code String 是 商品SKU编码
product_name String 是 商品名称
quantity Integer 是 购买数量
price Decimal 是 商品单价
total_price Decimal 是 商品总价
image String 否 商品图片URL
specifications String 否 商品规格，如"颜色:红色;尺寸:XL"

响应参数

字段名 类型 描述
order_id String 平台订单号
merchant_order_id String 商户订单号
status Integer 处理结果：1-成功，0-失败
message String 处理结果描述

请求示例

{
  "order_id": "PO2023061512345678",
  "order_time": "2023-06-15 14:30:25",
  "pay_time": "2023-06-15 14:31:05",
  "total_amount": 125.50,
  "pay_amount": 115.50,
  "discount_amount": 10.00,
  "delivery_fee": 5.00,
  "pay_type": 1,
  "buyer_info": {
    "buyer_id": "U123456789",
    "buyer_name": "张三",
    "buyer_phone": "13800138000"
  },
  "delivery_info": {
    "delivery_type": 2,
    "receiver_name": "李四",
    "receiver_phone": "13900139000",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "address": "建国路88号中央公园1号楼2单元303室",
    "longitude": 116.46,
    "latitude": 39.92,
    "expected_delivery_time": "2023-06-15 18:00:00"
  },
  "items": [
    {
      "item_id": "OI2023061500001",
      "sku_code": "SP123456",
      "product_name": "有机草莓",
      "quantity": 2,
      "price": 29.90,
      "total_price": 59.80,
      "image": "https://example.com/images/strawberry.jpg",
      "specifications": "规格:标准(500g)"
    },
    {
      "item_id": "OI2023061500002",
      "sku_code": "SP234567",
      "product_name": "进口牛奶",
      "quantity": 3,
      "price": 18.90,
      "total_price": 56.70,
      "image": "https://example.com/images/milk.jpg",
      "specifications": "规格:1L"
    }
  ],
  "remark": "请尽快送达，谢谢！"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "PO2023061512345678",
    "merchant_order_id": "MO2023061587654321",
    "status": 1,
    "message": "订单接收成功"
  },
  "timestamp": 1623123456789
}

# 2. 订单接单确认

POST /merchant/order/accept

商户确认接单。

请求参数

参数名 类型 必填 描述
order_id String 是 订单ID
estimated_delivery_time String 否 预计送达时间，格式：yyyy-MM-dd HH:mm:ss
remark String 否 备注信息

响应参数

字段名 类型 描述
order_id String 订单ID
status Integer 订单状态

请求示例

{
  "order_id": "PO2023061512345678",
  "estimated_delivery_time": "2023-06-15 16:30:00",
  "remark": "正在准备商品"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "PO2023061512345678",
    "status": 20
  },
  "timestamp": 1623123456789
}

# 3. 订单配送更新

POST /merchant/order/delivery/update

更新订单配送状态。

请求参数

参数名 类型 必填 描述
order_id String 是 订单ID
delivery_status Integer 是 配送状态：10-待配送，20-配送中，30-已送达
rider_info Object 否 骑手信息
tracking_number String 否 物流单号
remark String 否 备注信息

rider_info对象结构：

字段名 类型 必填 描述
rider_id String 是 骑手ID
rider_name String 是 骑手姓名
rider_phone String 是 骑手手机号

响应参数

字段名 类型 描述
order_id String 订单ID
delivery_status Integer 配送状态

请求示例

{
  "order_id": "PO2023061512345678",
  "delivery_status": 20,
  "rider_info": {
    "rider_id": "R10001",
    "rider_name": "王五",
    "rider_phone": "13700137000"
  },
  "tracking_number": "",
  "remark": "骑手已取货，正在配送中"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "PO2023061512345678",
    "delivery_status": 20
  },
  "timestamp": 1623123456789
}

# 4. 订单完成确认

POST /merchant/order/complete

商户确认订单已完成配送。

请求参数

参数名 类型 必填 描述
order_code String 是 平台订单编号
actual_arrival_time Long 是 实际送达时间戳
completion_type String 否 完成类型：normal-正常送达，self_pick-自提，other-其他
remark String 否 完成备注

响应参数

字段名 类型 描述
order_code String 平台订单编号
order_status Integer 更新后的订单状态

请求示例

{
  "order_code": "ORD20230601123456",
  "actual_arrival_time": 1623128000000,
  "completion_type": "normal",
  "remark": "已送达顾客手中"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_code": "ORD20230601123456",
    "order_status": 4
  },
  "timestamp": 1623123456789
}

# 5. 订单取消

POST /merchant/order/cancel

商户请求取消订单。

请求参数

参数名 类型 必填 描述
order_code String 是 平台订单编号
cancel_reason String 是 取消原因
cancel_type String 是 取消类型：out_of_stock-缺货，store_closed-门店已关闭，delivery_problem-配送问题，other-其他

响应参数

字段名 类型 描述
order_code String 平台订单编号
order_status Integer 更新后的订单状态
is_refund_initiated Boolean 是否已发起退款

请求示例

{
  "order_code": "ORD20230601123456",
  "cancel_reason": "商品已售罄",
  "cancel_type": "out_of_stock"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_code": "ORD20230601123456",
    "order_status": 5,
    "is_refund_initiated": true
  },
  "timestamp": 1623123456789
}

# 6. 订单详情查询

GET /merchant/order/detail

商户查询订单详情信息。

请求参数

参数名 类型 必填 描述
order_code String 是 平台订单编号

响应参数

返回订单完整详情，包含推送订单时的所有字段，以及订单最新状态。

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "12345",
    "order_code": "ORD20230601123456",
    "merchant_id": "M10001",
    "store_id": "S2001",
    "user_id": "U100232",
    "order_type": 1,
    "order_status": 3,
    "pay_status": 1,
    "pay_type": 1,
    "pay_time": 1623123456789,
    "pay_amount": 56.80,
    "order_amount": 59.80,
    "discount_amount": 3.00,
    "freight_amount": 0.00,
    "address": {
      "receiver_name": "张三",
      "receiver_phone": "13800138000",
      "province": "北京市",
      "city": "北京市",
      "district": "朝阳区",
      "detail_address": "建国路88号中央公园8号楼1单元801",
      "longitude": 116.46,
      "latitude": 39.92
    },
    "buyer_remark": "不要辣",
    "expect_delivery_time": 1623130000000,
    "create_time": 1623123000000,
    "update_time": 1623125000000,
    "delivery_info": {
      "delivery_status": 1,
      "deliverer_name": "李四",
      "deliverer_phone": "13900139000",
      "delivery_time": 1623125000000,
      "estimate_arrival_time": 1623130000000
    },
    "items": [
      {
        "item_id": "I10001",
        "sku_code": "SP123456",
        "product_name": "有机草莓",
        "product_image": "https://example.com/images/strawberry.jpg",
        "quantity": 2,
        "price": 29.90,
        "total_amount": 59.80,
        "discount_amount": 3.00,
        "specs": "标准(500g),简装"
      }
    ]
  },
  "timestamp": 1623123456789
}

# 7. 订单列表查询

GET /merchant/order/list

商户批量查询订单列表。

请求参数

参数名 类型 必填 描述
page Integer 否 页码，默认1
size Integer 否 每页数量，默认20，最大100
status Integer 否 订单状态筛选
start_time Long 否 开始时间戳
end_time Long 否 结束时间戳
order_code String 否 订单编号筛选

响应参数

字段名 类型 描述
total Integer 总记录数
pages Integer 总页数
page Integer 当前页码
size Integer 每页记录数
list Array 订单列表

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 125,
    "pages": 7,
    "page": 1,
    "size": 20,
    "list": [
      {
        "order_id": "12345",
        "order_code": "ORD20230601123456",
        "order_status": 3,
        "pay_status": 1,
        "pay_amount": 56.80,
        "create_time": 1623123000000,
        "receiver_name": "张三",
        "receiver_phone": "13800138000"
      },
      // 更多订单...
    ]
  },
  "timestamp": 1623123456789
}