货流单接口文档

货流单接口

货单类型与详情接口

`stockflowTypeNumber`	说明	后台操作说明	详情接口
`12`	进货单	对应后台“进货”，库存增加。	`/openapi/v3/stock-flow/inbound-detail`
`14`	退货单	对应后台“退货给供应商”，库存减少。	`/openapi/v3/stock-flow/outbound-detail`
`17`	出库单	对应后台“普通出库单”，库存减少。	`/openapi/v3/stock-flow/outbound-detail`
`13`	调货单	对应后台“普通调货”。	`/openapi/v3/stock-flow/transfer-detail`
`16`	调拨退货单	对应后台“调拨退货单”。	`/openapi/v3/stock-flow/transfer-detail`

调货单、调拨退货单确认出货后，会同时生成一笔对应的进货单。出货方减库存，进货方加库存。
调货单、调拨退货单可通过 nextStockFlowId 找到对应进货单。
进货单可通过 prevStockFlowId 找到对应的调货单或调拨退货单。

货流状态码

`confirmed`	状态	说明
`0`	待确认	货流单已创建，等待确认。
`1`	已完成	货流单已确认完成。
`2`	已拒绝	当前货流单被操作方拒绝。
`3`	被拒绝	当前货流单的关联方拒绝了该货流。
`4`	已作废	销售出库单、销售退货单等销售关联货流单作废状态。
`5`	已冲红	销售出库单、销售退货单等销售关联货流单冲红状态。

创建进货单

POST

/openapi/v3/stock-flow/inbound-create

按商品 barcode 创建进货单。接口固定创建 stockflowTypeNumber=12 的进货单。

Token 消耗 500 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号，用于鉴权并定位货流单所属门店。
`confirmationRequired`	boolean	是	是否仅创建待确认单。`true` 表示创建待确认单，后续需调用确认接口，库存不变更；`false` 表示创建后立即确认，库存立即变更。
`uid`	long	否	外部唯一 UID，建议别传，由服务端生成并在响应中返回。
`cashierUid`	long	否	收银员 UID。
`remarks`	string	否	主单备注。
`items`	array	是	商品明细，不能为空；同一请求内 `barcode` 不能重复。
`items[].barcode`	string	是	商品条码，必须属于当前 `account` 对应门店。
`items[].quantity`	decimal	是	进货数量，必须大于 `0`。
`items[].buyPrice`	decimal	否	本次进货价；传入则使用传入值，不传则使用商品档案 `buyPrice`。
`items[].productUnitUid`	long	否	商品单位 UID；传入后校验商品是否支持该单位。
`items[].remark`	string	否	明细备注。
`items[].sns`	array<string>	序列号商品必填	商品序列号列表。启用序列号管理（enableSN=1）的商品必传，且个数必须等于 `quantity`（此时 `quantity` 必须为正整数）；未启用序列号管理的商品不允许传。整单内序列号不允许重复，单条长度不超过 64。

请求示例

{
  "account": "store001",
  "confirmationRequired": true,
  "uid": 900000000001,
  "cashierUid": 800001,
  "remarks": "开放平台进货",
  "items": [
    {
      "barcode": "6901234567890",
      "quantity": 10,
      "buyPrice": 8.5,
      "productUnitUid": 7001,
      "remark": "首批进货"
    },
    {
      "barcode": "6901234567891",
      "quantity": 2,
      "buyPrice": 1200,
      "sns": ["SN20260101001", "SN20260101002"],
      "remark": "序列号商品进货"
    }
  ]
}

返回示例

{
  "status": "success",
  "messages": null,
  "result": {
    "stockFlowId": 14127908,
    "uid": 900000000001,
    "stockflowTypeNumber": 12,
    "confirmed": 0
  },
  "errorCode": null
}

创建出库单

POST

/openapi/v3/stock-flow/outbound-create

按商品 barcode 创建普通出库单。接口固定创建 stockflowTypeNumber=17 的出库单。

