Appearance

售后管理 API ​

1. 接口概述 ​

售后管理 API 提供了查询售后单信息的功能，包括售后单列表查询和 JIT 售后单查询。通过这些接口，您可以获取系统中的售后单数据，用于数据分析和业务处理。

2. 接口列表 ​

接口名方法功能描述
aftersales.getListPOST获取售后单列表
aftersales.getDetailPOST获取售后单详情

3. 系统级参数 ​

系统级参数是调用所有接口都必须提供的参数：

参数名类型必填名称描述
flagstring是应用标识用于标识调用方身份
methodstring是接口方法名例如：aftersales.getList
vernumber是版本号固定为1
charsetstring是字符集固定为utf-8
typestring是返回格式固定为json
timestampstring是时间戳格式：yyyyMMddHHmmss
signstring是签名用于验证请求的合法性

4. 接口详细说明 ​

4.1 获取售后单列表 ​

请求参数 ​

参数名类型必填描述
start_timestring是开始时间（格式：yyyy-MM-dd HH:mm:ss）
end_timestring是结束时间（格式：yyyy-MM-dd HH:mm:ss）
modified_startstring否更新开始时间（格式：yyyy-MM-dd HH:mm:ss）
modified_endstring否更新结束时间（格式：yyyy-MM-dd HH:mm:ss）
page_noint是页码，默认1
page_sizeint是每页条数，默认100，最大1000

响应参数 ​

参数名类型描述
countint总记录数
listsarray售后单列表

lists 数组中的每个对象包含以下字段：

参数名类型描述
shop_codestring店铺编码
shop_namestring店铺名称
order_nostring订单编号
change_order_bnstring换货订单号
relate_order_bnstring关联订单号
order_typestring订单类型
order_pay_timestring订单支付时间
ship_timestring发货时间
ship_provincestring发货省份
ship_citystring发货城市
ship_districtstring发货区县
ship_addrstring发货地址
ship_zipstring邮政编码
sale_bnstring销售单号
platform_order_bnstring平台订单号
aftersale_nostring售后单号
aftersale_apply_nostring售后申请单号
return_change_nostring退货换货单号
return_logi_nostring退货物流单号
return_logi_namestring退货物流公司名称
refund_apply_nostring退款申请单号
aftersale_typestring售后类型
delivery_modestring配送方式
pay_methodstring支付方式
refund_moneystring退款金额
member_namestring会员名称
member_mobilestring会员手机号
check_opstring审核操作员
quality_inspection_opstring质检操作员
refund_opstring退款操作员
apply_timestring申请时间
check_timestring审核时间
quality_inspection_timestring质检时间
refund_timestring退款时间
aftersale_timestring售后时间
settlement_amountstring结算金额
platform_amountstring平台承担金额
receiving_statusstring收货状态
up_timestring更新时间
return_categorystring售后退货分类
aftersale_itemsarray售后商品明细

aftersale_items 数组中的每个对象包含以下字段：

参数名类型描述
item_idstring商品ID
bnstring商品编码
sales_material_bnstring销售物料编码
namestring商品名称
barcodestring条码
pricestring价格
apply_numint申请数量
numsint数量
normal_numint正常数量
defective_numint残次数量
amountstring金额
branch_namestring仓库名称
branch_bnstring仓库编码
apply_moneystring申请金额
refund_moneystring退款金额
coststring成本
cost_amountstring成本金额
sale_pricestring销售价格
cost_taxstring商品税率
brand_codestring物料品牌
cat_namestring物料分类
goods_typestring物料属性
retail_pricestring基础物料价格
order_item_idstring订单明细行ID
order_pricestring订单销售单价
order_sale_pricestring订单销售价
order_amountstring订单销售金额
order_pmt_pricestring订单商品优惠价
order_sales_amountstring订单商品实际成交金额
shop_goods_idstring平台商品ID
shop_product_idstring平台SkuID
settlement_amountstring结算金额
platform_amountstring平台承担金额
batchsarray批次信息
propsarray商品属性

请求示例 ​

请参考openapi.md文档中【6. 接口调用示例】。

响应示例 ​

