Skip to main content

OpenAPI

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" } },
});

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

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

无需提供任何认证信息,自动使用浏览器 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 });

安全机制​

  1. Token 时效 - 每个 Token 有效期为 10 分钟,过期后自动失效

  2. 签名验证 - 所有请求必须携带正确的 HMAC-SHA256 签名

  3. HTTPS 强制 - 生产环境强制使用 HTTPS 加密传输

  4. 应用隔离 - 每个应用只能访问授权的数据集

  5. 环境变量 - 敏感信息存储在环境变量,不提交到代码仓库

数据权限​

  • 应用隔离 - 每个应用只能访问授权的数据集

  • 字段权限 - 支持字段级别的访问控制

  • 行级权限 - 支持数据行级别的过滤

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 了吗?推荐按以下顺序学习:

  1. 快速开始 - 5 分钟完成第一个 API 调用

  2. 认证指南 - 深入了解三种认证模式和 Token 管理

  3. API 参考 - 查看完整的接口文档和高级用法

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

支持与反馈​

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

  • 📧 技术支持:向您的商务经理获取技术支持联系方式

  • 📚 开发文档:持续更新中

  • 💬 在线客服:工作日 9:00-18:00