Token 消耗 500 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号，用于鉴权并定位货流单所属门店。
`confirmationRequired`	boolean	是	是否仅创建待确认单。`true` 表示创建待确认单，后续需调用确认接口，库存不变更；`false` 表示创建后立即确认，库存立即变更。
`uid`	long	否	外部唯一 UID，建议别传，由服务端生成并在响应中返回。
`cashierUid`	long	否	收银员 UID。
`remarks`	string	否	主单备注。
`items`	array	是	商品明细，不能为空；同一请求内 `barcode` 不能重复。
`items[].barcode`	string	是	商品条码，必须属于当前 `account` 对应门店。
`items[].quantity`	decimal	是	出库数量，必须大于 `0`。
`items[].productUnitUid`	long	否	商品单位 UID；传入后校验商品是否支持该单位。
`items[].remark`	string	否	明细备注。
`items[].sns`	array<string>	序列号商品必填	商品序列号列表。启用序列号管理（enableSN=1）的商品必传，且个数必须等于 `quantity`（此时 `quantity` 必须为正整数）；未启用序列号管理的商品不允许传。整单内序列号不允许重复，单条长度不超过 64。序列号必须已存在于本店库存且为在库状态、归属于本行商品、未被其他待确认出库单占用，否则报错。

请求示例

{
  "account": "store001",
  "confirmationRequired": false,
  "uid": 900000000002,
  "cashierUid": 800001,
  "remarks": "开放平台出库",
  "items": [
    {
      "barcode": "6901234567890",
      "quantity": 2,
      "productUnitUid": 7001,
      "sns": ["SN20260101001", "SN20260101002"],
      "remark": "门店出库"
    }
  ]
}

返回示例

{
  "status": "success",
  "messages": null,
  "result": {
    "stockFlowId": 14128092,
    "uid": 900000000002,
    "stockflowTypeNumber": 17,
    "confirmed": 1
  },
  "errorCode": null
}

确认进货单

POST

/openapi/v3/stock-flow/inbound-confirm

仅支持 stockflowTypeNumber=12 且 confirmed=0 的货流单。

Token 消耗 500 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号，用于鉴权并定位货流单所属门店。
`stockFlowId`	long	是	待确认进货单 ID。
`cashierUid`	long	否	确认收银员 UID。
`remark`	string	否	确认备注。
`confirmedTime`	string	否	指定确认时间，格式建议 `yyyy-MM-dd HH:mm:ss`；不传由后台按当前时间处理。

请求示例

{
  "account": "store001",
  "stockFlowId": 14127908,
  "cashierUid": 800001,
  "remark": "开放平台确认进货",
  "confirmedTime": "2026-07-21 10:30:00"
}

返回示例

{
  "status": "success",
  "messages": null,
  "result": null,
  "errorCode": null
}

确认出库/退货单

POST

/openapi/v3/stock-flow/outbound-confirm

仅支持 stockflowTypeNumber=14 退货单和 stockflowTypeNumber=17 出库单，且货流单必须为 confirmed=0。

Token 消耗 500 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号，用于鉴权并定位货流单所属门店。
`stockFlowId`	long	是	待确认出库/退货单 ID。
`cashierUid`	long	否	确认收银员 UID。

请求示例

{
  "account": "store001",
  "stockFlowId": 14128092,
  "cashierUid": 800001
}

返回示例

{
  "status": "success",
  "messages": null,
  "result": null,
  "errorCode": null
}

查询货流单

POST

/openapi/v3/stock-flow/increment-page

按主键游标分页查询货流主单。列表只返回公共字段，详情请根据 stockflowTypeNumber 调用对应详情接口。

Token 消耗 500 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号。传总部账号时查询总部及子门店货流单；传子门店账号时只查询当前门店货流单。
`stockflowTypeNumberList`	array<int>	否	货单类型列表。支持 `12,13,14,16,17`。
`confirmedList`	array<int>	否	货流状态列表。支持 `0,1,2,3,4,5`，含义见上方货流状态码。
`createdDatetimeBegin`	string	否	制单开始时间，格式 `yyyy-MM-dd HH:mm:ss`，包含该时间。
`createdDatetimeEnd`	string	否	制单结束时间，格式 `yyyy-MM-dd HH:mm:ss`，不包含该时间。
`lastId`	long	否	分页游标。首次查询传 `0` 或不传；下一页传上次返回的 `nextLastId`。
`order`	string	否	主键排序方向，支持 `asc` / `desc`，默认 `desc`。
`limit`	int	否	本次返回最大条数，默认 `100`，最大 `100`。

请求示例

