接口文档

1. 获取 API Key

1. 用公司管理员账号登录 智寻库存网页版(电脑端)。
2. 左侧菜单进入 API 令牌。
3. 点 颁发新令牌,填一个名字(比如「仓库扫码枪」「MES 对接」,方便以后区分)。
4. 在 开放接口权限 里只勾需要的:
   • 图像识别 — 能调拍照识别
   • 查码/查库存 — 能查物料和库存
   • 入库 / 出库 — 能改库存,按需单独授权
5. 点确定,弹窗里显示的 ss_live_… 就是你的 API Key。只显示这一次,请立刻复制保存;丢了只能「旋转」(换新的)或重新颁发。

Key 等同于账号密码,不要写进前端页面或手机 App 里,只放在你们自己的服务器上。泄露了就在 API 令牌页点「撤销」,立刻失效。想定期换 Key,用「旋转」,旧 Key 会保留一小段时间让你切换。

2. 认证

所有请求在请求头里带上 Key,基础地址是 https://zx.jsslab.com/api/open/v1:

curl https://zx.jsslab.com/api/open/v1/lookup?code=6901234567890 \
  -H "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx"

• 请求和响应都是 JSON(识别接口上传图片用 multipart/form-data)。
• Key 没有对应权限时返回 403 SCOPE_DENIED;Key 无效或已撤销返回 401 INVALID_TOKEN。
• 入库、出库必须带 Idempotency-Key 请求头(任意唯一字符串,建议用你们的单号)。同一个 key 重复请求,返回第一次的结果,不会重复入库或出库。结果缓存 24 小时。
• 一个 Key 只能操作它所属公司的数据,看不到别的公司。

3. 套餐说明

API 接入是收费套餐(标准版及以上)的功能,免费版不提供。

公司被停用或套餐到期后,所有接口会返回 403 COMPANY_INACTIVE。想升级套餐,请在官网价格页联系我们。

查询物料 GET /lookup

用条码、二维码内容、SKU 编码或物料编码,查到对应的物料。扫码枪扫到什么就把什么传给 code 即可。

需要权限:查码/查库存。找不到返回 404 NOT_FOUND。

# 请求
curl "https://zx.jsslab.com/api/open/v1/lookup?code=6901234567890" \
  -H "Authorization: Bearer $KEY"

# 响应 200
{
  "id": "0b8c…", "code": "M-0001", "name": "M3 螺丝",
  "specification": "M3×8 不锈钢", "unit": "个",
  "current_stock": 1200, "min_stock": 100,
  "has_sku": false, "sku_code": null,
  "barcodes": ["6901234567890"],
  "images": ["https://zx.jsslab.com/media/thumbnails/xxx.jpg"]
}

想让某个条码能被查到,先在网页版「物品管理」里给物料登记条码(一个物料可以有多个码:箱码、单品码、厂家码)。同一公司内一个码只能属于一个物料。

查库存 GET /stock

参数同 /lookup,额外返回每个仓库的库存。需要权限:查码/查库存。

curl "https://zx.jsslab.com/api/open/v1/stock?code=M-0001" -H "Authorization: Bearer $KEY"

# 响应 200(在上面的字段基础上多一个分仓明细)
{
  "code": "M-0001", "current_stock": 1200,
  "warehouses": [
    { "code": "WH001", "name": "主仓库", "quantity": 1000, "sku_code": null },
    { "code": "WH002", "name": "备件仓", "quantity": 200,  "sku_code": null }
  ]
}

拍照识别 POST /recognize

上传一张实物照片,返回库里最像的物料,按相似度从高到低。需要权限:图像识别。

curl https://zx.jsslab.com/api/open/v1/recognize \
  -H "Authorization: Bearer $KEY" \
  -F "image=@/path/to/photo.jpg" \
  -F "top_k=5"

