采购退货单管理 API

1. 接口概述

采购退货单管理API用于管理系统中的采购退货单信息，支持获取采购退货单列表、新建采购退货单和取消采购退货单功能。

2. 接口列表

接口名	方法	功能描述
purchasereturn.getList	POST	获取采购退货单列表
purchasereturn.getDetail	POST	获取采购退货单详情

3. 系统级参数

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

参数名	类型	必填	名称	描述
flag	string	是	应用标识	用于标识调用方身份
method	string	是	接口方法名	例如：purchasereturn.getList
ver	number	是	版本号	固定为1
charset	string	是	字符集	固定为utf-8
type	string	是	返回格式	固定为json
timestamp	string	是	时间戳	格式：yyyyMMddHHmmss
sign	string	是	签名	用于验证请求的合法性

4. 接口详细说明

4.1 获取采购退货单列表

请求参数

参数名	类型	必填	描述
purchasereturn_bn	string	否	采购退货单编号
supplier_code	string	否	供应商编码
branch_bn	string	否	仓库编码
status	string	否	订单状态（1:待审核 2:已审核 3:已驳回 4:已关闭）
start_time	string	否	制单开始时间，格式：2022-01-01
end_time	string	否	制单结束时间，格式：2022-01-31
page_no	int	是	页码，默认1
page_size	int	是	每页条数，默认50，最大1000

响应参数

参数名	类型	描述
count	int	总记录数
lists	array	采购退货单列表

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

参数名	类型	描述
purchasereturn_bn	string	采购退货单编号
create_time	string	制单时间
supplier_code	string	供应商编码
supplier_name	string	供应商名称
branch_bn	string	仓库编码
branch_name	string	仓库名称
total_amount	string	退货总金额
actual_refund_amount	string	实际退款金额
status	string	订单状态
status_text	string	状态描述
creator	string	制单人

请求示例

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

响应示例

{
  "count": 100,
  "lists": [
    {
      "purchasereturn_bn": "PR202201010001",
      "create_time": "2022-01-01 10:00:00",
      "supplier_code": "SUP001",
      "supplier_name": "测试供应商",
      "branch_bn": "WARE001",
      "branch_name": "测试仓库",
      "total_amount": "5000.00",
      "actual_refund_amount": "4500.00",
      "status": "2",
      "status_text": "已审核",
      "creator": "张三"
    }
  ]
}

4.2 获取采购退货单详情

请求参数

参数名	类型	必填	描述
purchasereturn_bn	string	是	采购退货单编号

响应参数

参数名	类型	描述
purchasereturn_bn	string	采购退货单编号
create_time	string	制单时间
supplier_code	string	供应商编码
supplier_name	string	供应商名称
branch_bn	string	仓库编码
branch_name	string	仓库名称
currency	string	币种
tax_rate	string	税率
total_amount	string	退货总金额
total_amount_with_tax	string	含税总金额
actual_refund_amount	string	实际退款金额
status	string	订单状态
status_text	string	状态描述
creator	string	制单人
remark	string	备注
items	array	采购退货单明细

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

参数名	类型	描述
bn	string	商品编码
name	string	商品名称
spec_info	string	规格信息
quantity	int	退货数量
price	string	退货单价
amount	string	退货金额
tax_price	string	含税单价
tax_amount	string	含税金额
return_reason	string	退货原因
stockout_quantity	int	已出库数量

请求示例

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

响应示例

{
  "purchasereturn_bn": "PR202201010001",
  "create_time": "2022-01-01 10:00:00",
  "supplier_code": "SUP001",
  "supplier_name": "测试供应商",
  "branch_bn": "WARE001",
  "branch_name": "测试仓库",
  "currency": "CNY",
  "tax_rate": "13%",
  "total_amount": "5000.00",
  "total_amount_with_tax": "5650.00",
  "actual_refund_amount": "4500.00",
  "status": "2",
  "status_text": "已审核",
  "creator": "张三",
  "remark": "测试备注",
  "items": [
    {
      "bn": "PROD001",
      "name": "测试商品",
      "spec_info": "红色,M",
      "quantity": 50,
      "price": "100.00",
      "amount": "5000.00",
      "tax_price": "113.00",
      "tax_amount": "5650.00",
      "return_reason": "质量问题",
      "stockout_quantity": 40
    }
  ]
}

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. 敏感数据（如签名、密钥等）请勿在日志中记录，确保数据安全。