{
  "account": "store001",
  "stockflowTypeNumberList": [12, 13, 14, 16, 17],
  "confirmedList": [1],
  "createdDatetimeBegin": "2026-07-15 00:00:00",
  "createdDatetimeEnd": "2026-07-16 00:00:00",
  "lastId": 0,
  "order": "desc",
  "limit": 100
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "14127908",
        "uid": "17841224568520088",
        "stockFlowNo": "20260715213415",
        "stockflowTypeNumber": 12,
        "confirmed": 1,
        "createdDatetime": "2026-07-15 21:34:15",
        "confirmedTime": "2026-07-15 21:35:02",
        "operatorUserId": 5027446,
        "toUserId": 5027446,
        "actualTotalAmount": 24.00
      }
    ],
    "hasMore": false,
    "nextLastId": "14127908"
  }
}

主单返回字段

字段	类型	说明
`id`	long	货流单主键 ID。详情接口只按该字段查询。
`uid`	long	货流单业务 UID。
`stockFlowNo`	string	货流展示号，由 `createdDatetime` 格式化为 `yyyyMMddHHmmss`，仅用于展示。
`stockflowTypeNumber`	int	货单类型。
`confirmed`	int	货流状态，含义见上方货流状态码。
`createdDatetime`	string	制单时间。
`confirmedTime`	string	货单完成或拒绝时间。
`operatorUserId`	int	操作门店 userId。
`toUserId`	int	`stockflowTypeNumber` 为 `12`（进货单）时，表示进货方门店 userId；为 `14`、`17`、`13`、`16`（退货/出库/调货/调拨退货单）时，表示出货方门店 userId。
`nextStockFlowUserId`	int	调货类关联下一张货流单的门店 userId。
`prevStockFlowId`	long	上一张关联货流单 ID。
`nextStockFlowId`	long	下一张关联货流单 ID。
`productRequestId`	long	关联订货单 ID。
`productPurchaseId`	long	关联采购单 ID。
`actualTotalAmount`	decimal	实际总金额。
`remarks`	string	备注。

查询进货单详情

POST

/openapi/v3/stock-flow/inbound-detail

按货流单 id 查询进货单详情。仅支持 stockflowTypeNumber=12。

Token 消耗 300 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号。
`id`	long	是	货流单主键 ID，详情接口只按该字段查询。

请求示例

{
  "account": "store001",
  "id": 14127908
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "14127908",
    "uid": "17841224568520088",
    "stockFlowNo": "20260715213415",
    "stockflowTypeNumber": 12,
    "confirmed": 1,
    "createdDatetime": "2026-07-15 21:34:15",
    "confirmedTime": "2026-07-15 21:35:02",
    "inUserId": 5027446,
    "operatorUserId": 5027446,
    "prevStockFlowId": "14127907",
    "actualTotalAmount": 24.00,
    "remarks": "",
    "suppliers": [
      {
        "supplierUid": "9001",
        "supplierName": "供应商A"
      }
    ],
    "stockFlowItems": [
      {
        "id": "94200894",
        "productUid": "781562237872544049",
        "productName": "商品a",
        "barcode": "abarcode",
        "categoryUid": "9001",
        "productUnitUid": "7001",
        "spec": "",
        "supplierUid": "9001",
        "supplierName": "供应商A",
        "purchaseQuantity": 4.000,
        "giftQuantity": 0.000,
        "receivedQuantity": 4.000,
        "purchasePrice": 5.00,
        "remarks": "",
        "productSnList": ["SN20260101001", "SN20260101002"]
      }
    ]
  }
}

单据级字段

字段	类型	说明
`id`	string	货流单主键 ID。
`uid`	string	货流单业务 UID。
`stockFlowNo`	string	货流展示号，由 `createdDatetime` 格式化为 `yyyyMMddHHmmss`，仅用于展示。
`stockflowTypeNumber`	int	货单类型，固定 `12`（进货单）。
`confirmed`	int	货流状态，含义见上方货流状态码。
`createdDatetime`	string	制单时间。
`confirmedTime`	string	货单完成或拒绝时间，为 null 时不返回。
`inUserId`	int	进货方门店 userId。
`operatorUserId`	int	操作门店 userId。
`prevStockFlowId`	string	上一张关联货流单 ID，为 null 时不返回。
`productRequestId`	string	关联订货单 ID，为 null 时不返回。
`productPurchaseId`	string	关联采购单 ID，为 null 时不返回。
`actualTotalAmount`	decimal	实际总金额，为 null 时不返回。
`remarks`	string	备注。
`suppliers`	array	单据涉及的供应商列表（按明细 supplierUid 去重），元素含 supplierUid、supplierName；无供应商时不返回。
`stockFlowItems`	array<object>	货流明细列表，字段见下方明细字段表。