# 响应 200,按相似度从高到低
{
  "results": [
    { "code": "M-0001", "name": "M3 螺丝", "current_stock": 1200,
      "similarity": 0.93, "barcodes": ["6901234567890"],
      "matched_image": "https://zx.jsslab.com/media/thumbnails/aaa.jpg",
      "images": ["https://zx.jsslab.com/media/thumbnails/aaa.jpg",
                 "https://zx.jsslab.com/media/thumbnails/bbb.jpg"], … },
    { "code": "M-0007", "name": "M3 垫片", "similarity": 0.71, … }
  ]
}

图片地址:每个结果带 images(这个物料登记过的全部照片,主图在前)和 matched_image(这次实际匹配上的那一张)。都是完整的 https 地址,不需要带 Key,可以直接放进 <img src> 显示,或者用浏览器/程序直接下载。/lookup 和 /stock 也有 images。没有照片的物料返回空数组。

对着实物拍,别用截图和网图;识别前要先在网页版给物料拍好照片入库,库里没有的东西认不出来。相似度仅供参考,建议你们的系统对 0.8 以下的结果让人工确认。

入库 POST /inbound

创建并直接确认一张入库单,库存立即增加。需要权限:入库。

curl https://zx.jsslab.com/api/open/v1/inbound \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: po-20261013-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse": "WH001",
    "remark": "采购到货",
    "items": [
      { "material_code": "M-0001", "quantity": 500, "unit_price": 0.12 },
      { "barcode": "6901234567891", "quantity": 20 }
    ]
  }'

# 响应 201
{
  "bill_no": "IN-20261013-7DCE05", "type": "IN", "status": "CONFIRMED",
  "warehouse": "WH001",
  "items": [
    { "material_code": "M-0001", "sku_code": null, "quantity": 500, "stock_after": 1700 },
    { "material_code": "M-0002", "sku_code": null, "quantity": 20,  "stock_after": 80 }
  ]
}

物料启用了 SKU 变体的,必须用 sku_code 指定到具体规格。接口产生的流水,操作人显示为「API:你的令牌名」,在网页版出入库记录里可以直接区分。

出库 POST /outbound

参数和入库完全一样。库存不足时整单失败、一行都不扣。需要权限:出库(建议只给确实要出库的 Key)。

curl https://zx.jsslab.com/api/open/v1/outbound \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: so-20261013-0001" \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "material_code": "M-0001", "quantity": 100 } ] }'

# 库存不足时 422,整单不写入
{
  "error": { "code": "REJECTED", "message": "单据未通过校验",
             "details": { "errors": ["M3 螺丝:库存不足,当前 50,需要 100"] } }
}

已确认的单据不能修改。录错了请在网页版「出入库单」里红冲更正。

错误码

出错时返回 {"error": {"code": "…", "message": "…"}}。

完整示例(Python)

拍照识别出是哪个物料,再出库 10 个:

import uuid, requests

BASE = "https://zx.jsslab.com/api/open/v1"
H = {"Authorization": "Bearer ss_live_xxxxxxxx"}

# 1. 拍照识别,找到是哪个物料
with open("photo.jpg", "rb") as f:
    hit = requests.post(f"{BASE}/recognize", headers=H, files={"image": f}).json()["results"][0]

# 2. 出库 10 个。Idempotency-Key 用你们系统的单号,网络重试不会重复出库
r = requests.post(f"{BASE}/outbound",
    headers={**H, "Idempotency-Key": "SO-10086"},
    json={"items": [{"material_code": hit["code"], "quantity": 10}]})
print(r.status_code, r.json())

常见问题

支持 OCR(识别文字)和 Webhook 回调吗?

暂时没有,后续版本会加。

条码、二维码是你们帮我识别图片里的码吗?

不是。接口接收的是已经扫出来的码内容(扫码枪、手机相机、你们自己的程序解码后的字符串),我们按内容去查物料。

一个 Key 能同时被多台设备使用吗?

可以,但建议一个系统一个 Key,出问题时可以单独撤销而不影响别的。

有调用频率限制吗?

读接口约 20 次/秒,写接口(入库、出库、识别)有更严格的限流,超出会返回 429。一般的业务调用不会碰到。

需要帮助?

把你的请求和响应(打码 Key)发给我们,会尽快回复。