API 参考
FabHub 公共 API 的完整参考。品牌化门户为权威来源；你也可以将机器可读的契约载入任意 OpenAPI 查看器（Swagger Editor、Redoc、Postman 或你的 IDE）。
基础 URL
https://api.fabhub.app/v1
约定
- 使用
X-API-Key（或Authorization: Bearer）进行身份验证。参见身份验证。 - 请求主体为带
camelCase键名的 JSON；列表过滤器为snake_case查询参数。 - 列表端点为基于页码的分页，并返回
pagination对象；参见分页。 - 写端点需要
Idempotency-Key标头；参见幂等性。 - 错误使用带机器可读
code的稳定信封；参见错误。
所有端点
此表由 OpenAPI 契约生成，始终列出每个公共操作及其所需作用域。下方各小节为最常见资源的实战示例；OpenAPI 契约是请求与响应 schema 的详尽来源。
| 方法 | 路径 | 作用域 |
|---|---|---|
GET | /v1 | authenticated |
GET | /v1/audit/events | audit:read |
GET | /v1/auth/context | authenticated |
GET | /v1/contacts | contacts:read |
POST | /v1/contacts | contacts:write |
DELETE | /v1/contacts/{contact_id} | contacts:write |
GET | /v1/contacts/{contact_id} | contacts:read |
PATCH | /v1/contacts/{contact_id} | contacts:write |
GET | /v1/items | items:read |
POST | /v1/items | items:write |
DELETE | /v1/items/{item_id} | items:write |
GET | /v1/items/{item_id} | items:read |
PATCH | /v1/items/{item_id} | items:write |
GET | /v1/items/{item_id}/ingredients | items:read |
POST | /v1/items/{item_id}/ingredients | items:write |
DELETE | /v1/items/{item_id}/ingredients/{ingredient_id} | items:write |
PATCH | /v1/items/{item_id}/ingredients/{ingredient_id} | items:write |
GET | /v1/items/{item_id}/suppliers | items:read |
POST | /v1/items/{item_id}/suppliers | items:write |
DELETE | /v1/items/{item_id}/suppliers/{supplier_id} | items:write |
PATCH | /v1/items/{item_id}/suppliers/{supplier_id} | items:write |
GET | /v1/orders | orders:read |
POST | /v1/orders | orders:write |
GET | /v1/orders/{order_id} | orders:read |
PATCH | /v1/orders/{order_id} | orders:write |
GET | /v1/orders/{order_id}/lines | orders:read |
GET | /v1/organization | organization:read |
GET | /v1/stock-documents | inventory:read |
POST | /v1/stock-documents | inventory:write |
DELETE | /v1/stock-documents/{document_id} | inventory:write |
GET | /v1/stock-documents/{document_id} | inventory:read |
PATCH | /v1/stock-documents/{document_id} | inventory:write |
POST | /v1/stock-documents/{document_id}/approve | inventory:write |
POST | /v1/stock-documents/{document_id}/cancel | inventory:write |
GET | /v1/stock-documents/{document_id}/lines | inventory:read |
POST | /v1/stock-documents/{document_id}/lines | inventory:write |
DELETE | /v1/stock-documents/{document_id}/lines/{line_id} | inventory:write |
PATCH | /v1/stock-documents/{document_id}/lines/{line_id} | inventory:write |
POST | /v1/stock-documents/{document_id}/submit | inventory:write |
GET | /v1/stock-levels | inventory:read |
GET | /v1/usage | usage:read |
GET | /v1/webhooks | webhooks:read |
POST | /v1/webhooks | webhooks:write |
DELETE | /v1/webhooks/{webhook_id} | webhooks:delete |
GET | /v1/webhooks/{webhook_id} | webhooks:read |
PATCH | /v1/webhooks/{webhook_id} | webhooks:write |
GET | /v1/webhooks/{webhook_id}/deliveries | webhooks:deliveries:read |
服务
GET /v1
返回调用凭据可使用的能力（方法、路径、作用域）。无需作用域。
GET /v1/auth/context
返回调用凭据的租户、套餐、作用域、速率限制层级及过期时间。无需作用域。参见快速上手中的示例。
物料
GET /v1/items
作用域：items:read。列出物料（产品、材料、组合品）。
| 查询 | 类型 | 说明 |
|---|---|---|
page | integer | 从 1 开始的页码（默认 1） |
page_size | integer | 每页物料数（默认 20） |
search | string | 对名称/SKU 的自由文本匹配 |
curl "https://api.fabhub.app/v1/items?page=1&page_size=2&search=widget" \
-H "X-API-Key: $FABHUB_API_KEY"
{
"data": [
{
"id": "a1c9...",
"name": "Blue Widget",
"sku": "WIDG-BLUE",
"itemType": "product",
"salePrice": 19.99,
"purchasePrice": 8.5,
"isActive": true,
"category": { "id": "cat_1", "name": "Widgets" },
"supplier": { "id": "sup_1", "name": "Acme", "company": "Acme Ltd" },
"updatedAt": "2026-06-19T14:02:00Z"
}
],
"pagination": { "page": 1, "pageSize": 2, "total": 57, "totalPages": 29 }
}
POST /v1/items
作用域：items:write。需要 Idempotency-Key。创建一个物料。
| 主体字段 | 类型 | 说明 |
|---|---|---|
name | string | 必填 |
itemType | product | material | combo | 默认为 product |
sku、mpn、barcode | string | null | 可选标识符 |
categoryId、unitId、supplierId | string | null | 可选引用 |
salePrice、purchasePrice | number | null | 可选定价 |
supplierCode、notes | string | null | 可选 |
isActive | boolean | 默认为 true |
curl -X POST https://api.fabhub.app/v1/items \
-H "X-API-Key: $FABHUB_API_KEY" \
-H "Idempotency-Key: 0b9c4a2e-..." \
-H "Content-Type: application/json" \
-d '{"name":"Blue Widget","itemType":"product","salePrice":19.99}'
返回 { "data": { ...item } }，包含已创建的物料。
GET /v1/items/{item_id}
作用域：items:read。返回 { "data": { ...item } }，或返回 404 并带有 code: "NOT_FOUND"。
PATCH /v1/items/{item_id}
作用域：items:write。需要 Idempotency-Key。接受创建字段的任意子集，并返回更新后的物料。
物料子资源
GET /v1/items/{item_id}/ingredients（作用域items:read）- 用于combo/制造类物料的组件。GET /v1/items/{item_id}/suppliers（作用域items:read）- 关联到某个物料的供应商。
订单
GET /v1/orders
作用域：orders:read。
| 查询 | 类型 | 说明 |
|---|---|---|
module | buy | sell | make | check | fix | 必填 |
status | 订单状态 | 可选过滤（draft、open、in_progress、waiting、completed、cancelled） |
page、page_size、search | - | 标准列表参数 |
{
"data": [
{
"id": "ord_1",
"module": "sell",
"orderNumber": "SO-1042",
"status": "open",
"contactId": "con_7",
"orderDate": "2026-06-18",
"dueDate": "2026-06-25",
"siteId": null,
"priority": "normal",
"assignedTo": null,
"contact": { "id": "con_7", "name": "Globex" },
"site": null,
"createdAt": "2026-06-18T10:00:00Z",
"updatedAt": "2026-06-18T10:05:00Z"
}
],
"pagination": { "page": 1, "pageSize": 20, "total": 3, "totalPages": 1 }
}
订单还支持 POST /v1/orders、GET /v1/orders/{order_id} 和 PATCH /v1/orders/{order_id}（写操作需要 Idempotency-Key），以及用于行项目的 GET /v1/orders/{order_id}/lines（作用域 orders:read）。请参阅 OpenAPI 契约了解确切的请求主体。
联系人
GET /v1/contacts
作用域：contacts:read。
| 查询 | 类型 | 说明 |
|---|---|---|
contact_types | string | 以逗号分隔：customer、supplier、both |
page、page_size、search | - | 标准列表参数 |
每个联系人：id、name、email、phone、company、contactType、country、contactGroup、isPrimaryContact、isActive、updatedAt。
联系人还支持 POST /v1/contacts、GET /v1/contacts/{contact_id} 和 PATCH /v1/contacts/{contact_id}（写操作需要 Idempotency-Key）；字段请参阅 OpenAPI 契约。
组织
GET /v1/organization
作用域：organization:read。返回 { "data": { "id", "name", "slug", "plan", "createdAt" } }，其中 plan 为 free | standard | pro | enterprise。
用量
GET /v1/usage
作用域：usage:read。返回当前计费周期、请求总数（整体及按能力划分），以及速率限制层级和剩余额度。参见速率限制。
审计事件
GET /v1/audit/events
作用域：audit:read（企业版）。基于游标的分页导出。
| 查询 | 类型 | 说明 |
|---|---|---|
since、until | ISO 8601 | 时间窗口 |
action_prefix | string | 按动作前缀过滤 |
actor_type | user | system | api | 按行为者过滤 |
limit | integer | 页大小 |
cursor_created_at、cursor_id | - | 从上一页继续 |
{
"data": [
{
"id": "evt_1",
"actorType": "api",
"actorId": "key_8f...",
"action": "item.created",
"resourceType": "item",
"resourceId": "a1c9...",
"metadata": {},
"ipAddress": "203.0.113.10",
"createdAt": "2026-06-19T14:02:00Z"
}
],
"pagination": { "hasMore": true, "nextCursor": { "createdAt": "2026-06-19T14:02:00Z", "id": "evt_1" } }
}
库存
GET /v1/stock-levels
返回租户物料的当前库存水平（所需作用域见上表，过滤器及响应结构见 OpenAPI 契约）。
Webhook
完整的生命周期与签名细节请见 Webhook。
| 方法 | 路径 | 作用域 |
|---|---|---|
GET | /v1/webhooks | webhooks:read |
POST | /v1/webhooks | webhooks:write（企业版） |
GET | /v1/webhooks/{webhook_id} | webhooks:read |
PATCH | /v1/webhooks/{webhook_id} | webhooks:write |
DELETE | /v1/webhooks/{webhook_id} | webhooks:delete |
GET | /v1/webhooks/{webhook_id}/deliveries | webhooks:deliveries:read |