开放 API

灵途造币体验站 OpenAPI

面向 OpenClaw 和企业内部 Agent 的接口规范。第一版聚焦产品清单、库存查询、普通产品入库，以及普通产品和组合产品出库，所有请求通过用户个人 API Key 鉴权。

Base URL

https://demo.lingtuzaowu.com/api/v1

Auth Header

x-api-key

Version

v1

鉴权模型

API Key 由每个用户自行生成

API Key 绑定用户身份。服务端会校验 key 是否存在、是否撤销、是否过期、用户是否可用；库存接口不再做细分 scope 限制。

curl --location --request GET "https://demo.lingtuzaowu.com/api/v1/me" \
  --header "x-api-key: ltzj_xxx"
authenticated

所有有效 API Key 都可以调用库存读写接口；Key 仅用于识别操作人、审计和撤销。

接口文档

左侧选接口，右侧看请求和返回

入库只支持普通产品且单价必填；出库支持普通产品和组合产品，组合产品出库会按组件用量扣减库存。联调时先用 /me 校验 key，再通过产品清单拿 productId 和 locationId。

接口目录

基础

GET校验 API Key / 当前用户/me

库存

GET查询产品清单/inventory/productsGET查询库存矩阵/inventory/stockPOST批量普通产品入库/inventory/inboundPOST批量产品出库/inventory/outbound
GET

/me

校验 API Key / 当前用户

用于联调时确认 API Key 是否有效，以及它绑定到哪个用户。

authenticated

请求参数

位置字段类型必填说明
Headerx-api-keystring必填用户在个人资料页生成的 API Key。

请求示例

curl --location --request GET "https://demo.lingtuzaowu.com/api/v1/me" \
  --header "x-api-key: ltzj_xxx"

成功返回

{
  "ok": true,
  "user": {
    "id": "user_123",
    "name": "张三",
    "username": "zhangsan",
    "role": "ADMIN",
    "status": "ACTIVE"
  },
  "scopes": ["authenticated"]
}
GET

/inventory/products

查询产品清单

返回全部未删除产品，支持按关键词、分类和产品类型过滤。普通产品返回库存列表，组合产品返回组件列表和可售数。

authenticated

请求参数

位置字段类型必填说明
Querysearchstring选填匹配 SKU、名称等关键词。
Querycategorystring选填按产品分类过滤。
QuerykindSIMPLE | BUNDLE选填按普通产品或组合产品过滤。
Headerx-api-keystring必填用户 API Key。

请求示例

curl --location --request GET "https://demo.lingtuzaowu.com/api/v1/inventory/products?search=杯&kind=SIMPLE" \
  --header "x-api-key: ltzj_xxx"

成功返回

{
  "ok": true,
  "data": {
    "products": [
      {
        "id": "prod_123",
        "spuId": "spu_001",
        "spu": {
          "id": "spu_001",
          "spuCode": "CUP",
          "name": "随行杯"
        },
        "sku": "CUP-BLACK-001",
        "name": "黑色随行杯",
        "category": "成品",
        "unit": "个",
        "referencePrice": "39.90",
        "kind": "SIMPLE",
        "status": "ON_SALE",
        "color": "黑色",
        "specification": "500ml",
        "remark": null,
        "totalQuantity": 120,
        "bundleSellable": null,
        "stocks": [
          {
            "id": "stock_001",
            "locationId": "loc_sz",
            "locationName": "深圳仓",
            "quantity": 120
          }
        ],
        "components": [],
        "createdAt": "2026-06-21T08:30:00.000Z",
        "updatedAt": "2026-06-21T08:30:00.000Z"
      }
    ],
    "count": 1
  },
  "meta": {
    "generatedAt": "2026-06-21T08:30:00.000Z"
  }
}
GET

/inventory/stock

查询库存矩阵

返回所有地点、普通产品各地点库存，以及组合产品按组件推导出的各地点可售数。

authenticated

请求参数

位置字段类型必填说明
Headerx-api-keystring必填用户 API Key。

请求示例