明细字段

字段	类型	说明
`id`	string	货流明细 ID。
`productUid`	string	商品 UID。
`productName`	string	商品名称。
`barcode`	string	商品条码。
`categoryUid`	string	分类 UID。
`productUnitUid`	string	货流单位 UID，为空时不返回。
`spec`	string	规格，来自商品资料，为空时不返回。
`supplierUid`	string	供应商 uid，为 null 时不返回。
`supplierName`	string	供应商名称，为 null 时不返回。
`purchaseQuantity`	decimal	进货量。
`giftQuantity`	decimal	赠送量。
`receivedQuantity`	decimal	实收量。
`purchasePrice`	decimal	进货价。
`remarks`	string	明细备注。
`productSnList`	array<string>	商品序列号列表，仅含待确认和已确认的序列号；无序列号时不返回该字段。

查询出库/退货单详情

POST

/openapi/v3/stock-flow/outbound-detail

按货流单 id 查询退货单或出库单详情。支持 stockflowTypeNumber=14,17。

Token 消耗 300 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号。
`id`	long	是	货流单主键 ID，详情接口只按该字段查询。

请求示例

{
  "account": "store001",
  "id": 14127908
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "14127908",
    "uid": "17841224568520088",
    "stockFlowNo": "20260715213415",
    "stockflowTypeNumber": 17,
    "confirmed": 1,
    "createdDatetime": "2026-07-15 21:34:15",
    "confirmedTime": "2026-07-15 21:35:02",
    "outUserId": 5027446,
    "operatorUserId": 5027446,
    "remarks": "",
    "suppliers": [
      {
        "supplierUid": "9001",
        "supplierName": "供应商A"
      }
    ],
    "stockFlowItems": [
      {
        "id": "94200894",
        "productUid": "781562237872544049",
        "productName": "商品a",
        "barcode": "abarcode",
        "categoryUid": "9001",
        "productUnitUid": "7001",
        "spec": "",
        "supplierUid": "9001",
        "supplierName": "供应商A",
        "outQuantity": 1.000,
        "giftQuantity": 0.000,
        "outPrice": 5.00,
        "remarks": "",
        "productSnList": ["SN20260101001"]
      }
    ]
  }
}

单据级字段

字段	类型	说明
`id`	string	货流单主键 ID。
`uid`	string	货流单业务 UID。
`stockFlowNo`	string	货流展示号，由 `createdDatetime` 格式化为 `yyyyMMddHHmmss`，仅用于展示。
`stockflowTypeNumber`	int	货单类型，`14` 退货单 / `17` 出库单。
`confirmed`	int	货流状态，含义见上方货流状态码。
`createdDatetime`	string	制单时间。
`confirmedTime`	string	货单完成或拒绝时间，为 null 时不返回。
`outUserId`	int	出货方门店 userId。
`operatorUserId`	int	操作门店 userId。
`productRequestId`	string	关联订货单 ID，为 null 时不返回。
`productPurchaseId`	string	关联采购单 ID，为 null 时不返回。
`actualTotalAmount`	decimal	实际总金额，为 null 时不返回。
`remarks`	string	备注。
`suppliers`	array	单据涉及的供应商列表（按明细 supplierUid 去重），元素含 supplierUid、supplierName；无供应商时不返回。
`stockFlowItems`	array<object>	货流明细列表，字段见下方明细字段表。

明细字段

