仓库管理 API

概述

仓库管理系统 API 为外部分拣、入库、出库、盘点和查询流程提供标准化的数据接口。Mini API（/api/mini.php）通过 action 参数路由到不同的业务处理逻辑，统一返回 JSON。开放 API（/api.php）提供经典 HTTP 风格的查询端点。两者均支持 CORS 跨域。

小程序 Mini API

面向钉钉小程序，使用统一的 /api/mini.php 入口，通过 action 字段分发到不同的业务操作。请求和响应均使用 JSON 格式，支持 CORS。

开放 API

面向外部系统，使用 /api.php 入口，支持 GET/POST 传参。适用于 ERP、WMS 等外部系统对接，可以查询产品信息、库存余量等。

SSO 认证集成

所有 API 调用需携带有效的 SSO access_token。Token 通过 SSO 的 OAuth2 流程或密码登录接口获取。业务系统需要在请求中附加 Token 来完成身份认证和权限校验。

项目	说明
请求方法	`GET` / `POST`
内容格式	`application/json` / `application/x-www-form-urlencoded`
跨域支持	响应头包含 `Access-Control-Allow-Origin: *`
接口数量	Mini API 20 个 action / 开放 API 16 个 action

认证方式

所有 API 请求都需要携带有效的 SSO access_token。Token 可通过以下方式传入：

认证方式	示例	说明
Bearer Token	Header `Authorization: Bearer {token}`	SSO `access_token`，也可使用 `api_token`
X-Api-Token	Header `X-Api-Token: {token}`	自定义 Token 头
Body / Query	`access_token` 或 `api_token`	通过 JSON Body 或 Query 参数传递
用户身份参数	`sso_user_id` + `username`	兼容旧版 API 的用户身份传递方式，需附带 `real_name`、`dept_id` 等补充字段
用户 ID	`user_id`	仓库管理系统用户表中对应的 users 记录 ID

获取 access_token：请参考 OAuth2 授权码流程（Web SSO）或密码登录 REST API。 SSO 平台签发的 access_token 可直接在本系统使用，无需额外申请。

响应格式

{
  "success": true,
  "message": "操作成功",
  "data": { }
}

success 为 false 时表示请求失败，HTTP 状态码也会相应设置为 400 / 401 / 403 / 500，message 字段包含具体的错误原因。

小程序 Mini API

所有小程序接口使用统一入口 https://kucunguanli.xahrf.cn/api/mini.php，通过 action 参数区分不同的业务操作。每个 action 对应一套请求参数和响应格式。

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

验证身份

action: ping / whoami

校验人员凭证是否有效，返回用户信息与可访问仓库数量。

请求示例

{
    "action": "whoami",
    "access_token": "YOUR_TOKEN"
}

响应示例