json
{
  "count": 100,
  "lists": [
    {
      "shop_code": "SHOP001",
      "shop_name": "测试店铺",
      "order_no": "ORDER20240101001",
      "aftersale_no": "AS20240101001",
      "aftersale_type": "return",
      "refund_money": "100.00",
      "apply_time": "2024-01-01 10:00:00",
      "aftersale_items": {
        "1": {
          "item_id": "1",
          "bn": "MAT001",
          "name": "测试商品",
          "barcode": "BAR123456",
          "price": "100.00",
          "nums": 1,
          "amount": "100.00"
        }
      }
    }
  ]
}```

### 4.2 获取售后单详情

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| `aftersale_no` | string | 是 | 售后单号 |

#### 响应参数

| 参数名 | 类型 | 描述 |
| :--- | :--- | :--- |
| `shop_code` | string | 店铺编码 |
| `shop_name` | string | 店铺名称 |
| `order_no` | string | 订单编号 |
| `change_order_bn` | string | 换货订单号 |
| `relate_order_bn` | string | 关联订单号 |
| `order_type` | string | 订单类型 |
| `order_pay_time` | string | 订单支付时间 |
| `ship_time` | string | 发货时间 |
| `ship_province` | string | 发货省份 |
| `ship_city` | string | 发货城市 |
| `ship_district` | string | 发货区县 |
| `ship_addr` | string | 发货地址 |
| `ship_zip` | string | 邮政编码 |
| `sale_bn` | string | 销售单号 |
| `platform_order_bn` | string | 平台订单号 |
| `aftersale_no` | string | 售后单号 |
| `aftersale_apply_no` | string | 售后申请单号 |
| `return_change_no` | string | 退货换货单号 |
| `return_logi_no` | string | 退货物流单号 |
| `return_logi_name` | string | 退货物流公司名称 |
| `refund_apply_no` | string | 退款申请单号 |
| `aftersale_type` | string | 售后类型 |
| `delivery_mode` | string | 配送方式 |
| `pay_method` | string | 支付方式 |
| `refund_money` | string | 退款金额 |
| `member_name` | string | 会员名称 |
| `member_mobile` | string | 会员手机号 |
| `check_op` | string | 审核操作员 |
| `quality_inspection_op` | string | 质检操作员 |
| `refund_op` | string | 退款操作员 |
| `apply_time` | string | 申请时间 |
| `check_time` | string | 审核时间 |
| `quality_inspection_time` | string | 质检时间 |
| `refund_time` | string | 退款时间 |
| `aftersale_time` | string | 售后时间 |
| `settlement_amount` | string | 结算金额 |
| `platform_amount` | string | 平台承担金额 |
| `receiving_status` | string | 收货状态 |
| `up_time` | string | 更新时间 |
| `return_category` | string | 售后退货分类 |
| `aftersale_items` | array | 售后商品明细 |

`aftersale_items` 对象中的每个子对象（以item_id为键）包含以下字段：

| 参数名 | 类型 | 描述 |
| :--- | :--- | :--- |
| `item_id` | string | 商品ID |
| `bn` | string | 商品编码 |
| `sales_material_bn` | string | 销售物料编码 |
| `name` | string | 商品名称 |
| `barcode` | string | 条码 |
| `price` | string | 价格 |
| `apply_num` | int | 申请数量 |
| `nums` | int | 数量 |
| `normal_num` | int | 正常数量 |
| `defective_num` | int | 残次数量 |
| `amount` | string | 金额 |
| `branch_name` | string | 仓库名称 |
| `branch_bn` | string | 仓库编码 |
| `apply_money` | string | 申请金额 |
| `refund_money` | string | 退款金额 |
| `cost` | string | 成本 |
| `cost_amount` | string | 成本金额 |
| `sale_price` | string | 销售价格 |
| `cost_tax` | string | 商品税率 |
| `brand_code` | string | 物料品牌 |
| `cat_name` | string | 物料分类 |
| `goods_type` | string | 物料属性 |
| `retail_price` | string | 基础物料价格 |
| `order_item_id` | string | 订单明细行ID |
| `order_price` | string | 订单销售单价 |
| `order_sale_price` | string | 订单销售价 |
| `order_amount` | string | 订单销售金额 |
| `order_pmt_price` | string | 订单商品优惠价 |
| `order_sales_amount` | string | 订单商品实际成交金额 |
| `shop_goods_id` | string | 平台商品ID |
| `shop_product_id` | string | 平台SkuID |
| `settlement_amount` | string | 结算金额 |
| `platform_amount` | string | 平台承担金额 |
| `batchs` | array | 批次信息 |
| `props` | array | 商品属性 |

#### 请求示例

请参考openapi.md文档中【6. 接口调用示例】。

#### 响应示例

```json
{
  "shop_code": "SHOP001",
  "shop_name": "测试店铺",
  "order_no": "ORDER20240101001",
  "aftersale_no": "AS20240101001",
  "aftersale_type": "return",
  "refund_money": "100.00",
  "apply_time": "2024-01-01 10:00:00",
  "aftersale_items": {
    "1": {
      "item_id": "1",
      "bn": "MAT001",
      "sales_material_bn": "SMAT001",
      "name": "测试商品",
      "barcode": "BAR123456",
      "price": "100.00",
      "nums": 1,
      "amount": "100.00",
      "branch_name": "测试仓库",
      "branch_bn": "WARE001"
    }
  }
}```

## 5. 错误码说明

| 错误码 | 错误信息 | 解决方案 |
|-------|---------|--------|
| 0 | 成功 | - |
| 1 | 参数错误 | 检查参数格式是否正确，所有必填参数是否都已提供 |
| 400 | 参数错误 | 检查参数格式是否正确，所有必填参数是否都已提供 |
| 401 | 未授权访问 | 检查flag和sign是否正确 |
| 403 | 禁止访问 | 联系管理员获取权限 |
| 500 | 服务器内部错误 | 检查请求参数或联系技术支持 |
| 1001 | 非法的flag | 请检查flag是否正确 |
| 1002 | 请求已过期 | 请检查timestamp是否正确，请求有效期为5分钟 |
| 1003 | 签名错误 | 请检查签名算法和参数是否正确 |
| 1004 | 不支持的type格式 | 请使用json格式 |
| 2001 | 缺少必要的参数 | 请检查请求参数是否完整 |
| 2002 | 非法的请求参数 | 请检查参数格式和范围是否正确 |
| 2003 | 接口不存在 | 请检查接口方法名是否正确 |

## 6. 注意事项

1. 时间格式必须为 `yyyy-MM-dd HH:mm:ss`，否则可能导致查询失败。
2. `page_size` 参数最大支持 1000，默认50，超过100将被限制为 100。
3. 对于大数据量的查询，建议使用时间范围进行精确筛选，以提高查询效率。
4. 时间戳必须与服务器时间保持同步，误差不超过3600秒。
5. 每个请求必须生成唯一的签名，避免重复提交。
6. 请妥善保管接口密钥，避免泄露。
7. 所有请求参数中的特殊字符必须进行 URL 编码，特别是在使用 GET 方法时。
8. 请确保在请求头中设置正确的 Content-Type，对于 POST 请求建议使用 application/json。
9. 为了系统性能和稳定性，请避免短时间内发送大量请求，建议控制调用频率。
10. 敏感数据（如签名、密钥等）请勿在日志中记录，确保数据安全。