仓库管理 API 文档 - 企业统一身份平台

概述

仓库管理系统支持按人员权限进行仓库结构查询、商品主数据维护、入库/出库/调拨/盘点等业务操作。

小程序业务 API

统一入口 /api/mini.php，通过 action 参数区分操作，支持 JSON 与表单提交，已开启 CORS。

开放查询 API

入口 /api.php，提供仓库、库存、流水、商品等只读查询能力。

SSO 统一鉴权

推荐使用 SSO access_token 标识操作人员，与统一身份平台账号体系打通。

项目	说明
请求方式	`GET` / `POST`
数据格式	`application/json` 或 `application/x-www-form-urlencoded`
跨域	小程序接口已开启 `Access-Control-Allow-Origin: *`
接口总数	小程序 17 组 / 开放查询 15 个 action

鉴权方式

所有接口均需标识操作人员，任选以下一种方式（推荐 SSO access_token）：

方式	传参位置	说明
Bearer Token	Header `Authorization: Bearer {token}`	SSO `access_token` 或本地 `api_token`
X-Api-Token	Header `X-Api-Token: {token}`	同上
Body / Query	`access_token` 或 `api_token`	表单或 JSON 字段
人员信息	`sso_user_id` + `username`	可选 `real_name`、`dept_id`；自动同步本地用户
本地用户 ID	`user_id`	仓库系统 users 表主键

获取 access_token：通过 OAuth2 授权码流程或账号密码登录 API 从 SSO 平台换取，再携带到仓库系统接口请求中。

响应格式

{
  "success": true,
  "message": "可选提示信息",
  "data": { }
}

失败时 success 为 false，HTTP 状态码通常为 400 / 401 / 403 / 500，message 为错误描述。

钉钉小程序 API

统一入口 https://kucunguanli.xahrf.cn/api/mini.php，在请求中携带 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`	int	否	1 启用 / 0 停用，默认 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": "不锈钢螺丝" }
}

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
  }
}

开放查询 API

入口 https://kucunguanli.xahrf.cn/api.php，须携带有效 api_token 或 access_token（不支持仅 username 鉴权）。

action	说明	主要参数
`tree`	仓库树（含管理人员）	`warehouse_id（可选）`
`list`	启用仓库列表	`—`
`location`	层位详情	`layer_id`
`inventory_search`	库存查询	`keyword, warehouse_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（必填）及要修改的字段`

权限说明

能力	权限要求
仓库结构查询	按仓库管理绑定过滤，仅返回有权限的节点
商品查询	所有已登录人员可用
商品新建 / 编辑	仓库管理员（平台管理员或已绑定仓库/区域/货架管理权限）
入库 / 出库 / 调拨	须对目标库位有管理权限
盘点上传	须为指定盘点人或仓库管理员

错误说明

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（开放查询）

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