{
  "success": true,
  "data": {
    "user": {
      "user_id": 1,
      "username": "zhangsan",
      "real_name": "张三",
      "role": "operator",
      "sso_user_id": 10001
    },
    "warehouse_count": 2
  }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

获取有权限的仓库结构

action: warehouse_tree / my_warehouses

返回当前人员可管理的仓库完整树：仓库 → 区域 → 货架 → 层位（仅启用节点）。

请求示例

{
    "action": "warehouse_tree",
    "access_token": "YOUR_TOKEN"
}

响应示例

{
  "success": true,
  "data": {
    "user": { "user_id": 1, "real_name": "张三" },
    "warehouses": [
      {
        "id": 1,
        "name": "主仓库",
        "code": "WH001",
        "areas": [
          {
            "id": 1,
            "name": "A区",
            "shelves": [
              {
                "id": 1,
                "name": "1号货架",
                "layers": [
                  { "id": 1, "name": "第1层", "level_no": 1, "code": "LY001" }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

入库

action: stock_in / inbound / upload_inbound

向指定库位增加库存并写入入库流水。推荐通过 product_id / sku / barcode 引用商品主数据，系统自动补全名称、规格、单位等信息。

请求参数

参数	类型	必填	说明
`layer_id`	int	是	目标库位（层）ID
`quantity`	number	是	入库数量
`product_id`	int	条件	商品 ID，与 sku / barcode / stock_id / item_name 选一
`sku`	string	条件	商品编码，须存在于商品主数据
`barcode`	string	条件	条形码，须存在于商品主数据
`stock_id`	int	条件	已有库存记录 ID，直接向该记录加量
`item_name`	string	条件	手动录入物品名称（非主数据入库时使用）
`spec`	string	否	规格型号
`unit`	string	否	计量单位，默认「件」
`min_quantity`	number	否	最低库存预警
`ref_no`	string	否	关联单号（如采购单号）
`remark`	string	否	备注

请求示例

{
    "action": "stock_in",
    "access_token": "YOUR_TOKEN",
    "layer_id": 12,
    "quantity": 10,
    "barcode": "6901234567890",
    "ref_no": "RK20260329001"
}

响应示例

{
  "success": true,
  "message": "入库成功",
  "data": {
    "movement_id": 101,
    "movement_type": "in",
    "product_id": 1,
    "stock": { "id": 5, "quantity": "10.00", "name": "螺丝" }
  }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

上传进出库记录

action: upload_movement / movement_upload

写入进出库流水并同步更新库存。入库可新建物品；出库/调整须指定已有库存。

请求参数

参数	类型	必填	说明
`movement_type`	string	是	in 入库 / out 出库 / adjust 调整（数量为调整后库存）
`layer_id`	int	是	库位（层）ID
`quantity`	number	是	变动数量（adjust 为调整后数量）
`stock_id`	int	否	库存记录 ID，出库/调整时推荐填写
`item_name`	string	条件	入库新物品时必填
`sku`	string	否	物料编码
`barcode`	string	否	条形码
`spec`	string	否	规格型号
`unit`	string	否	计量单位，默认「件」
`ref_no`	string	否	关联单号
`remark`	string	否	备注

请求示例

{
    "action": "upload_movement",
    "access_token": "YOUR_TOKEN",
    "movement_type": "out",
    "layer_id": 12,
    "stock_id": 5,
    "quantity": 2
}

响应示例

{
  "success": true,
  "message": "进出库记录已保存",
  "data": {
    "movement_id": 101,
    "movement_type": "out",
    "stock": { "id": 5, "quantity": 8, "name": "螺丝" }
  }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

上传调拨记录

action: upload_transfer / transfer_upload

从调出库位扣减库存、向调入库位增加库存，并写入调拨流水。

请求参数

参数	类型	必填	说明
`from_layer_id`	int	是	调出层位 ID
`to_layer_id`	int	是	调入层位 ID
`quantity`	number	是	调拨数量
`stock_id`	int	否	库存记录 ID
`sku`	string	否	无 stock_id 时可用编码定位
`barcode`	string	否	无 stock_id 时可用条码定位
`transfer_no`	string	否	调拨单号，留空自动生成
`remark`	string	否	备注

请求示例

{
    "action": "upload_transfer",
    "access_token": "YOUR_TOKEN",
    "stock_id": 5,
    "from_layer_id": 12,
    "to_layer_id": 18,
    "quantity": 3
}

响应示例

{
  "success": true,
  "message": "调拨记录已保存",
  "data": {
    "transfer_id": 20,
    "from_stock_id": 5,
    "to_stock_id": 8,
    "quantity": 3
  }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

上传盘点记录

action: upload_stocktake / stocktake_upload

批量提交盘点明细实盘数量。盘点单须先在后台「盘点管理」中创建并指定盘点人。

请求参数

参数	类型	必填	说明
`stocktake_id`	int	是	盘点单 ID
`items`	array	是	明细数组
`items[].item_id`	int	是	盘点明细 ID
`items[].actual_quantity`	number	是	实盘数量
`items[].remark`	string	否	备注
`complete`	bool	否	true 时全部录入后自动完成盘点

请求示例

{
    "action": "upload_stocktake",
    "access_token": "YOUR_TOKEN",
    "stocktake_id": 1,
    "complete": false,
    "items": [
        {
            "item_id": 101,
            "actual_quantity": 50
        },
        {
            "item_id": 102,
            "actual_quantity": 48
        }
    ]
}

响应示例

{
  "success": true,
  "message": "盘点记录已保存",
  "data": {
    "stocktake": { "id": 1, "count_no": "PD1A2B3C", "status": "counting" },
    "items": []
  }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

入库明细

action: stock_in_detail / inbound_detail

按进出库记录 ID 获取入库单详情（movement_type=in）。

请求参数

参数	类型	必填	说明
`id`	int	是	记录 ID，与 movement_id 二选一
`movement_id`	int	是	同 id

请求示例

{
    "action": "stock_in_detail",
    "access_token": "YOUR_TOKEN",
    "id": 101
}

响应示例

{
  "success": true,
  "data": { "id": 101, "movement_type": "in", "quantity": "10.00", "item_name": "螺丝" }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

出库明细

action: stock_out_detail / outbound_detail

按进出库记录 ID 获取出库单详情（movement_type=out）。

请求参数

参数	类型	必填	说明
`id`	int	是	记录 ID
`movement_id`	int	是	同 id

请求示例

{
    "action": "stock_out_detail",
    "access_token": "YOUR_TOKEN",
    "id": 102
}

响应示例

{
  "success": true,
  "data": { "id": 102, "movement_type": "out", "quantity": "2.00" }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

调拨明细

action: transfer_get / transfer_detail

按调拨记录 ID 获取详情，含调出/调入库位信息。

请求参数

参数	类型	必填	说明
`id`	int	是	调拨 ID，与 transfer_id 二选一
`transfer_id`	int	是	同 id

请求示例

{
    "action": "transfer_detail",
    "access_token": "YOUR_TOKEN",
    "id": 20
}

响应示例

{
  "success": true,
  "data": { "id": 20, "transfer_no": "DB1A2B3C", "quantity": "3.00" }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

盘点明细

action: stocktake_get / stocktake_detail

按盘点单 ID 获取详情，默认附带 items 明细列表。

请求参数

参数	类型	必填	说明
`id`	int	是	盘点单 ID，与 stocktake_id 二选一
`stocktake_id`	int	是	同 id
`with_items`	bool	否	是否返回 items，默认 true

请求示例

{
    "action": "stocktake_detail",
    "access_token": "YOUR_TOKEN",
    "id": 1
}

响应示例

{
  "success": true,
  "data": { "id": 1, "count_no": "PD1A2B3C", "items": [] }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

查询商品列表

action: product_search / products / product_list

分页搜索商品主数据，默认仅返回启用商品。结果含各 SKU 库存汇总。

请求参数

参数	类型	必填	说明
`keyword`	string	否	名称 / 编码 / 条码 / 规格 / 分类模糊搜索
`category`	string	否	按分类精确筛选
`status`	string	否	1 启用 / 0 停用 / all 全部，默认 1
`page`	int	否	页码，默认 1
`per_page`	int	否	每页条数，默认 20，最大 100

请求示例

{
    "action": "product_search",
    "access_token": "YOUR_TOKEN",
    "keyword": "螺丝",
    "page": 1
}

响应示例

{
  "success": true,
  "data": {
    "items": [{ "id": 1, "name": "螺丝", "sku": "PRA1B2C3", "stock_quantity": "25.00" }],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "pages": 1
  }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

获取商品详情

action: product_get / product_detail

按商品 ID、编码或条形码获取单条商品，含库存汇总。

请求参数

参数	类型	必填	说明
`id`	int	条件	商品 ID，与 sku / barcode 三选一
`product_id`	int	条件	同 id
`sku`	string	条件	商品编码
`barcode`	string	条件	条形码

请求示例

{
    "action": "product_get",
    "access_token": "YOUR_TOKEN",
    "barcode": "6901234567890"
}

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "name": "螺丝",
    "sku": "PRA1B2C3",
    "barcode": "6901234567890",
    "stock_quantity": "25.00"
  }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

新建商品

action: product_create / product_add

创建商品主数据。须为仓库管理员。商品编码 sku 留空时自动生成（PR + 6 位十六进制）。

请求参数

参数	类型	必填	说明
`name`	string	是	商品名称
`sku`	string	否	商品编码，留空自动生成
`barcode`	string	否	条形码，须唯一
`spec`	string	否	规格型号
`unit`	string	否	计量单位，默认「件」
`category_id`	int	否	商品分类 ID（推荐）
`category`	string	否	分类名称（须已存在且启用）
`min_quantity`	number	否	默认最低库存预警，默认 0
`remark`	string	否	备注
`status`	int	否	1 启用 / 0 停用，默认 1
`sort_order`	int	否	排序，默认 0

请求示例

{
    "action": "product_create",
    "access_token": "YOUR_TOKEN",
    "name": "螺丝",
    "category_id": 1,
    "barcode": "6901234567890",
    "spec": "M6*20"
}

响应示例

{
  "success": true,
  "message": "商品已创建",
  "data": { "id": 2, "name": "螺丝", "sku": "PRA1B2C3" }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

编辑商品

action: product_update / product_edit

更新商品主数据。须为仓库管理员。仅需传入 id 及要修改的字段。

请求参数

参数	类型	必填	说明
`id`	int	是	商品 ID，与 product_id 二选一
`product_id`	int	是	同 id
`name`	string	否	商品名称
`sku`	string	否	商品编码
`barcode`	string	否	条形码
`spec`	string	否	规格型号
`unit`	string	否	计量单位
`category_id`	int	否	商品分类 ID
`category`	string	否	分类名称
`min_quantity`	number	否	最低库存预警
`remark`	string	否	备注
`status`	int	否	1 启用 / 0 停用
`sort_order`	int	否	排序

请求示例

{
    "action": "product_update",
    "access_token": "YOUR_TOKEN",
    "id": 2,
    "name": "不锈钢螺丝",
    "category_id": 1
}

响应示例

{
  "success": true,
  "message": "商品已更新",
  "data": { "id": 2, "name": "不锈钢螺丝" }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

删除商品

action: product_delete / product_remove

删除商品主数据。须为仓库管理员。若该商品已有库存记录（按 sku 关联）则无法删除，请改为停用（status=0）。

请求参数

参数	类型	必填	说明
`id`	int	是	商品 ID，与 product_id 二选一
`product_id`	int	是	同 id

请求示例

{
    "action": "product_delete",
    "access_token": "YOUR_TOKEN",
    "id": 2
}

响应示例

{
  "success": true,
  "message": "商品已删除"
}

POST https://kucunguanli.xahrf.cn/api/mini.php

启用/停用商品

action: product_toggle_status / product_status_toggle / toggle_status

切换商品启用状态。须为仓库管理员。停用后入库等业务默认不再列出该商品。

请求参数

参数	类型	必填	说明
`id`	int	是	商品 ID，与 product_id 二选一
`product_id`	int	是	同 id

请求示例

{
    "action": "product_toggle_status",
    "access_token": "YOUR_TOKEN",
    "id": 2
}

响应示例

{
  "success": true,
  "message": "商品已停用",
  "data": { "id": 2, "status": 0 }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

获取商品分类

action: product_categories / product_category_list

返回已启用的商品分类列表（含 id、name），可用于筛选下拉与商品表单。

请求示例

{
    "action": "product_categories",
    "access_token": "YOUR_TOKEN"
}

响应示例

{
  "success": true,
  "data": [
    { "id": 1, "name": "五金" },
    { "id": 2, "name": "办公用品" }
  ]
}

POST https://kucunguanli.xahrf.cn/api/mini.php

新建商品分类

action: product_category_create / category_create

创建商品分类。须为仓库管理员。创建后可在商品管理中通过 category_id 引用。

请求参数

参数	类型	必填	说明
`name`	string	是	分类名称，须唯一
`remark`	string	否	备注
`status`	int	否	1 启用 / 0 停用，默认 1
`sort_order`	int	否	排序，默认 0

请求示例

{
    "action": "product_category_create",
    "access_token": "YOUR_TOKEN",
    "name": "五金",
    "sort_order": 0
}

响应示例

{
  "success": true,
  "message": "分类已创建",
  "data": {
    "id": 3,
    "name": "五金",
    "remark": "",
    "status": 1,
    "sort_order": 0
  }
}

POST https://kucunguanli.xahrf.cn/api/mini.php

编辑商品分类

action: product_category_update / category_update / category_edit

更新商品分类。须为仓库管理员。仅需传入 id 及要修改的字段；修改名称后会同步更新已关联商品的 category 字段。

请求参数

参数	类型	必填	说明
`id`	int	是	分类 ID，与 category_id 二选一
`category_id`	int	是	同 id
`name`	string	否	分类名称，须唯一
`remark`	string	否	备注
`status`	int	否	1 启用 / 0 停用
`sort_order`	int	否	排序

请求示例

{
    "action": "product_category_update",
    "access_token": "YOUR_TOKEN",
    "id": 3,
    "name": "五金配件",
    "sort_order": 10
}

响应示例

{
  "success": true,
  "message": "分类已更新",
  "data": {
    "id": 3,
    "name": "五金配件",
    "remark": "",
    "status": 1,
    "sort_order": 10
  }
}

GET / POST https://kucunguanli.xahrf.cn/api/mini.php

库存查询

action: inventory_search / inventory_list

以商品主数据为基准查询全部商品库存；无库存记录时数量为 0。可按仓库、分类、库位筛选，包含停用商品。

请求参数

参数	类型	必填	说明
`warehouse_id`	int	否	仓库 ID
`keyword`	string	否	商品名称/编码/分类模糊搜索
`category_id`	int	否	商品分类 ID
`category`	string	否	商品分类名称（与 category_id 二选一）
`area_id`	int	否	区域 ID
`shelf_id`	int	否	货架 ID
`layer_id`	int	否	层位 ID
`low_stock`	bool	否	仅低库存
`page`	int	否	页码，默认 1
`per_page`	int	否	每页条数，默认 20，最大 100

请求示例

{
    "action": "inventory_search",
    "access_token": "YOUR_TOKEN",
    "warehouse_id": 1,
    "category_id": 2
}

响应示例

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "螺丝刀",
        "sku": "PR001",
        "quantity": 100,
        "product_id": 5,
        "category": "五金",
        "category_id": 2,
        "area_id": 1,
        "shelf_id": 3,
        "layer_id": 8,
        "warehouse_name": "主仓库"
      }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "pages": 1
  }
}

开放 API

开放 API 入口为 https://kucunguanli.xahrf.cn/api.php，通过 action 参数路由。需要传递 api_token 或 access_token（或使用旧版的 username 模式认证）。

action	说明	参数
`tree`	仓库树（含管理人员）	`warehouse_id（可选）`
`list`	启用仓库列表	`—`
`location`	层位详情	`layer_id`
`inventory_search`	库存查询	`keyword, warehouse_id, category_id, category, area_id, shelf_id, layer_id, low_stock, page, per_page`
`inventory_movements`	进出库记录列表	`keyword, warehouse_id, movement_type, date_from, date_to, page`
`inventory_movement_detail`	进出库/入库/出库明细	`id / movement_id；可选 movement_type=in/out`
`inventory_transfers`	调拨记录列表	`keyword, warehouse_id, scope, status, date_from, date_to, page`
`inventory_transfer_detail`	调拨明细	`id / transfer_id`
`stocktake_search`	盘点单列表	`keyword, warehouse_id, status, page`
`stocktake_detail`	盘点单明细（含 items）	`id / stocktake_id；可选 with_items`
`stocktake_records`	盘点明细记录列表	`keyword, warehouse_id, stocktake_id, has_diff, date_from, date_to, page`
`stocktake_record_detail`	单条盘点明细	`id / item_id`
`product_search`	商品列表查询	`keyword, category, status, page, per_page`
`product_create / product_add`	新建商品（须仓库管理员）	`name（必填）, sku, barcode, spec, unit, category_id, category, min_quantity, remark, status, sort_order`
`product_update / product_edit`	编辑商品（须仓库管理员）	`id / product_id（必填）及要修改的字段`
`product_delete / product_remove`	删除商品（须仓库管理员）	`id / product_id（必填）；有库存记录时无法删除`

访问限制说明

限制项	说明
仓库系统本体访问限制	外部系统访问仓库 API 时需要仓库系统的管理员在后台配置相应的 API Token（也叫外部 Token）。API Token 可以在仓库系统后台的"系统设置 → API 配置"页面生成和管理。API Token 绑定到具体的用户，沿用该用户在仓库系统中的仓库访问权限。
仓库系统内部角色	仓库管理系统的管理员可以在后台为不同的 API Token 分配不同的数据查看范围。
用户创建限制（管理员 / 数据管理员）	仓库管理系统的管理员角色可以在后台管理用户账号（新增/禁用/分配仓库权限）。仓库管理员和数据管理员在对应仓库下有完整的数据操作权限。
普通用户（操作员 / 仓管员 / 质检员）	默认只能操作被分配到的仓库的数据，使用"操作员"角色的用户无法新增、修改和删除产品和仓库等基础信息。
SSO 集成身份	仓库系统通过 SSO 获取基础用户信息后，自动将用户所属部门与仓库系统中的仓库进行关联。

错误码说明

HTTP	说明
`401`	认证失败：access_token / api_token / 用户身份信息不对或已失效。
`400`	请求参数有误：action 参数缺失、参数格式不符合要求或参数值非法。
`403`	权限不足：用户无访问指定操作的权限或角色未分配。
`500`	服务器内部错误：出现系统异常，message 字段会包含具体的错误详情。如遇此错误请联系技术人员排查。

代码示例

小程序示例

dd.httpRequest({
  url: 'https://kucunguanli.xahrf.cn/api/mini.php',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  data: JSON.stringify({
    action: 'stock_in',
    access_token: token,
    layer_id: 12,
    quantity: 10,
    barcode: '6901234567890'
  }),
  success: (res) => {
    const body = typeof res.data === 'string' ? JSON.parse(res.data) : res.data;
    console.log(body);
  }
});

cURL 示例（开放 API）

curl 'https://kucunguanli.xahrf.cn/api.php?action=product_search&keyword=电缆&access_token=YOUR_TOKEN'