OpenAPI 简介

欢迎使用 Lovrabet OpenAPI!这是一套安全、高效的数据接口服务,让您能够通过编程方式访问 Lovrabet 平台中的业务数据。

内测阶段

OpenAPI 目前处于 内测阶段,仅向部分合作伙伴开放。如需开通使用权限,请联系您的商务经理。

什么是 Lovrabet OpenAPI?

Lovrabet OpenAPI 是专为企业级应用设计的数据接口服务,采用基于 HMAC-SHA256 签名的认证机制,确保数据传输的安全性和完整性。

核心特性

🔐 安全认证 - 基于 HMAC-SHA256 签名,支持多种认证模式
🚀 开箱即用 - 官方 SDK 自动处理认证、签名、Token 管理
🌐 多环境支持 - 支持服务端(Node.js)和浏览器端
📊 强大查询 - 支持分页、排序、条件筛选等高级功能
📝 TypeScript - 完整的类型定义和智能提示
🛡️ 权限隔离 - 应用级别的数据权限控制

三种认证模式

根据运行环境和使用场景,OpenAPI 提供三种认证方式:

1. 服务端模式 - 使用 accessKey

适用场景: Node.js 服务端、SSR(服务端渲染)、API 路由

使用 accessKey 实时生成 Token,无需预先生成:

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY, // ✅ 从环境变量读取
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// 直接调用,SDK 自动处理认证
const users = await client.models.users.filter();

2. 浏览器 Token 模式 - 预生成 Token

适用场景: 浏览器端公开数据访问、未登录用户

服务端生成 Token,浏览器端使用:

// 步骤 1: 服务端生成 Token (如 Next.js API 路由)
import { generateOpenApiToken } from "@lovrabet/sdk";

export async function GET() {
  const result = await generateOpenApiToken({
    appCode: "your-app-code",
    datasetCode: "ds-001",
    accessKey: process.env.LOVRABET_ACCESS_KEY,
  });

  return Response.json(result); // { token, timestamp, expiresAt }
}

// 步骤 2: 浏览器使用 Token
const { token, timestamp } = await fetch("/api/token").then((r) => r.json());

const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

适用场景: 已登录用户访问私有数据

无需提供任何认证信息,自动使用浏览器 Cookie:

const client = createClient({
  appCode: "your-app-code",
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// 请求会自动携带用户的登录 Cookie
const users = await client.models.users.filter();

如何选择认证模式?

服务端? → 使用 accessKey 模式
浏览器 + 公开数据? → 使用预生成 Token 模式
浏览器 + 已登录用户? → 使用 Cookie 模式

适用场景

1. 数据集成与同步

将 Lovrabet 平台的业务数据集成到您的企业系统中:

BI 报表系统 - 定期同步数据到数据仓库,生成管理报表
ERP 集成 - 与企业 ERP 系统对接,实现数据互通
数据中台 - 作为数据源接入企业数据中台

2. 自定义应用开发

基于 Lovrabet 数据构建您的专属应用:

移动应用 - 为移动端提供数据接口支持
微信小程序 - 快速开发轻量级业务应用
Web 应用 - 构建定制化的 Web 管理系统

3. 数据分析与挖掘

利用 OpenAPI 进行深度数据分析:

实时监控 - 构建业务数据实时监控大屏
数据分析 - 导出数据进行统计分析和挖掘
趋势预测 - 基于历史数据进行业务预测

4. 自动化工作流

通过 API 实现业务流程自动化:

定时任务 - 自动执行数据查询和导出任务
事件触发 - 基于数据变化触发业务流程
批量处理 - 高效处理大批量数据查询

当前能力

功能范围

OpenAPI 目前已开放完整的 CRUD 操作(查询、创建、更新),支持应用级别的数据访问。删除操作暂时仅在 WebAPI(Cookie 认证)模式下可用。

已开放接口

OpenAPI 提供以下接口,基础地址为: https://runtime.lovrabet.com

接口	HTTP 路径	SDK 方法	功能描述
批量查询数据	`POST /openapi/data/get-list`	`getList(params?, sortList?)`	分页查询数据,支持条件筛选、多字段排序
查询单条数据	`POST /openapi/data/get-one`	`getOne(id)`	根据 ID 获取单条数据的完整详情
创建数据	`POST /openapi/data/create`	`create(data)`	创建新的数据记录
更新数据	`POST /openapi/data/update`	`update(id, data)`	更新已有数据记录(支持部分更新)

完整接口规范

更多详细的接口参数、请求/响应格式说明,请查看 API 参考 文档。

接口调用示例

// 批量查询(支持分页、排序、筛选)
const users = await client.models.users.filter(
  {
    currentPage: 1,
    pageSize: 20,
    status: "active", // 条件筛选
  },
  [
    { priority: SortOrder.DESC }, // 多字段排序
    { createTime: SortOrder.DESC },
  ]
);

// 查询单条数据
const user = await client.models.users.getOne(123);

// 创建数据
const newUser = await client.models.users.create({
  name: "John Doe",
  email: "john@example.com",
});

// 更新数据
const updated = await client.models.users.update(123, {
  status: "inactive",
});

认证方式

所有 OpenAPI 请求需要通过 HMAC-SHA256 签名认证,认证信息通过 HTTP Headers 传递:

Header 名称	说明	示例值
`X-Time-Stamp`	请求时间戳(毫秒)	1758903130713
`X-App-Code`	应用编码	app-c2dd52a2
`X-Dataset-Code`	数据集编码	0fefba76fe29440194841f4825df53ff
`X-Token`	HMAC-SHA256 签名	jdqqGtzecF2I6FIW...

SDK 会自动处理所有认证细节,无需手动添加这些 Headers。

即将开放

⏳ 删除操作 - OpenAPI 模式下的 delete() 方法(目前仅 WebAPI 模式支持)
⏳ Webhook 通知 - 数据变更时的实时推送通知
⏳ 批量操作 - 支持批量创建、更新、导入导出
⏳ 文件上传 - 支持文件字段的上传和管理

响应结构

所有 OpenAPI 接口都遵循统一的响应格式。

getList 响应格式

{
  "success": true,
  "msg": "操作成功",
  "data": {
    "paging": {
      "pageSize": 10,
      "totalCount": 100,
      "currentPage": 1
    },
    "tableData": [
      {
        "id": "123",
        "name": "示例数据",
        "status": "active",
        "gmt_create": "2024-01-01 12:00:00"
      }
    ],
    "tableColumns": [
      {
        "title": "ID",
        "dataIndex": "id"
      },
      {
        "title": "名称",
        "dataIndex": "name"
      }
    ]
  }
}

固定字段说明:

paging - 分页信息(总条数、当前页、每页条数)
tableData - 实际的数据列表数组
tableColumns - 表格列定义元数据,可用于动态构建 UI

安全最佳实践

重要安全提示

绝不要在浏览器端代码中暴露 accessKey!

❌ 错误做法:

// 危险!会暴露密钥
const client = createClient({
  accessKey: "sk_live_xxx", // ❌ 切勿这样做!
});

✅ 正确做法:

// 服务端:使用环境变量
const client = createClient({
  accessKey: process.env.LOVRABET_ACCESS_KEY,
});

// 浏览器:使用预生成的 token
const { token } = await fetch("/api/token").then((r) => r.json());
const client = createClient({ token });

安全机制

Token 时效 - 每个 Token 有效期为 10 分钟,过期后自动失效
签名验证 - 所有请求必须携带正确的 HMAC-SHA256 签名
HTTPS 强制 - 生产环境强制使用 HTTPS 加密传输
应用隔离 - 每个应用只能访问授权的数据集
环境变量 - 敏感信息存储在环境变量,不提交到代码仓库

数据权限

应用隔离 - 每个应用只能访问授权的数据集
字段权限 - 支持字段级别的访问控制
行级权限 - 支持数据行级别的过滤

SDK 支持

为了简化开发,我们提供了官方 SDK:

npm install @lovrabet/sdk
# 或
bun add @lovrabet/sdk

SDK 优势:

✅ 自动处理认证和签名
✅ 自动管理 Token 生命周期
✅ 完整的 TypeScript 类型支持
✅ 统一的错误处理

资源链接:

开通流程

1. 申请开通

请联系您的商务经理,提供以下信息:

公司名称和业务场景说明
预计调用量和并发需求
需要访问的数据集清单
技术联系人信息

2. 获取凭证

审核通过后,您将获得:

App Code - 应用唯一标识
Access Key - 访问密钥(请妥善保管)
Dataset Codes - 授权的数据集列表

技术规范

接口规范

协议: HTTPS
方法: POST
编码: UTF-8
格式: JSON

环境说明

环境	域名
生产环境	`https://runtime.lovrabet.com`

下一步

准备好开始使用 OpenAPI 了吗?推荐按以下顺序学习:

快速开始 - 5 分钟完成第一个 API 调用
认证指南 - 深入了解三种认证模式和 Token 管理
API 参考 - 查看完整的接口文档和高级用法

推荐从快速开始

如果是第一次使用,建议直接查看快速开始文档,通过实际例子快速上手。

支持与反馈

如需技术支持或有任何问题,请通过以下方式联系我们:

📧 技术支持:向您的商务经理获取技术支持联系方式
📚 开发文档:持续更新中
💬 在线客服:工作日 9:00-18:00

什么是 Lovrabet OpenAPI?​

核心特性​

三种认证模式​

1. 服务端模式 - 使用 accessKey​

2. 浏览器 Token 模式 - 预生成 Token​

3. 浏览器 Cookie 模式 - 使用用户登录态​

适用场景​

1. 数据集成与同步​

2. 自定义应用开发​

3. 数据分析与挖掘​

4. 自动化工作流​

当前能力​

已开放接口​

接口调用示例​

认证方式​

即将开放​

响应结构​

getList 响应格式​

安全最佳实践​

安全机制​

数据权限​

SDK 支持​

开通流程​

1. 申请开通​

2. 获取凭证​

技术规范​

接口规范​

环境说明​

下一步​

支持与反馈​