商品库存变更查询

仅提供已授权的门店数据服务：调用时通过 clientStoreSn 定位门店，平台校验该门店已完成授权（即客户门店与收钱吧门店已完成映射）；未授权门店的商品库存变更数据无法查询。

1. 接口说明

按指定日期范围异步导出已授权门店的商品库存变更数据。开放平台受理请求后创建导出任务，任务完成后生成导出文件（库存流水明细 CSV、库存流水 movement Excel），再通过 notifyUrl 回调将下载链接通知开发者；任务失败时同样回调通知失败原因。

接口为异步导出模式：提交后立即返回受理结果，导出结果与任务状态通过回调通知异步获取，无需轮询。任务受理后异步执行导出，处理时长一般不超过 5 分钟，完成后通过 notifyUrl 回调通知开发者。

导出流程

1. 开发者发起查询请求，携带门店、日期范围、回调地址 notifyUrl。
2. 开放平台受理并创建该门店的商品库存变更导出任务。
3. 任务完成：开放平台回调 notifyUrl，downloadUrls 为结果文件下载链接集合。
4. 任务失败：开放平台回调 notifyUrl，携带失败原因（remark），请联系收钱吧运营人员处理。

2. 请求参数

请求示例

{
    "clientStoreSn": "SH001",
    "sqbStoreSn": "1580000003443730",
    "requestId": "req_001",
    "startTime": "2026-01-01",
    "endTime": "2026-01-31",
    "notifyUrl": "https://3rd.example.com/stock/notify"
}

3. 响应参数

接口为异步受理，响应 data 为受理结果，导出结果文件与任务状态通过回调通知异步获取：

3.1 受理结果

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "requestId": "req_001"
    }
}

3.2 回调通知（notifyUrl）

查询结果生成后，开放平台向请求中的 notifyUrl 发起回调通知：生成成功时携带结果文件下载链接，失败时携带失败原因。

回调请求（开放平台 → 开发者）

downloadUrls 结构说明

回调请求示例

{
    "msgId": "MSG20260101120000001",
    "requestId": "req_001",
    "clientStoreSn": "SH001",
    "downloadUrls": {
        "detailUrl": "https://files.3rd.example.com/stock/2026-01-01/req_001_detail.csv",
        "movementUrl": "https://files.3rd.example.com/stock/2026-01-01/req_001_movement.csv"
    },
    "status": "SUCCESS",
    "remark": null
}

回调验签

回调请求与主动调用接口复用同一套签名鉴权规范（见鉴权与签名）：签名参数通过请求头 X-AccessKey、X-Timestamp、X-Nonce、X-Signature 携带，接收方需使用自身 accessSecret 验签，验签不通过应丢弃该回调。防重放机制同样适用（X-Timestamp 与服务器时间差 ≤ 5 分钟，X-Nonce 5 分钟内不可重复使用）。

回调响应（开发者 → 开放平台）

回调必须遵循推送与回调机制，尤其是其中的响应要求（HTTP 200、Content-Type: application/json、Body 为 {"status": "success"}、3 秒内响应）为强制项，不满足即视为回调失败并触发重试；重试策略、幂等处理与消息兼容机制同见该文件。

4. 导出文件内容

导出文件包含两个文件：库存流水 movement 文件（Excel）与库存流水明细文件（CSV），分别对应回调 downloadUrls 中的 movementUrl 与 detailUrl。

4.1 库存流水 movement 文件（Excel）

每行一条商品的库存 movement 记录，字段如下：

示例（10 条）

4.2 库存流水明细文件（CSV）

导出文件为 CSV 格式，每行一条库存变更流水记录，由库存流水字段与商品信息字段拼接成宽表：

extra（Map）、extendBarcodes（List）等复合类型字段，以 JSON 字符串形式输出。

示例（10 条）

extra、extendBarcodes 等复合字段以 JSON 字符串形式输出，字段含逗号/引号时按 CSV 规则使用双引号包裹转义。

