Appearance

库存查询 API ​

1. 接口概述 ​

库存查询API用于获取系统中的库存信息，支持按基础物料编码、仓库编码、条形码、货号等多种方式查询库存数据。

2. 接口列表 ​

接口名方法功能描述
stock.getStockPOST获取指定条件下的库存信息
stock.getStockDetailsPOST获取指定条件下的库存明细信息
stock.getStockHistoryPOST获取指定条件下的库存变更历史

3. 系统级参数 ​

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

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

4. 接口详细说明 ​

4.1 获取指定条件下的库存信息 ​

请求参数 ​

参数名类型必填描述
material_bnstring否物料编号，多个用逗号分隔
warehouse_bnstring否仓库编号，多个用逗号分隔
shop_bnstring否店铺编号
page_noint是页码，默认 1
page_sizeint是每页条数，默认 50，最大 1000

响应参数 ​

参数名类型描述
countint总记录数
listsarray库存信息列表

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

参数名类型描述
material_bnstring物料编号
material_namestring物料名称
specstring规格
unitstring单位
warehouse_bnstring仓库编号
warehouse_namestring仓库名称
stock_qtydecimal库存数量
lock_qtydecimal锁定数量
available_qtydecimal可用数量

请求示例 ​

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

响应示例 ​

json
{
  "count": 100,
  "lists": [
    {
      "material_bn": "MAT001",
      "material_name": "测试物料",
      "spec": "标准规格",
      "unit": "个",
      "warehouse_bn": "WH001",
      "warehouse_name": "测试仓库",
      "stock_qty": 1000,
      "lock_qty": 100,
      "available_qty": 900
    }
  ]
}

4.2 获取指定条件下的库存明细信息 ​

请求参数 ​

参数名类型必填描述
material_bnstring否物料编号，多个用逗号分隔
warehouse_bnstring否仓库编号，多个用逗号分隔
shop_bnstring否店铺编号
batch_nostring否批次号
page_noint是页码，默认 1
page_sizeint是每页条数，默认 50，最大 1000

响应参数 ​

参数名类型描述
countint总记录数
listsarray库存明细列表

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

参数名类型描述
material_bnstring物料编号
material_namestring物料名称
specstring规格
unitstring单位
warehouse_bnstring仓库编号
warehouse_namestring仓库名称
batch_nostring批次号
stock_qtydecimal库存数量
lock_qtydecimal锁定数量
available_qtydecimal可用数量
expire_datestring过期日期

请求示例 ​

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

响应示例 ​

json
{
  "count": 100,
  "lists": [
    {
      "material_bn": "MAT001",
      "material_name": "测试物料",
      "spec": "标准规格",
      "unit": "个",
      "warehouse_bn": "WH001",
      "warehouse_name": "测试仓库",
      "batch_no": "BATCH20240101",
      "stock_qty": 500,
      "lock_qty": 50,
      "available_qty": 450,
      "expire_date": "2025-12-31"
    }
  ]
}

4.3 获取指定条件下的库存变更历史 ​

请求参数 ​

参数名类型必填描述
start_timestring否开始时间（格式：yyyy-MM-dd HH:mm:ss）
end_timestring否结束时间（格式：yyyy-MM-dd HH:mm:ss）
material_bnstring否物料编号，多个用逗号分隔
warehouse_bnstring否仓库编号，多个用逗号分隔
operate_typestring否操作类型：in-入库, out-出库, adjust-调整
page_noint是页码，默认 1
page_sizeint是每页条数，默认 50，最大 1000

响应参数 ​

参数名类型描述
countint总记录数
listsarray库存变更历史列表

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

参数名类型描述
idint记录ID
material_bnstring物料编号
material_namestring物料名称
warehouse_bnstring仓库编号
warehouse_namestring仓库名称
batch_nostring批次号
operate_typestring操作类型
operate_qtydecimal操作数量
before_qtydecimal操作前数量
after_qtydecimal操作后数量
operate_timestring操作时间
remarkstring备注

请求示例 ​

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

响应示例 ​

json
{
  "count": 200,
  "lists": [
    {
      "id": 1,
      "material_bn": "MAT001",
      "material_name": "测试物料",
      "warehouse_bn": "WH001",
      "warehouse_name": "测试仓库",
      "batch_no": "BATCH20240101",
      "operate_type": "in",
      "operate_qty": 500,
      "before_qty": 0,
      "after_qty": 500,
      "operate_time": "2024-01-01 10:00:00",
      "remark": "采购入库"
    }
  ]
}

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