字段	类型	说明
`id`	string	货流明细 ID。
`productUid`	string	商品 UID。
`productName`	string	商品名称。
`barcode`	string	商品条码。
`categoryUid`	string	分类 UID。
`productUnitUid`	string	货流单位 UID，为空时不返回。
`spec`	string	规格，为空时不返回。
`supplierUid`	string	供应商 uid，为 null 时不返回。
`supplierName`	string	供应商名称，为 null 时不返回。
`outQuantity`	decimal	`14` 表示退货量；`17` 表示出库量。
`giftQuantity`	decimal	`14` 表示赠送退货量；`17` 表示赠送量。
`outPrice`	decimal	`14` 表示退货价；`17` 表示出库价。
`remarks`	string	备注。
`productSnList`	array<string>	商品序列号列表，仅含待确认和已确认的序列号；无序列号时不返回该字段。

查询调货/调拨退货单详情

POST

/openapi/v3/stock-flow/transfer-detail

按货流单 id 查询调货单或调拨退货单详情。支持 stockflowTypeNumber=13,16。

Token 消耗 300 token/次。

请求参数

参数	类型	必填	说明
`account`	string	是	业务账号。
`id`	long	是	货流单主键 ID，详情接口只按该字段查询。

请求示例

{
  "account": "store001",
  "id": 14127908
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "14127908",
    "uid": "17841224568520088",
    "stockFlowNo": "20260715213415",
    "stockflowTypeNumber": 13,
    "confirmed": 1,
    "createdDatetime": "2026-07-15 21:34:15",
    "confirmedTime": "2026-07-15 21:35:02",
    "outUserId": 5027446,
    "inUserId": 5027447,
    "operatorUserId": 5027446,
    "nextStockFlowId": "14127909",
    "inConfirmed": 1,
    "inConfirmedTime": "2026-07-15 21:36:02",
    "remarks": "",
    "suppliers": [
      {
        "supplierUid": "9001",
        "supplierName": "供应商A"
      }
    ],
    "stockFlowItems": [
      {
        "id": "94200894",
        "productUid": "781562237872544049",
        "productName": "商品a",
        "barcode": "abarcode",
        "categoryUid": "9001",
        "productUnitUid": "7001",
        "spec": "",
        "supplierUid": "9001",
        "supplierName": "供应商A",
        "outQuantity": 1.000,
        "receivedQuantity": 1.000,
        "transferPrice": 5.00,
        "remarks": "",
        "productSnList": ["SN20260101001"]
      }
    ]
  }
}

单据级字段

字段	类型	说明
`id`	string	货流单主键 ID。
`uid`	string	货流单业务 UID。
`stockFlowNo`	string	货流展示号，由 `createdDatetime` 格式化为 `yyyyMMddHHmmss`，仅用于展示。
`stockflowTypeNumber`	int	货单类型，`13` 调货单 / `16` 调拨退货单。
`confirmed`	int	货流状态，含义见上方货流状态码。
`createdDatetime`	string	制单时间。
`confirmedTime`	string	货单完成或拒绝时间，为 null 时不返回。
`outUserId`	int	出货方门店 userId。
`inUserId`	int	进货方门店 userId。
`operatorUserId`	int	操作门店 userId。
`nextStockFlowId`	string	下一张关联货流单 ID，为 null 时不返回。
`inConfirmed`	int	进货方确认状态，为 null 时不返回。
`inConfirmedTime`	string	进货方确认时间，为 null 时不返回。
`productRequestId`	string	关联订货单 ID，为 null 时不返回。
`productPurchaseId`	string	关联采购单 ID，为 null 时不返回。
`actualTotalAmount`	decimal	实际总金额，为 null 时不返回。
`remarks`	string	备注。
`suppliers`	array	单据涉及的供应商列表（按明细 supplierUid 去重），元素含 supplierUid、supplierName；无供应商时不返回。
`stockFlowItems`	array<object>	货流明细列表，字段见下方明细字段表。

明细字段

字段	类型	说明
`id`	string	明细 ID。
`productUid`	string	商品 UID。
`productName`	string	商品名称。
`barcode`	string	商品条码。
`categoryUid`	string	分类 UID。
`productUnitUid`	string	商品单位 UID，为空时不返回。
`spec`	string	规格，为空时不返回。
`supplierUid`	string	供应商 uid，为 null 时不返回。
`supplierName`	string	供应商名称，为 null 时不返回。
`outQuantity`	decimal	出货量。
`receivedQuantity`	decimal	收货量。
`transferPrice`	decimal	调货价。
`remarks`	string	明细备注。
`productSnList`	array<string>	商品序列号列表，仅含待确认和已确认的序列号；无序列号时不返回该字段。