curl --location --request GET "https://demo.lingtuzaowu.com/api/v1/inventory/stock" \
  --header "x-api-key: ltzj_xxx"

成功返回

{
  "ok": true,
  "data": {
    "locations": [
      {
        "id": "loc_sz",
        "name": "深圳仓"
      }
    ],
    "simpleProducts": [
      {
        "productId": "prod_123",
        "sku": "CUP-BLACK-001",
        "name": "黑色随行杯",
        "unit": "个",
        "category": "成品",
        "kind": "SIMPLE",
        "totalQuantity": 120,
        "stocks": [
          {
            "locationId": "loc_sz",
            "locationName": "深圳仓",
            "quantity": 120
          }
        ]
      }
    ],
    "bundleProducts": [
      {
        "productId": "bundle_001",
        "sku": "GIFT-001",
        "name": "礼盒套装",
        "unit": "套",
        "category": "成品",
        "kind": "BUNDLE",
        "totalSellable": 20,
        "perLocationSellable": [
          {
            "locationId": "loc_sz",
            "locationName": "深圳仓",
            "sellable": 20
          }
        ],
        "components": [
          {
            "componentProductId": "prod_123",
            "componentSku": "CUP-BLACK-001",
            "componentName": "黑色随行杯",
            "componentUnit": "个",
            "quantityPerBundle": 1,
            "stocks": [
              {
                "locationId": "loc_sz",
                "locationName": "深圳仓",
                "quantity": 120
              }
            ]
          }
        ]
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-06-21T08:30:00.000Z"
  }
}
POST

/inventory/inbound

批量普通产品入库

批量提交普通产品入库明细，一次最多 50 条。整批在一个事务内执行；任意一条失败，整批不会入库。

authenticated

请求参数

位置字段类型必填说明
Bodyitemsarray必填入库明细数组，1 到 50 条。
Bodyitems[].productIdstring必填普通产品 ID。
Bodyitems[].toLocationIdstring必填入库地点 ID。
Bodyitems[].quantitynumber | string必填正整数，范围 1 到 1000000。
Bodyitems[].unitCostnumber | string必填入库单价，最多两位小数。
Bodyitems[].supplierIdstring | null选填供应商 ID，最长 64 字符。
Bodyitems[].businessRefstring | null选填外部业务单号，最长 128 字符。
Bodyitems[].remarkstring | null选填备注，最长 500 字符。
Headerx-api-keystring必填用户 API Key。

请求示例

curl --location --request POST "https://demo.lingtuzaowu.com/api/v1/inventory/inbound" \
  --header "content-type: application/json" \
  --header "x-api-key: ltzj_xxx" \
  --data-raw '{
    "items": [
      {
        "productId": "prod_123",
        "toLocationId": "loc_sz",
        "quantity": 50,
        "unitCost": "12.30",
        "supplierId": "supplier_001",
        "businessRef": "PO-20260621-001",
        "remark": "OpenAPI 入库"
      },
      {
        "productId": "prod_456",
        "toLocationId": "loc_sz",
        "quantity": "20",
        "unitCost": "8.00",
        "businessRef": "PO-20260621-002"
      }
    ]
  }'

成功返回

{
  "ok": true,
  "data": {
    "itemCount": 2,
    "totalQuantity": 70,
    "movements": [
      {
        "index": 0,
        "movementId": "mov_123",
        "productId": "prod_123",
        "quantity": 50,
        "businessRef": "PO-20260621-001",
        "occurredAt": "2026-06-21T08:30:00.000Z"
      },
      {
        "index": 1,
        "movementId": "mov_124",
        "productId": "prod_456",
        "quantity": 20,
        "businessRef": "PO-20260621-002",
        "occurredAt": "2026-06-21T08:30:00.000Z"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-06-21T08:30:00.000Z"
  }
}
POST

/inventory/outbound

批量产品出库

批量提交普通产品或组合产品出库明细，一次最多 50 条。整批在一个事务内执行；任意一条库存不足，整批不会出库。

authenticated

请求参数

位置字段类型必填说明
Bodyitemsarray必填出库明细数组，1 到 50 条。
Bodyitems[].productIdstring必填普通产品 ID 或组合产品 ID。
Bodyitems[].fromLocationIdstring必填出库地点 ID。
Bodyitems[].quantitynumber | string必填正整数，范围 1 到 1000000。
Bodyitems[].businessRefstring | null选填外部业务单号，最长 128 字符。
Bodyitems[].remarkstring | null选填备注，最长 500 字符。
Headerx-api-keystring必填用户 API Key。

请求示例

curl --location --request POST "https://demo.lingtuzaowu.com/api/v1/inventory/outbound" \
  --header "content-type: application/json" \
  --header "x-api-key: ltzj_xxx" \
  --data-raw '{
    "items": [
      {
        "productId": "prod_123",
        "fromLocationId": "loc_sz",
        "quantity": 5,
        "businessRef": "SO-20260621-008"
      },
      {
        "productId": "bundle_001",
        "fromLocationId": "loc_sz",
        "quantity": 2,
        "businessRef": "SO-20260621-009",
        "remark": "OpenAPI 组合出库"
      }
    ]
  }'

成功返回

{
  "ok": true,
  "data": {
    "itemCount": 2,
    "totalQuantity": 7,
    "results": [
      {
        "index": 0,
        "productKind": "SIMPLE",
        "productId": "prod_123",
        "movementId": "mov_201",
        "quantity": 5,
        "businessRef": "SO-20260621-008",
        "occurredAt": "2026-06-21T08:30:00.000Z"
      },
      {
        "index": 1,
        "productKind": "BUNDLE",
        "bundleProductId": "bundle_001",
        "movements": [
          {
            "movementId": "mov_202",
            "componentProductId": "prod_456",
            "quantity": 2,
            "businessRef": "SO-20260621-009",
            "occurredAt": "2026-06-21T08:30:00.000Z"
          }
        ]
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-06-21T08:30:00.000Z"
  }
}
响应规范

给 Agent 稳定、可解释的数据契约

页面数据结构可以随 UI 演进，OpenAPI 响应需要保持兼容。v1 只做兼容新增字段，不删除、不改名已有字段。

统一响应

成功返回 ok、data、meta；失败返回 ok、error，error.code 使用稳定机器码。

分页限制

列表接口默认 limit=50，最大 limit=200。后续大数据量接口使用 cursor 翻页。

写入审计

入库和出库会记录操作人、API Key、业务单号和库存流水，便于追踪来源。

时间格式

所有时间使用 ISO 8601 字符串；from/to 查询参数按闭区间处理。

{
  "ok": true,
  "data": {},
  "meta": {
    "requestId": "req_xxx",
    "generatedAt": "2026-06-21T08:30:00.000Z"
  }
}
{
  "ok": false,
  "error": {
    "code": "insufficient_stock",
    "message": "库存不足，无法出库。"
  }
}
安全与审计

对外接口默认可追踪、可限流、可撤销

每次请求都写入 API 请求日志；入库和出库额外写入审计日志，记录操作人、API Key、业务单号和库存流水。

审计字段

请求日志记录 apiKeyId、userId、method、path、statusCode、IP 和 User-Agent。

库存口径

库存查询返回所有未删除产品，缺失库存记录按 0 计算，组合产品返回组件可售数。

稳定版本

破坏性变更进入 /api/v2；/api/v1 仅做兼容新增。

业务单号

写接口支持 businessRef，用于记录外部订单、调拨单或自动化任务编号。

StatusCodeDescription
401missing_api_key缺少 x-api-key 请求头。
401invalid_api_keyAPI Key 不存在或校验失败。
401revoked_api_keyAPI Key 已被用户撤销。
401expired_api_keyAPI Key 已过期。
403user_disabled绑定用户不是可用状态。
404product_not_found产品不存在或已删除。
409insufficient_stock库存不足，无法出库。
409insufficient_component_stock组合产品组件库存不足。