开放 API ​

Linker 提供基于 API Key 认证的数据开放接口，允许外部系统通过 HTTP 请求读写业务数据，无需用户登录。

适合场景：

  • 第三方系统集成
  • 外部数据同步
  • 内部系统之间调用 Linker

一、获取 API Key ​

API Key 由系统管理员在「系统设置 → 开放 API」页面创建。生成时需要指定：

  • 绑定用户：必填。Key 持有者将继承该用户的数据权限，可见范围和操作权限与该用户完全一致
  • 描述：可选。用于标识 Key 的用途，如「ERP 系统集成」
  • 过期时间：可选。不填则永不过期

创建完成后，Key 值仅在创建时完整显示一次，请立即复制保存，后续页面只显示打码后的形式（如 sk-****1234）。

管理员可以随时对 Key 执行：

  • 启用 / 禁用：禁用后调用立即失效
  • 删除：删除后调用立即失效

二、认证方式 ​

所有 /open/api/** 接口均需在请求头中携带 API Key：

http
X-Api-Key: <your-api-key>
Content-Type: application/json

请求示例：

http
POST /open/api/Customer/list
X-Api-Key: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Content-Type: application/json

认证失败时返回 HTTP 401：

json
{
  "code": 4012,
  "message": "无效的API Key"
}

常见原因：Key 不存在、已被禁用、已过期。

三、接口说明 ​

Base URL：http(s)://<host>:<port>

所有接口响应结构统一为：

json
{
  "code": 200,
  "message": "成功",
  "data": { ... }
}

3.1 分页查询数据 ​

POST /open/api/{entity}/list
参数位置说明
entityPath实体名，如 Customer、Order
请求体Body查询参数，见下方说明

请求体示例：

json
{
  "page": 1,
  "pageSize": 20,
  "columns": [
    { "name": "customerName" },
    { "name": "phone" },
    { "name": "createdTime" }
  ],
  "conditionEntry": {
    "conditionItems": [
      {
        "field": "customerName",
        "operator": "CONTAIN",
        "value": "张"
      }
    ],
    "type": "AND"
  },
  "sort": {
    "field": "createdTime",
    "order": "desc"
  }
}

请求体字段说明：

字段说明
page当前页，从 1 开始
pageSize页大小
columns查询列，cite 类型字段会自动带出引用对象的名称
conditionEntry查询条件（条件项 + 条件组）
sort排序，field 为字段名，order 为 asc / desc
checkRecycleBin是否检查回收站，默认 true

conditionEntry 说明：

  • conditionItems：条件项列表，每项为 { "field": 字段名, "operator": 操作符, "value": 值 }
  • type：条件项之间的组合方式，AND 或 OR
  • conditionEntries：嵌套条件组，用于更复杂的组合条件
  • rawCondition：原生 SQL 条件（高级用法）

支持的操作符（operator）：

操作符含义
EQ等于
NEQ不等于
GT大于
LT小于
GTEQ大于等于
LTEQ小于等于
CONTAIN包含（模糊匹配）
NIL为空
NNIL不为空
TODAY今天
YESTERDAY昨天
THISMONTH本月
LASTMONTH上月
THISYEAR本年
LASTYEAR去年
RECENTLYDAY最近 N 天
RECENTLYMONTH最近 N 个月
RECENTLYYEAR最近 N 年
SELF本人
THISDEPT本部门

响应示例：

json
{
  "code": 200,
  "message": "成功",
  "data": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "records": [
      {
        "customerId": "10010000000000001",
        "customerName": "张三",
        "phone": "138****1234",
        "createdTime": "2025-01-01 10:00:00"
      }
    ]
  }
}

3.2 获取单条记录 ​

GET /open/api/record?id={recordId}

示例：

http
GET /open/api/record?id=10010000000000001
X-Api-Key: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

记录不存在或已删除时返回 404。

3.3 新建 / 更新记录 ​

POST /open/api/record/save

请求体为 JSON 对象：

  • 请求体中不含 ID 字段 → 新建记录
  • 请求体中包含 ID 字段 → 更新该记录（仅传入的字段会被更新）

新建示例：

json
{
  "entityName": "Customer",
  "customerName": "李四",
  "phone": "13900001234"
}

更新示例：

json
{
  "entityName": "Customer",
  "customerId": "10010000000000001",
  "phone": "13900005678"
}

如需同时保存明细记录，可附加 DETAILS 数组：

json
{
  "entityName": "Order",
  "orderNo": "ORD-2025-001",
  "DETAILS": [
    {
      "entityName": "OrderItem",
      "productName": "产品A",
      "quantity": 2
    }
  ]
}

接口返回新建 / 更新记录的 ID。

3.4 删除记录 ​

DELETE /open/api/record/delete?ids={id1}&ids={id2}

支持批量删除，多个记录 ID 以多个 ids 参数传递。

四、记录 ID 说明 ​

系统中的记录 ID 是一个 18 位数字字符串，格式为：

{实体编码(4位)}{时间戳+随机数(14位)}

例如 10010000000000001，前 4 位 1001 表示该记录属于 Customer 实体。ID 在跨实体引用时携带了类型信息，请勿截断或修改。

五、权限说明 ​

API Key 绑定的用户决定了该 Key 能访问的数据范围：

  • 查询接口只能返回绑定用户权限范围内的数据。例如绑定用户只能查看「自己负责的客户」，则通过该 Key 查询也只能返回这部分数据
  • 写入操作（新建 / 更新 / 删除）同样受该用户权限约束，无权限时返回 403

建议

为外部系统集成专门创建一个系统用户，并为其分配合适的角色，再绑定到 API Key 上，避免使用管理员账号。

六、错误码参考 ​

code含义
200成功
4012无效的 API Key（不存在 / 已禁用 / 已过期）
403权限不足
404记录不存在或已删除
500系统异常

七、使用建议 ​

  • API Key 等同于一串长期有效的登录凭证，请妥善保管，避免泄露到公共代码仓库
  • 按用途分别创建 Key（如不同系统的集成各用一个），方便单独禁用和追溯
  • 对已不再使用的集成，及时在管理页面禁用或删除对应 Key
  • 需要批量或定时同步数据时，建议先小批量调用验证字段与权限，再全量执行

Linker