id,stockId,sqbStoreId,sqbStoreSn,clientStoreSn,bizScene,bizType,bizSn,operatorId,before,after,change,changeType,extra,ctime,mtime,spuId,clientSpuId,skuId,clientSkuId,skuName,title,pinyin,barcode,extendBarcodes,productType,saleType,unit,coverImage,description,sysCode,pluCode,saleStatus,status,categoryId,supplierId,brandId
10001,stock1001,store001,1580000003443730,SH001,retail,1,ORDER20260101001,OP001,50,48,-2,3,"{""source"": ""POS"", ""remark"": ""销售出库""}",1767571200000,1767571200000,9990418,SPU1001,9990418,SKU1001,默认,统一老坛泡椒面,tyltjpm,6925303797515,[],1,1,袋,,,JPM001,9990418,1,0,352984,50001,60001
10002,stock1001,store001,1580000003443730,SH001,retail,4,PO20260102001,OP001,48,68,20,2,"{""source"": ""ERP"", ""remark"": ""采购入库""}",1767571201000,1767571201000,9990418,SPU1001,9990418,SKU1001,默认,统一老坛泡椒面,tyltjpm,6925303797515,[],1,1,袋,,,JPM001,9990418,1,0,352984,50001,60001
10003,stock1002,store001,1580000003443730,SH001,retail,3,ADJ20260102001,OP001,80,78,-2,1,"{""source"": ""MANUAL"", ""remark"": ""盘点调整""}",1767571202000,1767571202000,9990099,SPU1002,9990099,SKU1002,默认,伊利纯牛奶250ml,ylcnn,6907992822716,[],1,1,盒,,,,,1,0,352984,50002,60002
10004,stock1003,store001,1580000003443730,SH001,retail,1,ORDER20260103001,OP001,100,97,-3,3,"{""source"": ""POS"", ""remark"": ""销售出库""}",1767571203000,1767571203000,9990111,SPU1003,9990111,SKU1003,330ml,可口可乐330ml,kkkl,6922255800510,[],1,1,瓶,,,,,1,0,352985,50003,60003
10005,stock1004,store001,1580000003443730,SH001,retail,5,RO20260103001,OP001,45,42,-3,3,"{""source"": ""POS"", ""remark"": ""退货出库""}",1767571204000,1767571204000,9990122,SPU1004,9990122,SKU1004,原味,乐事薯片原味,lssp,6924743915235,[],1,1,袋,,,,,1,0,352986,50004,60004
10006,stock1005,store001,1580000003443730,SH001,retail,6,ST20260104001,OP001,60,60,0,4,"{""source"": ""STOCKTAKE"", ""remark"": ""盘点无差异""}",1767571205000,1767571205000,9990133,SPU1005,9990133,SKU1005,默认,双汇王中王火腿肠,shwz,6901389631250,[],1,1,根,,,,,1,0,352984,50005,60005
10007,stock1001,store001,1580000003443730,SH001,retail,1,ORDER20260104001,OP001,68,65,-3,3,"{""source"": ""POS"", ""remark"": ""销售出库""}",1767571206000,1767571206000,9990418,SPU1001,9990418,SKU1001,默认,统一老坛泡椒面,tyltjpm,6925303797515,[],1,1,袋,,,JPM001,9990418,1,0,352984,50001,60001
10008,stock1003,store001,1580000003443730,SH001,retail,4,PO20260105001,OP001,97,117,20,2,"{""source"": ""ERP"", ""remark"": ""采购入库""}",1767571207000,1767571207000,9990111,SPU1003,9990111,SKU1003,330ml,可口可乐330ml,kkkl,6922255800510,[],1,1,瓶,,,,,1,0,352985,50003,60003
10009,stock1002,store001,1580000003443730,SH001,retail,7,LOSS20260105001,OP001,78,76,-2,3,"{""source"": ""MANUAL"", ""remark"": ""过期报损""}",1767571208000,1767571208000,9990099,SPU1002,9990099,SKU1002,默认,伊利纯牛奶250ml,ylcnn,6907992822716,[],1,1,盒,,,,,1,0,352984,50002,60002
10010,stock1004,store001,1580000003443730,SH001,retail,1,ORDER20260105001,OP001,42,40,-2,3,"{""source"": ""POS"", ""remark"": ""销售出库""}",1767571209000,1767571209000,9990122,SPU1004,9990122,SKU1004,原味,乐事薯片原味,lssp,6924743915235,[],1,1,袋,,,,,1,0,352986,50004,60004

5. 完整请求示例

5.1 请求示例

{
  "clientStoreSn": "SH001",
  "requestId": "req_001",
  "startTime": "2026-01-01",
  "endTime": "2026-01-31",
  "notifyUrl": "https://3rd.example.com/stock/notify"
}

5.2 响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "requestId": "req_001"
  }
}

6. 错误码

本接口业务错误码（51xxx 段）

完整错误码表见错误码。接口响应中的 code 为统一包装结果码，业务数据在 data 中体现。