API 对接参考

概述

OpenOBA 通过 7 个标准 REST API 实现与任意企业系统的对接。无论你现有的系统是什么语言、什么架构，只要实现这 7 个接口，OpenOBA 的 Agent 就可以用自然语言操作你的系统。

认证方式

所有 API 请求需在 Header 中携带 API Key：

Authorization: Bearer <your-api-key>
Content-Type: application/json

API Key 在管理后台的「系统配置 → API 密钥」页面生成和管理。

7 个标准接口

方法	路径	说明
GET	/api/external/:entity	查询实体列表（支持分页、过滤、排序）
GET	/api/external/:entity/:id	查询单个实体详情
POST	/api/external/:entity	创建实体
PUT	/api/external/:entity/:id	更新实体
DELETE	/api/external/:entity/:id	删除实体（软删除）
GET	/api/external/:entity/count	统计实体数量
POST	/api/external/:entity/sync	批量同步数据

接口详解

查询列表

GET /api/external/products?page=1&limit=20&sort=createdAt&order=desc&filter[name]=眼镜

Query 参数：

参数	类型	说明
page	number	页码，默认 1
limit	number	每页条数，默认 20，最大 100
sort	string	排序字段
order	string	排序方向（asc / desc）
filter[field]	string	按字段模糊过滤

创建实体

POST /api/external/products
Content-Type: application/json

{
  "name": "经典圆框眼镜",
  "price": 299.00,
  "category": "EYEWEAR",
  "colorCode": "BK-001"
}

同步数据

POST /api/external/products/sync
Content-Type: application/json

{
  "mode": "upsert",
  "keyField": "externalId",
  "items": [
    { "externalId": "EXT-001", "name": "商品A", "price": 199 },
    { "externalId": "EXT-002", "name": "商品B", "price": 299 }
  ]
}

响应格式

所有接口统一返回以下格式：

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  },
  "timestamp": "2026-05-30T08:00:00.000Z"
}

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "字段 'price' 不能为空",
    "details": [{ "field": "price", "reason": "required" }]
  }
}

Entity 发现

可通过以下接口获取系统已注册的所有实体及其字段定义：

GET /api/external/entities

# 响应示例
{
  "success": true,
  "data": {
    "Product": {
      "fields": {
        "name": { "type": "String", "required": true },
        "price": { "type": "Float", "required": true },
        "category": { "type": "String", "required": true, "enum": ["EYEWEAR", ...] }
      },
      "aliases": { "售价": "retailPrice", "货号": "productCode" },
      "actions": ["create", "update", "remove", ...]
    }
  }
}

Agent 通过此接口自动了解系统结构，无需人工告知。

对接已有系统

场景一：你有系统源代码

在你的系统后端新增上述 7 个 API 端点，每个端点内部调用你现有的业务逻辑。工作量约 2-4 人天。

场景二：你没有源代码（旧系统/成品软件）

在旧系统外层构建一个轻量的 Adapter 服务（约 200 行代码），对外暴露标准 API，对内通过数据库直连或 HTTP 调用连接旧系统。或使用 OpenOBA 快速重构你的系统。