开放 API（只读）

把老板管库的库存、商品与流水接进你自己的系统：标准 REST + JSON， Bearer 令牌鉴权，无需登录会话。

快速开始

登录老板管库，进「设置 → 开放接入」创建令牌：给令牌起个名字，勾选它能访问的数据（拿不准就选「只读分析」预设）。令牌明文只在创建时显示一次，泄露了随时吊销。
请求时带上认证头。Authorization 的值必须以 Bearer 开头（后面带一个空格）——只填令牌本身会一直收到 401：
```
curl "https://bossku.cn/api/open/v1/stock?limit=5" \
  -H "Authorization: Bearer bk_你的令牌"
```

通用约定

项	约定
Base URL	https://bossku.cn/api/open/v1
方法	全部端点只支持 GET；其他方法返回 405
金额	整数「厘」。1 元 = 1000 厘：retailPrice 3000 表示 3 元，300050 表示 300.05 元
时间	Unix 时间戳，epoch 毫秒（如 1789291200000）
业务日期	'YYYY-MM-DD' 文本（单据/流水的归属日，按北京时间）
数量	整数。库存流水的 delta 入库为正、出库为负
响应	UTF-8 JSON。列表端点分页：返回 offset / limit / total
认证	Authorization: Bearer <令牌>；401 对令牌不存在/已吊销/已过期统一返回，不区分原因

调用限额

免费版每天 300 次（REST 接口与 AI 助手 MCP 合计，按 UTC 日切重置）；专业版不限次数。
每个令牌每分钟最多 60 次，防止失控循环。
超限返回 429 与 Retry-After 响应头（秒数），等到期再重试即可。建议同步类场景按页拉全量（limit 拉大、减少请求次数），而不是高频小分页。

错误格式

出错时返回统一结构，code 是稳定的字符串枚举，适合程序分支：

{
  "error": { "code": "forbidden", "message": "当前令牌缺少权限：stock.read" }
}

code	HTTP	含义
unauthorized	401	缺少 Authorization 头、令牌无效/已吊销/已过期
forbidden	403	令牌权限不足（缺对应权限勾选）
not_found	404	端点不存在，或指定资源不属于本店
bad_request	400	参数不合法，message 会说明原因
rate_limited	429	超过每日额度或每分钟限速，看 Retry-After
internal	500	服务端内部错误，可稍后重试

权限对照

权限在创建令牌时逐项勾选，与员工权限同一套体系：

权限 key	解锁
stock.read	现存量 /stock、库存流水 /stock/movements、仓库 /warehouses、商品详情 /items/{id}
catalog.read	商品搜索 /items
cost.read	成本价字段（costPrice）。不勾选时响应里整个字段不出现，而不是返回 null

接口清单

GET/api/open/v1/stockstock.read

现存量明细：每个 SKU 在每个仓库一行（stocks 表原样）。支持条码精确查与关键词过滤，系统对接按页同步全量库存用这个端点。排序固定（商品名 → SKU → 仓库），offset 翻页稳定。

参数	说明
warehouseId	可选，只看这个仓库
itemId	可选，只看这个商品（所有规格）
skuId	可选，精确到单个规格
barcode	可选，条码精确匹配（规格条码或商品条码）
query	可选，关键词：名称 / 货号 / 条码 / 拼音首字母
offset	可选，翻页偏移，默认 0
limit	可选，单页条数，默认 200，最大 1000

{
  "total": 128,
  "offset": 0,
  "limit": 200,
  "rows": [
    {
      "itemId": 101,
      "itemName": "纯棉圆领T恤",
      "sn": "SP-T01",
      "skuId": 340,
      "skuName": "白色 / L",
      "barcode": "6901234500011",
      "warehouseId": 1,
      "warehouseName": "总店仓",
      "count": 42
    }
  ]
}

提示：要按条码查「现在还有多少件」，用 ?barcode=6901234500011，total 为 0 即无货。

GET/api/open/v1/itemscatalog.read

商品搜索：按名称 / 货号 / 条码 / 拼音首字母搜 SKU，带零售价与跨仓现存总量。不带 query 时按建档顺序全量翻页。

参数	说明
query	可选，关键词；留空 = 全量浏览
itemId	可选，传了则等价于 /items/{id} 返回完整资料
offset	可选，默认 0
limit	可选，默认 20，最大 50

{
  "total": 96,
  "offset": 0,
  "limit": 20,
  "results": [
    {
      "itemId": 101,
      "skuId": 340,
      "itemName": "纯棉圆领T恤",
      "sn": "SP-T01",
      "skuName": "白色 / L",
      "barcode": "6901234500011",
      "baseUnitName": "件",
      "retailPrice": 59000,
      "stock": 57
    }
  ]
}

retailPrice 59000 = 59 元。令牌勾选了 cost.read 时，结果里才会出现 costPrice（同为厘）。

GET/api/open/v1/items/{id}stock.read

单商品完整资料：商品档案 + 全部规格 + 每个规格的分仓库存。

{
  "item": {
    "id": 101,
    "name": "纯棉圆领T恤",
    "sn": "SP-T01",
    "barcode": "6901234500004",
    "baseUnitName": "件",
    "retailPrice": 59000,
    "warnLow": 10,
    "warnHigh": 500
  },
  "skus": [
    {
      "skuId": 340,
      "skuName": "白色 / L",
      "barcode": "6901234500011",
      "stockByWarehouse": [
        { "warehouseId": 1, "warehouseName": "总店仓", "count": 42 },
        { "warehouseId": 2, "warehouseName": "二店仓", "count": 15 }
      ]
    }
  ]
}

GET/api/open/v1/stock/movementsstock.read

库存流水：每一笔进出库，新的在前，带变动后结存。要重建某商品的库存变化过程，按 skuId 过滤后翻页拉全。

参数	说明
skuId	可选，只看这个规格
warehouseId	可选，只看这个仓库
reason	可选，流水原因：init / purchase / retail / transfer_out / transfer_in / stocktake / sales_out / purchase_in / manual 等
from	可选，起始业务日期 YYYY-MM-DD（按北京时间含当日）
to	可选，结束业务日期 YYYY-MM-DD（含当日）
offset	可选，默认 0
limit	可选，默认 50，最大 500

{
  "total": 312,
  "movements": [
    {
      "id": 9012,
      "skuId": 340,
      "warehouseId": 1,
      "reason": "retail",
      "orderId": 556,
      "delta": -2,
      "remark": "",
      "balanceAfter": 42,
      "operatorId": 1,
      "createdAt": 1789291200000
    }
  ]
}

GET/api/open/v1/warehousesstock.read

仓库 / 门店列表：stock 与流水里的 warehouseId 对号到这里。

{
  "warehouses": [
    { "id": 1, "name": "总店仓", "type": "warehouse" },
    { "id": 2, "name": "二店仓", "type": "store" }
  ]
}

顺便：同一枚令牌也能接 AI 助手

不想自己写代码的话，把令牌贴进 WorkBuddy、扣子、Claude Code 等 AI 助手（MCP 协议），用大白话就能查销售、利润、往来账，还能在预览确认后开单。配额与 REST 接口合计。接法见使用手册 · 接入 AI 助手。

最后更新：2026-09-04