API docs by Redocly

NexusBook OpenAPI (0.1.9)

Download OpenAPI specification:

NexusBook API Support: [email protected] URL: https://docs.nexusbook.app/support License: Apache 2.0 Terms of Service

NexusBook OpenAPI

🚀 NexusBook 是一个功能强大的开源文档管理和数据协作平台，为企业提供灵活的结构化数据管理、实时协作和供应链数据协同能力。

完整的 API 文档和开发指南

✨ 核心特性

📋 灵活的文档模型

  • 25+ 种字段类型：文本、数字、日期、附件、关联等
  • 多视图支持：表格、相册、看板、日历、文档视图
  • 自定义字段：支持不同行业的个性化扩展
  • 版本控制：完整的修订历史和回溯能力

🤝 实时协作

  • 多层级评论：文档级、字段级、行级评论系统
  • 审批工作流：可配置的变更审批流程
  • 请求与合并：类 Git 的数据变更管理
  • 并发控制：基于版本号的乐观锁机制

🔗 供应链数据协同

  • Catalog（商品目录）：供应商管理商品数据，支持行业自定义字段
  • OrderBook（订货本）：采购商基于 Connection 创建订货视图
  • Connection（连接）：供应商与采购商的数据共享通道
  • 字段映射：支持类型转换、单位转换、选项映射等 8 种转换类型
  • 智能过滤：嵌套条件组和自动接受/拒绝规则
  • 中间商支持：二级分销和多级数据传导

🔌 扩展能力

  • Webhooks：事件驱动的通知机制
  • 自动化集成：支持 Zapier、Make 等自动化平台
  • API Keys：安全的服务间调用
  • OAuth2/OIDC：企业级身份认证集成

🏗️ API 架构

主要命名空间

1️⃣ 文档管理 (/api/v1/doc)

  • Metadata（元数据）：字段定义、类型配置、验证规则
  • Views（视图）：表格/相册/看板/日历/文档视图管理
  • Data（数据）：结构化数据行的 CRUD 操作
  • Revisions（修订）：版本历史和回溯
  • Comments（评论）：多层级评论系统
  • Approvals（审批）：工作流审批管理
  • Requests（请求）：变更请求和合并
  • Settings（设置）：文档级和类型级配置

2️⃣ 供应链协同 (/api/v1/organizations/{orgId})

  • Catalog：商品目录管理，支持自定义字段
  • OrderBook：订货本管理，基于 Connection 自动生成
  • Connection：供应商-采购商数据连接（Outbound）
  • Binding：订货本数据绑定配置（Inbound），支持字段映射和接收过滤
  • Connector：组织内文档转换器（OrderBook → Catalog）

3️⃣ 租户管理 (/api/v1/users, /api/v1/organizations, /api/v1/workspaces)

  • Users：用户信息和偏好设置
  • Organizations：组织管理和成员邀请
  • Workspaces：工作区管理和权限控制

4️⃣ 扩展功能

  • Webhooks (/api/v1/webhooks)：事件订阅和投递管理
  • I18n (/api/v1/i18n)：国际化翻译服务
  • Billing (/api/v1/billing)：订阅和计费管理
  • Audit (/api/v1/audit)：审计日志查询

🚀 快速开始

认证

所有 API 请求需要在请求头中包含有效的 Bearer Token：

Authorization: Bearer <access_token>

获取 Token 的方式：

  1. 客户端凭证流程（服务间调用）：POST /auth/token
  2. 授权码流程（用户授权）：GET /auth/authorize → POST /auth/token
  3. API Keys：适用于 Webhook 验证和自动化集成

基础调用示例

# 1. 获取聚合文档包（包含元数据、视图和数据）
curl -H 'Authorization: Bearer TOKEN' \
  'https://open.nexusbook.app/api/v1/doc/product/doc-123?include=metadata,views,data'

# 2. 创建数据行
curl -X POST 'https://open.nexusbook.app/api/v1/doc/product/doc-123/data' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "row-1",
    "values": [
      {"fieldId": "name", "value": {"text": "iPhone 15 Pro"}},
      {"fieldId": "price", "value": {"number": 7999}},
      {"fieldId": "stock", "value": {"number": 100}}
    ]
  }'

# 3. 查询数据（高级查询）
curl -X POST 'https://open.nexusbook.app/api/v1/doc/product/doc-123/data/query' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "and": [
        {"field": "price", "op": "gte", "value": 5000},
        {"field": "stock", "op": "gt", "value": 0}
      ]
    },
    "sort": [{"field": "price", "order": "desc"}],
    "page": 1,
    "pageSize": 20
  }'

供应链协同示例

# 1. 供应商创建 Catalog
curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{
    "name": "电子产品目录",
    "catalogType": "product",
    "fields": [
      {"name": "品牌", "type": "text", "required": true},
      {"name": "型号", "type": "text", "required": true},
      {"name": "价格", "type": "currency", "required": true}
    ]
  }'

# 2. 供应商创建 Connection 并分享
curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/cat-456/connections' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{
    "name": "华东地区分销商",
    "shareScope": {"type": "all"},
    "accessControl": "public"
  }'

# 3. 采购商接受连接并创建 OrderBook
curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-789/orderbooks' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{
    "name": "供应商A订货本",
    "sourceConnectionIds": ["conn-111"]
  }'

# 4. 采购商配置 Binding（字段映射和过滤）
curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-789/orderbooks/ob-222/bindings' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{
    "connectionId": "conn-111",
    "fieldMapping": [
      {"sourceFieldId": "price", "targetFieldId": "cost", "transformType": "unit_convert",
       "unitConversion": {"fromUnit": "USD", "toUnit": "CNY", "rate": 7.2}}
    ],
    "receiverFilter": {
      "acceptMode": "selective",
      "filterGroup": {
        "operator": "AND",
        "conditions": [{"field": "price", "op": "lte", "value": 10000}]
      }
    }
  }'

📖 核心概念

文档包（Document Package）

NexusBook 的文档包含三个核心部分：

  • Metadata：定义文档结构（字段、类型、验证规则）
  • Views：定义数据展示方式（表格、看板、相册等）
  • Data：实际的结构化数据行

并发控制

所有数据行更新操作使用版本号（version）进行乐观锁控制：

{
  "id": "row-1",
  "version": 3,  // 必须提供当前版本号
  "values": [...]
}

如果版本号不匹配，API 将返回 409 Conflict 错误。

错误处理

所有错误响应遵循统一格式：

{
  "success": false,
  "code": "ERROR_CODE",
  "message": {
    "zh": "错误信息（中文）",
    "en": "Error message (English)"
  },
  "details": {  // 可选，提供额外的错误上下文
    "field": "price",
    "reason": "validation_failed"
  }
}

常见错误码：

  • UNAUTHORIZED：未授权或 Token 无效
  • FORBIDDEN：权限不足
  • NOT_FOUND：资源不存在
  • VALIDATION_ERROR：请求参数验证失败
  • CONFLICT：并发冲突（版本号不匹配）
  • RATE_LIMIT_EXCEEDED：请求频率超限

分页和查询

简单分页

GET /api/v1/doc/product/doc-123/data?page=1&pageSize=20

高级查询（POST 方式）

支持复杂过滤、排序、分组和聚合：

{
  "filter": {
    "and": [
      {"field": "status", "op": "eq", "value": "active"},
      {"or": [
        {"field": "category", "op": "eq", "value": "electronics"},
        {"field": "category", "op": "eq", "value": "computers"}
      ]}
    ]
  },
  "sort": [{"field": "createdAt", "order": "desc"}],
  "page": 1,
  "pageSize": 20
}

游标分页（深分页场景）

GET /api/v1/doc/product/doc-123/data?cursor=eyJ...&limit=100

📊 API 版本与环境

需要帮助？ 请访问我们的文档中心或加入开发者社区。

Users

获取当前用户信息

获取当前用户信息 Get current user info

返回当前登录用户的完整信息，包括默认组织和工作区。 Returns complete info of the current logged-in user, including default organization and workspace.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/users/me' \
  -H 'Authorization: Bearer TOKEN'

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新当前用户信息

更新当前用户信息 Update current user info

更新当前用户的个人信息和偏好设置。 Update personal information and preferences of the current user.

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/users/me' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "张三",
    "locale": "zh-CN",
    "timezone": "Asia/Shanghai"
  }'
Request Body schema: application/json
required
displayName
string

显示名称 Display name

avatarUrl
string

头像URL Avatar URL

locale
string

语言偏好 Language preference

timezone
string

时区 Timezone

defaultOrganizationId
string

默认组织ID Default organization ID

defaultWorkspaceId
string

默认工作区ID Default workspace ID

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "avatarUrl": "string",
  • "locale": "string",
  • "timezone": "string",
  • "defaultOrganizationId": "string",
  • "defaultWorkspaceId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 OAuth 连接

列出当前用户的 OAuth 连接 List current user's OAuth connections

获取当前用户已绑定的所有 OAuth 提供商列表。 Get the list of all OAuth providers bound to the current user.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/users/me/oauth' \
  -H 'Authorization: Bearer TOKEN'

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

绑定 OAuth 提供商

绑定 OAuth 提供商 Bind OAuth provider

将第三方 OAuth 提供商与当前用户账号关联。 Associate a third-party OAuth provider with the current user account.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/users/me/oauth/github' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "authorizationCode": "AUTH_CODE_FROM_GITHUB"
  }'
path Parameters
provider
required
string (Tenant.OAuthProvider)
Enum: "google" "github" "wechat" "dingtalk" "feishu"

OAuth 提供商名称 OAuth provider name

Request Body schema: application/json
required

绑定请求 Bind request

authorizationCode
required
string

OAuth 授权码 OAuth authorization code

redirectUri
string

重定向 URI Redirect URI

Responses

Request samples

Content type
application/json
{
  • "authorizationCode": "string",
  • "redirectUri": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

解绑 OAuth 提供商

解绑 OAuth 提供商 Unbind OAuth provider

移除当前用户与指定 OAuth 提供商的关联。 Remove the association between current user and specified OAuth provider.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/users/me/oauth/github' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
provider
required
string (Tenant.OAuthProvider)
Enum: "google" "github" "wechat" "dingtalk" "feishu"

OAuth 提供商名称 OAuth provider name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

列出用户加入的组织

列出用户加入的组织 List user's organizations

返回用户作为成员的所有组织列表，包含角色信息。 Returns the list of all organizations where the user is a member, including role information.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/users/me/organizations?page=1&pageSize=20' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
page
integer <int32>
Default: 1

页码（从1开始） Page number (starts from 1)

pageSize
integer <int32>
Default: 20

每页数量 Page size

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Organizations

创建组织

创建组织 Create organization

创建一个新组织，创建者自动成为 owner，并自动创建一个默认工作区。 Create a new organization. The creator automatically becomes the owner, and a default workspace is created automatically.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "我的团队",
    "slug": "my-team",
    "type": "team",
    "description": "团队描述"
  }'
Request Body schema: application/json
required
name
required
string

组织名称（必填） Organization name (required)

slug
required
string

URL标识（必填，全局唯一） URL slug (required, globally unique)

displayName
string

显示名称 Display name

description
string

组织描述 Organization description

type
required
string
Enum: "personal" "team" "enterprise"

组织类型 Organization type

object

组织设置 Organization settings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "displayName": "string",
  • "description": "string",
  • "type": "personal",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取组织详情

获取组织详情 Get organization detail

返回组织的详细信息，包括当前用户的角色和统计数据。 Returns detailed organization information including current user's role and statistics.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新组织信息

更新组织信息 Update organization info

更新组织的基本信息和设置。需要 owner 或 admin 权限。 Update organization's basic information and settings. Requires owner or admin permission.

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "新的显示名称",
    "description": "更新后的描述"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required

更新请求 Update request

name
string

组织名称 Organization name

displayName
string

显示名称 Display name

description
string

组织描述 Organization description

logoUrl
string

Logo URL Logo URL

object

组织设置 Organization settings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "logoUrl": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除组织

删除组织 Delete organization

软删除组织（标记为 archived）。仅 owner 可以执行此操作。 Soft delete organization (mark as archived). Only owner can perform this action.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

离开组织

离开组织（用户主动） Leave organization (user initiated)

用户主动离开组织。owner 不能离开，需先转让所有权。 User leaves the organization voluntarily. Owner cannot leave without transferring ownership first.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/leave' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

列出组织成员

列出组织成员 List organization members

获取组织的所有成员列表，支持按角色、状态过滤和搜索。 Get the list of all organization members, supporting filtering by role, status and search.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/members?page=1&pageSize=20&role=admin' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

role
string (Tenant.OrganizationRole)
Enum: "owner" "admin" "member" "guest"

按角色过滤 Filter by role

status
string (Tenant.MemberStatus)
Enum: "active" "suspended"

按状态过滤 Filter by status

search
string

搜索成员（名称、邮箱） Search members (name, email)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

添加组织成员

添加组织成员（直接添加） Add organization member (direct add)

直接将用户添加为组织成员。需要 owner 或 admin 权限。 Directly add a user as an organization member. Requires owner or admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/members' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user-456",
    "role": "member"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required

添加成员请求 Add member request

userId
required
string

用户ID（必填） User ID (required)

role
string
Default: "member"
Enum: "owner" "admin" "member" "guest"

角色（默认 member） Role (default: member)

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "role": "member"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取组织成员详情

获取组织成员详情 Get organization member detail

获取指定成员的详细信息。 Get detailed information of a specified member.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/members/member-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

memberId
required
string

成员ID Member ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新成员角色

更新成员角色 Update member role

更新组织成员的角色或状态。需要 owner 或 admin 权限。 Update organization member's role or status. Requires owner or admin permission.

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/members/member-789' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "admin"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

memberId
required
string

成员ID Member ID

Request Body schema: application/json
required

更新请求 Update request

role
string
Enum: "owner" "admin" "member" "guest"

新角色 New role

status
string
Enum: "active" "suspended"

状态 Status

Responses

Request samples

Content type
application/json
{
  • "role": "owner",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

移除组织成员

移除组织成员 Remove organization member

从组织中移除成员。需要 owner 或 admin 权限，不能移除 owner。 Remove a member from the organization. Requires owner or admin permission. Cannot remove owner.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/members/member-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

memberId
required
string

成员ID Member ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

Workspaces

创建工作区

创建工作区 Create workspace

在组织下创建新工作区。需要 organization.owner 或 organization.admin 权限。 Create a new workspace under the organization. Requires organization.owner or organization.admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品团队",
    "slug": "product-team",
    "description": "产品开发工作区",
    "visibility": "private"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required

创建请求 Create request

name
required
string

工作区名称（必填） Workspace name (required)

slug
required
string

URL标识（组织内唯一，必填） URL slug (unique within organization, required)

description
string

工作区描述 Workspace description

icon
string

工作区图标 Workspace icon

color
string

主题颜色 Theme color

visibility
string
Default: "private"
Enum: "public" "private"

可见性（默认 private） Visibility (default: private)

Array of objects (Tenant.DataSourceReference)

数据源引用配置 Data source reference configuration

允许工作区引用其他工作区的特定 document type 数据。 Allows workspace to reference specific document types from other workspaces.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "description": "string",
  • "icon": "string",
  • "color": "string",
  • "visibility": "private",
  • "dataSourceReferences": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出组织的工作区

列出组织的工作区 List organization's workspaces

获取组织下所有工作区列表，仅返回用户有权限访问的工作区。 Get the list of all workspaces under the organization. Only returns workspaces the user has permission to access.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces?page=1&pageSize=20' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

visibility
string (Tenant.WorkspaceVisibility)
Enum: "public" "private"

过滤可见性 Filter by visibility

includeArchived
boolean
Default: false

是否包含归档的工作区 Whether to include archived workspaces

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取工作区详情

获取工作区详情 Get workspace detail

返回工作区的详细信息。需要是工作区成员。 Returns detailed workspace information. Requires workspace membership.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新工作区信息

更新工作区信息 Update workspace info

更新工作区的基本信息。需要 workspace.owner 权限。 Update workspace's basic information. Requires workspace.owner permission.

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "新的工作区名称",
    "description": "更新后的描述"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

Request Body schema: application/json
required

更新请求 Update request

name
string

工作区名称 Workspace name

description
string

工作区描述 Workspace description

icon
string

工作区图标 Workspace icon

color
string

主题颜色 Theme color

visibility
string
Enum: "public" "private"

可见性 Visibility

Array of objects (Tenant.DataSourceReference)

数据源引用配置 Data source reference configuration

允许工作区引用其他工作区的特定 document type 数据。 Allows workspace to reference specific document types from other workspaces.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "icon": "string",
  • "color": "string",
  • "visibility": "public",
  • "dataSourceReferences": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除工作区

删除工作区 Delete workspace

软删除工作区。需要 workspace.owner 或 organization.owner 权限。 Soft delete workspace. Requires workspace.owner or organization.owner permission.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

归档工作区

归档工作区 Archive workspace

归档工作区。需要 workspace.owner 或 organization.owner/admin 权限。 Archive workspace. Requires workspace.owner or organization.owner/admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/archive' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出工作区成员

列出工作区成员 List workspace members

获取工作区的所有成员列表。需要是工作区成员。 Get the list of all workspace members. Requires workspace membership.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/members' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

query Parameters
page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

role
string (Tenant.WorkspaceRole)
Enum: "owner" "editor" "viewer"

按角色过滤 Filter by role

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

添加工作区成员

添加工作区成员 Add workspace member

将用户添加为工作区成员。需要 workspace.owner 权限。用户必须是组织成员。 Add a user as workspace member. Requires workspace.owner permission. User must be organization member.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/members' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user-789",
    "role": "editor"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

Request Body schema: application/json
required

添加成员请求 Add member request

userId
required
string

用户ID（必填，必须是组织成员） User ID (required, must be organization member)

role
string
Default: "editor"
Enum: "owner" "editor" "viewer"

角色（默认 editor） Role (default: editor)

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "role": "editor"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取工作区成员详情

获取工作区成员详情 Get workspace member detail

获取指定成员的详细信息。 Get detailed information of a specified member.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/members/member-999' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

memberId
required
string

成员ID Member ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新工作区成员角色

更新工作区成员角色 Update workspace member role

更新工作区成员的角色或状态。需要 workspace.owner 权限。 Update workspace member's role or status. Requires workspace.owner permission.

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/members/member-999' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "viewer"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

memberId
required
string

成员ID Member ID

Request Body schema: application/json
required

更新请求 Update request

role
string
Enum: "owner" "editor" "viewer"

新角色 New role

status
string
Enum: "active" "suspended"

状态 Status

Responses

Request samples

Content type
application/json
{
  • "role": "owner",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

移除工作区成员

移除工作区成员 Remove workspace member

从工作区移除成员。需要 workspace.owner 权限。 Remove a member from the workspace. Requires workspace.owner permission.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/members/member-999' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

memberId
required
string

成员ID Member ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

恢复归档的工作区

恢复归档的工作区 Restore archived workspace

恢复已归档的工作区。需要 workspace.owner 或 organization.owner/admin 权限。 Restore an archived workspace. Requires workspace.owner or organization.owner/admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/restore' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Invitations

通过令牌获取邀请信息

通过令牌获取邀请信息 Get invitation by token

使用邀请令牌获取邀请详情（用于邀请接受页面展示）。 Get invitation details using invitation token (for invitation acceptance page display).

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/invitations/TOKEN_STRING' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
token
required
string

邀请令牌 Invitation token

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

接受邀请

接受邀请 Accept invitation

通过邀请令牌接受邀请加入组织。验证邮箱匹配后创建成员记录。 Accept an invitation to join the organization using invitation token. Creates member record after email verification.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/invitations/TOKEN_STRING/accept' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
token
required
string

邀请令牌 Invitation token

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

拒绝邀请

拒绝邀请 Decline invitation

拒绝邀请加入组织。 Decline an invitation to join the organization.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/invitations/TOKEN_STRING/decline' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
token
required
string

邀请令牌 Invitation token

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

创建邀请

创建邀请 Create invitation

邀请用户加入组织。需要 owner 或 admin 权限。 Invite a user to join the organization. Requires owner or admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/invitations' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "role": "member",
    "message": "欢迎加入我们的团队！",
    "expiresInDays": 7
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required

创建邀请请求 Create invitation request

email
required
string

被邀请人邮箱（必填） Invitee email (required)

role
string
Default: "member"
Enum: "owner" "admin" "member" "guest"

邀请角色（默认 member） Invited role (default: member)

message
string

邀请留言 Invitation message

expiresInDays
integer <int32>
Default: 7

有效期（天数，默认7天） Expiration days (default: 7)

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "role": "member",
  • "message": "string",
  • "expiresInDays": 7
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出组织邀请

列出组织邀请 List organization invitations

获取组织的所有邀请列表。需要 owner 或 admin 权限。 Get the list of all invitations of the organization. Requires owner or admin permission.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/invitations?status=pending' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

status
string (Tenant.InvitationStatus)
Enum: "pending" "accepted" "expired" "revoked"

按状态过滤 Filter by status

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取邀请详情

获取邀请详情 Get invitation detail

获取指定邀请的详细信息。 Get detailed information of a specified invitation.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/invitations/inv-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

invitationId
required
string

邀请ID Invitation ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

撤销邀请

撤销邀请 Revoke invitation

撤销未接受的邀请。需要 owner 或 admin 权限，或是邀请创建者。 Revoke an unaccepted invitation. Requires owner or admin permission, or being the inviter.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/invitations/inv-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

invitationId
required
string

邀请ID Invitation ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

Join Requests

申请加入组织

申请加入组织 Apply to join organization

提交加入组织的申请。前置条件：用户未加入该组织，组织允许申请加入。 Submit an application to join the organization. Prerequisites: user is not a member, organization allows join requests.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/join-requests' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "我希望加入贵团队，我有5年相关经验..."
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required

创建申请请求 Create request

message
string

申请说明 Application message

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出加入申请

列出加入申请 List join requests

获取组织的所有加入申请列表。需要 owner 或 admin 权限。 Get the list of all join requests of the organization. Requires owner or admin permission.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/join-requests?status=pending' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

status
string (Tenant.JoinRequestStatus)
Enum: "pending" "approved" "rejected" "cancelled"

按状态过滤 Filter by status

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取加入申请详情

获取加入申请详情 Get join request detail

获取指定加入申请的详细信息。 Get detailed information of a specified join request.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/join-requests/req-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

requestId
required
string

申请ID Request ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

取消加入申请

取消加入申请（用户主动） Cancel join request (user initiated)

用户取消自己的加入申请。仅申请创建者本人可操作。 User cancels their own join request. Only the applicant can perform this action.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/join-requests/req-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

requestId
required
string

申请ID Request ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

批准加入申请

批准加入申请 Approve join request

批准用户的加入申请，创建组织成员记录并发送通知。需要 owner 或 admin 权限。 Approve user's join request, create member record and send notification. Requires owner or admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/join-requests/req-789/approve' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "member",
    "reviewNote": "欢迎加入！"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

requestId
required
string

申请ID Request ID

Request Body schema: application/json
required

批准请求 Approve request

role
string
Enum: "owner" "admin" "member" "guest"

授予的角色（默认使用组织默认角色） Granted role (default: use organization default role)

reviewNote
string

审核备注 Review note

Responses

Request samples

Content type
application/json
{
  • "role": "owner",
  • "reviewNote": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

拒绝加入申请

拒绝加入申请 Reject join request

拒绝用户的加入申请并发送通知。需要 owner 或 admin 权限。 Reject user's join request and send notification. Requires owner or admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/join-requests/req-789/reject' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "reviewNote": "很抱歉，暂时不符合我们的要求"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

requestId
required
string

申请ID Request ID

Request Body schema: application/json
required

拒绝请求 Reject request

reviewNote
required
string

拒绝原因 Rejection reason

Responses

Request samples

Content type
application/json
{
  • "reviewNote": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Core

类型设置

获取文档类型公共设置。

Get type-level settings.

path Parameters
docType
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新类型设置

更新文档类型公共设置。

Update type-level settings.

path Parameters
docType
required
string
Request Body schema: application/json
required
defaultViewId
string

默认视图ID Default view id

object

分享配置

permissions
any

权限策略 Permissions policy

object

保留策略

Responses

Request samples

Content type
application/json
{
  • "defaultViewId": "string",
  • "sharing": {
    },
  • "permissions": null,
  • "retention": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取聚合文档包

获取聚合文档包（支持 include 选择与分页）

Fetch aggregated doc bundle (supports include selection and pagination)

一次性获取文档的所需数据：通过 include 指定返回部分（如 metadata,views,data,comments,revisions,settings）， 支持视图分页（page/pageSize）与限制数量（commentsLimit/revisionsLimit）。

Fetch aggregated doc bundle with selective sections via include (e.g. metadata,views,data,comments,revisions,settings), supports view paging (page/pageSize) and limits (commentsLimit/revisionsLimit).

示例（cURL）:

curl -H 'Authorization: Bearer TOKEN' \
  'https://open.nexusbook.app/api/v1/doc/product/123?include=metadata,views,data&page=1&pageSize=20'
path Parameters
docType
required
string
docId
required
string
query Parameters
include
string
viewId
string
page
integer <int32>
pageSize
integer <int32>
commentsLimit
integer <int32>
revisionsLimit
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取文档元数据

返回字段定义与显示配置，供渲染与校验使用。

Returns field definitions and display settings for rendering and validation.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新文档元数据

更新字段与显示配置，需具备管理权限。

Update fields and display settings, requires manage permission.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
required
Array of objects (Document.Field)

数据行字段定义 Data row field definitions

定义数据行（表格行）的字段结构。 Defines the field structure for data rows (table rows).

Array of objects (Document.Field)

文档属性字段定义 Document property field definitions

定义文档级别属性的字段结构（如订单时间、总金额等）。 Defines the field structure for document-level properties (e.g., order time, total amount).

这些字段定义用于 DocumentProperties.properties 中的值。 These field definitions are used for values in DocumentProperties.properties.

Responses

Request samples

Content type
application/json
{
  • "fields": [
    ],
  • "properties": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

文档设置

获取文档级设置。

Get doc-level settings.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新文档设置

更新文档级设置。

Update doc-level settings.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
defaultViewId
string

默认视图ID Default view id

object

分享配置

permissions
any

权限策略 Permissions policy

object

保留策略

Responses

Request samples

Content type
application/json
{
  • "defaultViewId": "string",
  • "sharing": {
    },
  • "permissions": null,
  • "retention": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Data

列出数据

以分页返回数据行，支持简单 DSL 查询参数（page/pageSize/sort/filter/group/cursor）。

List rows with pagination, supports simple DSL query parameters (page/pageSize/sort/filter/group/cursor).

数据叠加读取

如果提供 requestId 参数，返回的数据将是： 生产数据 + Request 变更的叠加视图。

If requestId is provided, the returned data will be: Production data + Request changes merged view.

示例：

# 查看生产数据
GET /api/v1/doc/product/123/data

# 预览变更效果（叠加 Request 变更）
GET /api/v1/doc/product/123/data?requestId=req-abc

# 查看变更详情（包含变更标记）
GET /api/v1/doc/product/123/data?requestId=req-abc&includeChanges=true
path Parameters
docType
required
string
docId
required
string
query Parameters
page
integer <int32>
pageSize
integer <int32>
sort
string
filter
string
group
string
cursor
string
requestId
string
includeChanges
boolean

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建数据行

创建数据行（进入变更请求）

Create data row (goes into change request)

创建的数据行会添加到指定的变更请求中，不会立即生效。 Created row will be added to the specified change request, not applied immediately.

  • 如果指定 requestId，追加到该请求
  • 如果不指定，创建新的请求或追加到默认请求
  • 多人可以编辑同一个请求
  • 请求合并后才真正生效

Request workflow:

  • If requestId specified, append to that request
  • If not specified, create new request or append to default request
  • Multiple users can edit the same request
  • Changes apply only after request is merged

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/doc/product/123/data?requestId=req-1' \\
  -H 'Authorization: Bearer TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{"id":"row-1","values":[{"fieldId":"name","value":{"text":"新产品"}}]}'
path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
Request Body schema: application/json
required
id
required
string

行ID Row id

数据行唯一标识。 Unique identifier of the row.

required
Array of objects (Common.ValueEntry)

字段值集合 Field values

字段ID与值的集合。 Collection of field ids and values.

createdAt
string

创建时间 Created at

创建时间戳。 Created timestamp.

object

创建人 Created by

创建者。 Author.

updatedAt
string

更新时间 Updated at

更新时间戳。 Updated timestamp.

object

更新人 Updated by

更新者。 Updater.

version
integer <int64>

版本（并发控制） Version

版本号用于并发控制。 Version number for concurrency control.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "values": [
    ],
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string",
  • "updatedBy": {
    },
  • "version": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

批量更新

批量更新数据和属性（进入变更请求）

Bulk update data and properties (goes into change request)

灵活的批量更新接口，支持：

  • 修改单个/多个字段
  • 修改单行/多行
  • 修改单个/多个属性
  • 值始终保持简单（原始格式）

Flexible bulk update interface supporting:

  • Update single/multiple fields
  • Update single/multiple rows
  • Update single/multiple properties
  • Values always stay simple (raw format)

示例（cURL）：

# 1. 修改单个字段
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {"target": {"row": "row-1", "field": "price"}, "value": 99.99}
]'

# 2. 修改整行
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {
    "target": {"row": "row-1"},
    "value": {"price": 99.99, "name": "iPhone 15", "stock": 50}
  }
]'

# 3. 修改多行的同一字段
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {
    "target": {"rows": ["row-1", "row-2", "row-3"], "field": "status"},
    "value": "active"
  }
]'

# 4. 修改多行的同一字段（不同值）
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {
    "target": {"rows": ["row-1", "row-2", "row-3"], "field": "price"},
    "value": [99.99, 88.88, 77.77]
  }
]'

# 5. 修改单个属性
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {"target": {"property": "amount"}, "value": 5000.00}
]'

# 6. 修改多个属性
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {
    "target": {"properties": true},
    "value": {"amount": 5000.00, "quantity": 100, "date": "2024-12-05"}
  }
]'

# 7. 混合更新（数据 + 属性）
curl -X POST '.../data/bulk?requestId=req-1' -d '[
  {"target": {"row": "row-1", "field": "price"}, "value": 99.99},
  {"target": {"property": "amount"}, "value": 5000.00}
]'

服务端处理逻辑：

  1. 根据 docId 获取 metadata
  2. 对每个 target，解析目标类型（行/属性）
  3. 查找字段定义获取类型
  4. 将原始值转换为类型化值
  5. 验证值的有效性
  6. 添加到指定的 Request

Server processing:

  1. Get metadata by docId
  2. For each target, parse target type (row/property)
  3. Lookup field definition to get type
  4. Convert raw value to typed value
  5. Validate value
  6. Add to specified Request
path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
Request Body schema: application/json
required
Array
target
required
object

目标（灵活结构） Target (flexible structure)

支持多种目标指定方式：

  • {row: "row-1"} - 单行
  • {row: "row-1", field: "price"} - 单行单字段
  • {rows: ["row-1", "row-2"], field: "status"} - 多行同一字段
  • {property: "amount"} - 单个属性
  • {properties: true} - 多个属性
  • {row: "row-1", delete: true} - 删除单行
  • {rows: ["row-1", "row-2"], delete: true} - 删除多行
  • {condition: {...}, field: "status"} - 按条件更新
  • {condition: {...}, delete: true} - 按条件删除

Supports multiple target specification methods:

  • {row: "row-1"} - Single row
  • {row: "row-1", field: "price"} - Single row single field
  • {rows: ["row-1", "row-2"], field: "status"} - Multiple rows same field
  • {property: "amount"} - Single property
  • {properties: true} - Multiple properties
  • {row: "row-1", delete: true} - Delete single row
  • {rows: ["row-1", "row-2"], delete: true} - Delete multiple rows
  • {condition: {...}, field: "status"} - Conditional update
  • {condition: {...}, delete: true} - Conditional delete
value
any

值（原始格式，可以是单值、对象或数组） Value (raw format, can be single value, object or array)

根据 target 的不同，value 可以是：

  • 单个原始值：99.99, "text", true
  • 对象（多个字段）：{price: 99.99, name: "iPhone"}
  • 数组（多行不同值）：[99.99, 88.88, 77.77]

Depending on target, value can be:

  • Single raw value: 99.99, "text", true
  • Object (multiple fields): {price: 99.99, name: "iPhone"}
  • Array (different values for multiple rows): [99.99, 88.88, 77.77]

服务端根据 metadata 自动解析值的类型。 Server auto-parses value type based on metadata.

注意：删除操作（delete: true）不需要提供 value。 Note: Delete operations (delete: true) do not require value.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

结构化查询数据

以结构化体进行复杂查询（嵌套过滤、排序、分页）。

Perform complex query with structured body (nested filters, sorts, pagination).

注意：如果需要分组查询，请使用 /query/group 接口。 Note: For group queries, use /query/group endpoint.

数据叠加读取

支持通过 requestId 查询参数获取叠加后的数据视图。 Supports requestId query parameter for merged data view.

path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
includeChanges
boolean
Request Body schema: application/json
required
object

过滤 Filters

嵌套过滤组合。 Nested filter groups.

Array of objects (Common.Sort)

排序 Sorts

排序条件集合。 Sort conditions.

object

分组与聚合 Group and aggregations

分组字段与聚合函数。 Group fields and aggregation functions.

page
integer <int32>

页码 Page number

页码（默认1）。 Page number (default 1).

pageSize
integer <int32>

每页数量 Page size

每页数量（默认20，最大200）。 Page size (default 20, max 200).

cursor
string

游标 Cursor

游标用于深分页。 Cursor for deep pagination.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "sorts": [
    ],
  • "group": {
    },
  • "page": 0,
  • "pageSize": 0,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

分组查询数据

分组查询接口（支持多级分组与聚合）

Group query endpoint (supports multi-level grouping and aggregations)

该接口专门用于分组查询，返回树状结构的分组结果。 This endpoint is specifically for grouped queries, returning tree-structured group results.

多级分组示例

单级分组 (Single-level grouping)

{
  "filters": {...},
  "group": {
    "fields": ["category"],
    "aggregations": [
      {"kind": "count", "field": "*"},
      {"kind": "sum", "field": "amount"}
    ]
  }
}

二级分组 (Two-level grouping)

{
  "group": {
    "fields": ["region", "category"],
    "aggregations": [
      {"kind": "count", "field": "*"},
      {"kind": "sum", "field": "revenue"}
    ]
  }
}

三级分组 (Three-level grouping)

{
  "group": {
    "fields": ["region", "category", "status"],
    "aggregations": [{"kind": "count", "field": "*"}]
  }
}

返回结构示例

{
  "groups": [
    {
      "key": "North",
      "field": "region",
      "count": 100,
      "aggregations": {"count_*": 100, "sum_revenue": 50000},
      "children": [
        {
          "key": "Electronics",
          "field": "category",
          "count": 60,
          "aggregations": {"count_*": 60, "sum_revenue": 30000}
        },
        {
          "key": "Clothing",
          "field": "category",
          "count": 40,
          "aggregations": {"count_*": 40, "sum_revenue": 20000}
        }
      ]
    }
  ],
  "total": 100,
  "groupBy": {...}
}

数据叠加读取

支持通过 requestId 查询参数获取叠加后的数据视图。 Supports requestId query parameter for merged data view.

path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
includeChanges
boolean
includeRows
boolean
Request Body schema: application/json
required
object

过滤 Filters

嵌套过滤组合。 Nested filter groups.

Array of objects (Common.Sort)

排序 Sorts

排序条件集合。 Sort conditions.

object

分组与聚合 Group and aggregations

分组字段与聚合函数。 Group fields and aggregation functions.

page
integer <int32>

页码 Page number

页码（默认1）。 Page number (default 1).

pageSize
integer <int32>

每页数量 Page size

每页数量（默认20，最大200）。 Page size (default 20, max 200).

cursor
string

游标 Cursor

游标用于深分页。 Cursor for deep pagination.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "sorts": [
    ],
  • "group": {
    },
  • "page": 0,
  • "pageSize": 0,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取单行详情

返回单条数据行详情。

Return single row detail.

数据叠加读取

支持通过 requestId 查询参数获取叠加后的数据视图。 Supports requestId query parameter for merged data view.

path Parameters
docType
required
string
docId
required
string
rowId
required
string
query Parameters
requestId
string
includeChanges
boolean

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新数据行

更新数据行（进入变更请求）

Update data row (goes into change request)

更新的数据行会添加到指定的变更请求中，不会立即生效。 Updated row will be added to the specified change request, not applied immediately.

path Parameters
docType
required
string
docId
required
string
rowId
required
string
query Parameters
requestId
string
Request Body schema: application/json
required
id
required
string

行ID Row id

数据行唯一标识。 Unique identifier of the row.

required
Array of objects (Common.ValueEntry)

字段值集合 Field values

字段ID与值的集合。 Collection of field ids and values.

createdAt
string

创建时间 Created at

创建时间戳。 Created timestamp.

object

创建人 Created by

创建者。 Author.

updatedAt
string

更新时间 Updated at

更新时间戳。 Updated timestamp.

object

更新人 Updated by

更新者。 Updater.

version
integer <int64>

版本（并发控制） Version

版本号用于并发控制。 Version number for concurrency control.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "values": [
    ],
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string",
  • "updatedBy": {
    },
  • "version": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除数据行

删除数据行（进入变更请求）

Delete data row (goes into change request)

删除操作会添加到指定的变更请求中，不会立即生效。 Delete operation will be added to the specified change request, not applied immediately.

path Parameters
docType
required
string
docId
required
string
rowId
required
string
query Parameters
requestId
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Views

列出视图

返回指定文档的视图列表。

List all views of the document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

创建视图

创建新的视图定义。

Create a new view.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
id
required
string

视图唱一标识 Unique identifier of the view

name
required
string

视图显示名称 Display name of the view

type
string
Enum: "table" "gallery" "kanban" "calendar" "chart" "form" "map" "timeline"

视图类型（表格/相册/看板/文档） View type (grid/gallery/kanban/document)

displayFields
Array of strings

用于渲染的字段列表 Field list used for rendering

object

过滤条件组合 Filter conditions group

Array of objects (Common.Sort)

排序条件 Sort conditions

object

分组与聚合 Grouping and aggregations

object

列展示配置（宽度/顺序/固定/隐藏） Column display configuration (width/order/pinned/hidden)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "table",
  • "displayFields": [
    ],
  • "filters": {
    },
  • "sorts": [
    ],
  • "group": {
    },
  • "columnConfig": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取视图详情

获取视图配置与定义。

Get view definition and configuration.

path Parameters
docType
required
string
docId
required
string
viewId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新视图

更新视图定义与配置。

Update view definition and configuration.

path Parameters
docType
required
string
docId
required
string
viewId
required
string
Request Body schema: application/json
required
id
required
string

视图唱一标识 Unique identifier of the view

name
required
string

视图显示名称 Display name of the view

type
string
Enum: "table" "gallery" "kanban" "calendar" "chart" "form" "map" "timeline"

视图类型（表格/相册/看板/文档） View type (grid/gallery/kanban/document)

displayFields
Array of strings

用于渲染的字段列表 Field list used for rendering

object

过滤条件组合 Filter conditions group

Array of objects (Common.Sort)

排序条件 Sort conditions

object

分组与聚合 Grouping and aggregations

object

列展示配置（宽度/顺序/固定/隐藏） Column display configuration (width/order/pinned/hidden)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "table",
  • "displayFields": [
    ],
  • "filters": {
    },
  • "sorts": [
    ],
  • "group": {
    },
  • "columnConfig": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除视图

删除指定视图。

Delete specified view.

path Parameters
docType
required
string
docId
required
string
viewId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

设为默认视图

将指定视图设为默认视图。

Set specified view as default.

path Parameters
docType
required
string
docId
required
string
viewId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

Document - Properties

获取文档属性

获取文档属性

Get document properties

获取文档级别的所有元信息（订单时间、门店、金额等）。 Get all document-level metadata (order time, store, amount, etc).

数据叠加读取

支持通过 requestId 查询参数获取叠加后的属性视图。 Supports requestId query parameter for merged properties view.

path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
includeChanges
boolean

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建文档属性

创建或初始化文档属性

Create or initialize document properties

为新文档初始化属性。通常在文档创建时调用。 Initialize properties for new document. Typically called when document is created.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
id
required
string

属性ID Property id

唯一标识。 Unique identifier.

docId
required
string

文档ID Document id

关联的文档ID。 Associated document id.

docType
required
string

文档类型 Document type

文档类型（如 purchaseOrder、invoice、product）。 Document type (e.g. purchaseOrder, invoice, product).

organizationId
string

所属组织ID Organization ID

文档所属的组织（可选，用于多租户隔离）。 Organization that owns this document (optional, for multi-tenancy isolation).

workspaceId
string

所属工作区ID Workspace ID

文档所属的工作区（可选，为空表示组织级文档）。 Workspace that owns this document (optional, empty means organization-level document).

Array of objects (Common.ValueEntry)

属性值集合 Property values

使用类型化的值结构，与数据行的 cell 值设计一致。 Uses typed value structure, consistent with data row cell values.

每个属性都有字段ID和对应的类型化值。 Each property has a field ID and corresponding typed value.

示例:

[
  {"fieldId": "orderTime", "value": {"datetime": "2024-12-01T10:00:00Z"}},
  {"fieldId": "store", "value": {"text": "Beijing Branch"}},
  {"fieldId": "amount", "value": {"currency": 5000.00}},
  {"fieldId": "quantity", "value": {"number": 50}},
  {"fieldId": "coverImage", "value": {"attachment": [{"id": "att-123", "fileName": "cover.jpg", ...}]}}
]
version
integer <int64>

版本号 Version

用于并发控制。 For concurrency control.

createdAt
string

创建时间 Created at

创建时间戳。 Created timestamp.

updatedAt
string

更新时间 Updated at

更新时间戳。 Updated timestamp.

object

更新人 Updated by

最后更新的用户。 User who last updated.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "docId": "string",
  • "docType": "string",
  • "organizationId": "string",
  • "workspaceId": "string",
  • "properties": [
    ],
  • "version": 0,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "updatedBy": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

替换文档属性

完全替换文档属性（进入变更请求）

Replace document properties completely (goes into change request)

用新的属性集合完全替换现有属性。变更会添加到指定的变更请求中。 Replace existing properties with a new set. Changes will be added to the specified change request.

  • 如果指定 requestId，追加到该请求
  • 如果不指定，创建新的请求或追加到默认请求
  • 需要提供版本号以确保并发安全
  • 请求合并后才真正生效

示例（cURL）:

curl -X PUT 'https://open.nexusbook.app/api/v1/doc/purchaseOrder/order-123/properties?requestId=req-1' \\
  -H 'Authorization: Bearer TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "id": "prop-123",
    "docId": "order-123",
    "docType": "purchaseOrder",
    "version": 1,
    "properties": [
      {"fieldId": "orderTime", "value": {"datetime": "2024-12-01T10:00:00Z"}},
      {"fieldId": "store", "value": {"text": "Beijing Branch"}},
      {"fieldId": "amount", "value": {"currency": 5000.00}},
      {"fieldId": "quantity", "value": {"number": 50}}
    ]
  }'
path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
Request Body schema: application/json
required
id
required
string

属性ID Property id

唯一标识。 Unique identifier.

docId
required
string

文档ID Document id

关联的文档ID。 Associated document id.

docType
required
string

文档类型 Document type

文档类型（如 purchaseOrder、invoice、product）。 Document type (e.g. purchaseOrder, invoice, product).

organizationId
string

所属组织ID Organization ID

文档所属的组织（可选，用于多租户隔离）。 Organization that owns this document (optional, for multi-tenancy isolation).

workspaceId
string

所属工作区ID Workspace ID

文档所属的工作区（可选，为空表示组织级文档）。 Workspace that owns this document (optional, empty means organization-level document).

Array of objects (Common.ValueEntry)

属性值集合 Property values

使用类型化的值结构，与数据行的 cell 值设计一致。 Uses typed value structure, consistent with data row cell values.

每个属性都有字段ID和对应的类型化值。 Each property has a field ID and corresponding typed value.

示例:

[
  {"fieldId": "orderTime", "value": {"datetime": "2024-12-01T10:00:00Z"}},
  {"fieldId": "store", "value": {"text": "Beijing Branch"}},
  {"fieldId": "amount", "value": {"currency": 5000.00}},
  {"fieldId": "quantity", "value": {"number": 50}},
  {"fieldId": "coverImage", "value": {"attachment": [{"id": "att-123", "fileName": "cover.jpg", ...}]}}
]
version
integer <int64>

版本号 Version

用于并发控制。 For concurrency control.

createdAt
string

创建时间 Created at

创建时间戳。 Created timestamp.

updatedAt
string

更新时间 Updated at

更新时间戳。 Updated timestamp.

object

更新人 Updated by

最后更新的用户。 User who last updated.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "docId": "string",
  • "docType": "string",
  • "organizationId": "string",
  • "workspaceId": "string",
  • "properties": [
    ],
  • "version": 0,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "updatedBy": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

部分更新文档属性

部分更新文档属性（进入变更请求）

Partially update document properties (goes into change request)

仅更新指定的属性字段，保留其他字段。变更会添加到指定的变更请求中。 Update only specified property fields, preserve others. Changes will be added to the specified change request.

简化提交方式：

  • 只需指定字段ID和原始值
  • 服务端根据 metadata 自动解析值类型
  • 无需客户端了解字段类型细节

Simplified submission:

  • Only specify field id and raw value
  • Server auto-parses value type based on metadata
  • No need for client to know field type details

查询参数:

  • requestId - 指定要追加到的请求ID（可选）
  • merge=true - 合并模式（默认）：新值与现有值合并
  • merge=false - 覆盖模式：新值覆盖现有值
  • version - 当前版本号（用于并发检查）

Query parameters:

  • requestId - Specify which request to append to (optional)
  • merge=true - Merge mode (default): merge new values with existing
  • merge=false - Overwrite mode: new values override existing
  • version - Current version number (for concurrency check)

示例（cURL）- 仅更新订单金额和数量：

curl -X PATCH 'https://open.nexusbook.app/api/v1/doc/purchaseOrder/order-123/properties?requestId=req-1&merge=true&version=1' \\
  -H 'Authorization: Bearer TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "updates": [
      {"fieldId": "amount", "value": 6000.00},
      {"fieldId": "quantity", "value": 60}
    ]
  }'

服务端处理逻辑：

  1. 根据 docId 获取 metadata
  2. 对每个 fieldId，查找字段定义获取类型
  3. 将原始值转换为类型化值
  4. 验证值的有效性
  5. 添加到指定的 Request

Server processing:

  1. Get metadata by docId
  2. For each fieldId, lookup field definition to get type
  3. Convert raw value to typed value
  4. Validate value
  5. Add to specified Request
path Parameters
docType
required
string
docId
required
string
query Parameters
requestId
string
merge
boolean
version
integer <int64>
Request Body schema: application/json
required
Array of objects

要更新的属性值数组（简化格式） Property values to update (simplified format)

直接提供 fieldId 和原始值，服务端根据 metadata 自动解析类型。 Provide fieldId and raw value directly, server auto-parses type based on metadata.

note
string

更新说明 Update note

Responses

Request samples

Content type
application/json
{
  • "updates": [
    ],
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除文档属性

删除文档属性

Delete document properties

删除文档的所有属性数据。此操作无法撤销，请谨慎。 Delete all property data of the document. This action cannot be undone, use with caution.

path Parameters
docType
required
string
docId
required
string
query Parameters
version
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

查看属性历史

获取属性的修订历史

Get properties revision history

查看属性的所有历史变更记录。 View all historical changes of properties.

path Parameters
docType
required
string
docId
required
string
query Parameters
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Relations

列出关联关系

列出所有关联关系

List all relations

查询文档的所有关联关系，支持过滤。 Query all relations of the document, supports filtering.

path Parameters
docType
required
string
docId
required
string
query Parameters
fieldId
string
targetDocType
string
targetDocId
string
includeDetails
boolean
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建关联

创建关联关系

Create relation

在两个文档行之间创建关联。如果配置为双向关联，会自动在目标端创建反向关联。 Create relation between two document rows. If bidirectional, automatically creates reverse relation.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/doc/order/123/relations' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{
    "sourceRowId": "row-1",
    "fieldId": "products",
    "targetDocType": "product",
    "targetDocId": "456",
    "targetRowId": "row-2",
    "metadata": {"quantity": 10}
  }'
path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
sourceRowId
required
string

源行ID Source row id

fieldId
required
string

源字段ID Source field id

targetDocType
required
string

目标文档类型 Target document type

targetDocId
required
string

目标文档ID Target document id

targetRowId
required
string

目标行ID Target row id

metadata
any

关联元数据 Relation metadata

Responses

Request samples

Content type
application/json
{
  • "sourceRowId": "string",
  • "fieldId": "string",
  • "targetDocType": "string",
  • "targetDocId": "string",
  • "targetRowId": "string",
  • "metadata": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

批量创建关联

批量创建关联

Batch create relations

一次性创建多个关联关系。 Create multiple relations at once.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
Array
sourceRowId
required
string
fieldId
required
string
targetDocType
required
string
targetDocId
required
string
targetRowId
required
string
metadata
any

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

批量删除关联

批量删除关联

Batch delete relations

根据条件批量删除关联关系。 Delete relations in batch by conditions.

path Parameters
docType
required
string
docId
required
string
query Parameters
sourceRowId
string
fieldId
string
targetDocType
string
targetRowId
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

检查循环引用

检查循环引用

Check circular reference

检查创建关联是否会导致循环引用。 Check if creating relation would cause circular reference.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
sourceRowId
required
string
fieldId
required
string
targetDocType
required
string
targetDocId
required
string
targetRowId
required
string

Responses

Request samples

Content type
application/json
{
  • "sourceRowId": "string",
  • "fieldId": "string",
  • "targetDocType": "string",
  • "targetDocId": "string",
  • "targetRowId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取关联配置

获取文档的关联配置

Get document relation configurations

返回该文档所有字段的关联配置。 Return all field relation configurations of the document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

配置关联关系

创建或更新关联配置

Create or update relation configuration

配置字段的关联规则，包括双向关联、级联策略等。 Configure field relation rules, including bidirectional, cascade strategy, etc.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
id
required
string

配置ID Config id

sourceDocType
required
string

源文档类型 Source document type

sourceDocId
required
string

源文档ID Source document id

fieldId
required
string

源字段ID Source field id

targetDocType
required
string

目标文档类型 Target document type

targetDocId
required
string

目标文档ID Target document id

bidirectional
boolean

是否双向关联 Bidirectional linking

reverseFieldId
string

反向字段ID（双向关联时使用） Reverse field id (for bidirectional)

cascadeDelete
string
Enum: "none" "unlink" "soft" "hard" "prevent"

级联删除策略 Cascade delete strategy

object

关联验证规则 Link validation rules

createdAt
string

创建时间 Created at

updatedAt
string

更新时间 Updated at

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "sourceDocType": "string",
  • "sourceDocId": "string",
  • "fieldId": "string",
  • "targetDocType": "string",
  • "targetDocId": "string",
  • "bidirectional": true,
  • "reverseFieldId": "string",
  • "cascadeDelete": "none",
  • "validation": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除关联

删除关联关系

Delete relation

删除指定的关联关系。如果是双向关联，会同时删除反向关联。 Delete specified relation. If bidirectional, also deletes reverse relation.

path Parameters
docType
required
string
docId
required
string
relationId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

Document - Attachments

附件管理

列出附件

列出附件

List attachments

查询附件列表，支持过滤和分页。 Query attachments with filtering and pagination.

query Parameters
organizationId
string
workspaceId
string
relatedDocType
string
relatedDocId
string
relatedRowId
string
mimeType
string
tags
string
createdBy
string
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

清理过期附件

清理过期附件

Clean expired attachments

清理已过期的临时附件。 Clean up expired temporary attachments.

query Parameters
organizationId
string
dryRun
boolean

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取存储配额

获取存储配额

Get storage quota

查询组织的存储配额使用情况。 Query organization storage quota usage.

path Parameters
organizationId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

上传附件

上传附件

Upload attachment

上传文件并返回附件信息。支持自动扫描和缩略图生成。 Upload file and return attachment info. Supports automatic scanning and thumbnail generation.

支持的参数:

  • file - 文件（必需）
  • scanForVirus - 是否扫描病毒
  • generateThumbnail - 是否生成缩略图
  • generatePreview - 是否生成预览
  • tags - 标签（逗号分隔）
  • isPublic - 是否公开访问
  • expiresIn - 过期时间（秒）
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

批量上传附件

批量上传附件

Batch upload attachments

一次性上传多个文件。 Upload multiple files at once.

Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取附件详情

获取附件详情

Get attachment details

返回附件的完整信息。 Return complete attachment information.

path Parameters
attachmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新附件元数据

更新附件元数据

Update attachment metadata

更新附件的标签、名称等元数据。 Update attachment tags, name and other metadata.

path Parameters
attachmentId
required
string
Request Body schema: application/json
required
fileName
string
tags
Array of strings
metadata
any
isPublic
boolean

Responses

Request samples

Content type
application/json
{
  • "fileName": "string",
  • "tags": [
    ],
  • "metadata": null,
  • "isPublic": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除附件

删除附件

Delete attachment

删除附件及其所有版本。此操作不可恢复。 Delete attachment and all its versions. This action is irreversible.

path Parameters
attachmentId
required
string
query Parameters
permanent
boolean

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取下载链接

获取下载URL

Get download URL

生成附件的临时下载URL。 Generate temporary download URL for attachment.

path Parameters
attachmentId
required
string
query Parameters
expiresIn
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取预览

获取预览URL

Get preview URL

生成附件的预览URL（支持图片、PDF等）。 Generate preview URL for attachment (supports images, PDF, etc).

path Parameters
attachmentId
required
string
query Parameters
size
string (Document.PreviewSize)
Enum: "small" "medium" "large" "original"

预览尺寸 Preview size

page
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取附件版本

获取附件版本列表

Get attachment versions

返回附件的所有历史版本。 Return all historical versions of the attachment.

path Parameters
attachmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

创建新版本

创建附件新版本

Create attachment version

为现有附件上传新版本。 Upload new version for existing attachment.

path Parameters
attachmentId
required
string
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Sync

列出同步配置

列出同步配置

List sync configurations

返回文档的所有同步配置。 Return all sync configurations of the document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

创建同步配置

创建同步配置

Create sync configuration

创建新的数据同步配置。 Create new data sync configuration.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
id
required
string

配置ID Config id

name
required
string

名称 Name

description
string

描述 Description

docType
required
string

文档类型 Document type

docId
required
string

文档ID Document id

sourceType
required
string
Enum: "google_sheets" "excel_online" "csv" "json_api" "rest_api" "graphql_api" "database" "webhook" "airtable" "notion"

数据源类型 Source type

sourceConfig
required
any

数据源配置 Source configuration

根据 sourceType 不同，配置内容不同。 Configuration varies by sourceType.

syncMode
required
string
Enum: "one_way_import" "one_way_export" "two_way"

同步模式 Sync mode

Array of objects

字段映射 Field mapping

本地字段 -> 远程字段的映射。 Local field -> Remote field mapping.

object

同步过滤器 Sync filters

仅同步符合条件的数据。 Only sync data matching conditions.

conflictResolution
string
Enum: "keep_local" "keep_remote" "ask_user" "latest_wins" "merge"

冲突解决策略 Conflict resolution

schedule
string

定时任务（Cron 表达式） Schedule (Cron expression)

示例：

  • "0 * /6 * * *" - 每 6 小时一次
  • "0 0 * * *" - 每天午夜
  • "0 9 * * 1-5" - 工作日早上 9 点
enabled
boolean

是否启用 Enabled

incremental
boolean

增量同步（仅同步变更） Incremental sync

lastSyncedAt
string

最后同步时间 Last synced at

nextSyncAt
string

下次同步时间 Next sync at

createdAt
string

创建时间 Created at

object

创建人 Created by

updatedAt
string

更新时间 Updated at

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "docType": "string",
  • "docId": "string",
  • "sourceType": "google_sheets",
  • "sourceConfig": null,
  • "syncMode": "one_way_import",
  • "fieldMapping": [
    ],
  • "filters": {
    },
  • "conflictResolution": "keep_local",
  • "schedule": "string",
  • "enabled": true,
  • "incremental": true,
  • "lastSyncedAt": "string",
  • "nextSyncAt": "string",
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

测试连接

测试同步连接

Test sync connection

测试与数据源的连接是否正常。 Test if connection to data source is working.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
sourceType
required
string (Document.SyncSourceType)
Enum: "google_sheets" "excel_online" "csv" "json_api" "rest_api" "graphql_api" "database" "webhook" "airtable" "notion"

同步源类型 Sync source type

sourceConfig
required
any

Responses

Request samples

Content type
application/json
{
  • "sourceType": "google_sheets",
  • "sourceConfig": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取同步配置

获取同步配置详情

Get sync configuration

返回指定同步配置的详细信息。 Return detailed information of specified sync configuration.

path Parameters
docType
required
string
docId
required
string
configId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新同步配置

更新同步配置

Update sync configuration

更新同步配置的参数。 Update sync configuration parameters.

path Parameters
docType
required
string
docId
required
string
configId
required
string
Request Body schema: application/json
required
id
required
string

配置ID Config id

name
required
string

名称 Name

description
string

描述 Description

docType
required
string

文档类型 Document type

docId
required
string

文档ID Document id

sourceType
required
string
Enum: "google_sheets" "excel_online" "csv" "json_api" "rest_api" "graphql_api" "database" "webhook" "airtable" "notion"

数据源类型 Source type

sourceConfig
required
any

数据源配置 Source configuration

根据 sourceType 不同，配置内容不同。 Configuration varies by sourceType.

syncMode
required
string
Enum: "one_way_import" "one_way_export" "two_way"

同步模式 Sync mode

Array of objects

字段映射 Field mapping

本地字段 -> 远程字段的映射。 Local field -> Remote field mapping.

object

同步过滤器 Sync filters

仅同步符合条件的数据。 Only sync data matching conditions.

conflictResolution
string
Enum: "keep_local" "keep_remote" "ask_user" "latest_wins" "merge"

冲突解决策略 Conflict resolution

schedule
string

定时任务（Cron 表达式） Schedule (Cron expression)

示例：

  • "0 * /6 * * *" - 每 6 小时一次
  • "0 0 * * *" - 每天午夜
  • "0 9 * * 1-5" - 工作日早上 9 点
enabled
boolean

是否启用 Enabled

incremental
boolean

增量同步（仅同步变更） Incremental sync

lastSyncedAt
string

最后同步时间 Last synced at

nextSyncAt
string

下次同步时间 Next sync at

createdAt
string

创建时间 Created at

object

创建人 Created by

updatedAt
string

更新时间 Updated at

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "docType": "string",
  • "docId": "string",
  • "sourceType": "google_sheets",
  • "sourceConfig": null,
  • "syncMode": "one_way_import",
  • "fieldMapping": [
    ],
  • "filters": {
    },
  • "conflictResolution": "keep_local",
  • "schedule": "string",
  • "enabled": true,
  • "incremental": true,
  • "lastSyncedAt": "string",
  • "nextSyncAt": "string",
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除同步配置

删除同步配置

Delete sync configuration

删除同步配置及其相关任务历史。 Delete sync configuration and its task history.

path Parameters
docType
required
string
docId
required
string
configId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取同步冲突

获取同步冲突

Get sync conflicts

返回需要手动解决的同步冲突。 Return sync conflicts that need manual resolution.

path Parameters
docType
required
string
docId
required
string
configId
required
string
query Parameters
resolved
boolean
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

解决冲突

解决同步冲突

Resolve sync conflict

手动解决同步冲突。 Manually resolve sync conflict.

path Parameters
docType
required
string
docId
required
string
configId
required
string
conflictId
required
string
Request Body schema: application/json
required
resolution
required
string
Enum: "keep_local" "keep_remote" "ask_user" "latest_wins" "merge"

解决策略 Resolution strategy

customValue
any

自定义值（当选择合并时） Custom value (when merge is selected)

Responses

Request samples

Content type
application/json
{
  • "resolution": "keep_local",
  • "customValue": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取同步历史

获取同步任务历史

Get sync task history

返回同步配置的执行历史。 Return execution history of sync configuration.

path Parameters
docType
required
string
docId
required
string
configId
required
string
query Parameters
status
string (Document.SyncTaskStatus)
Enum: "pending" "running" "completed" "failed" "cancelled" "partial"

同步状态 Sync status

page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取任务详情

获取任务详情

Get task details

返回同步任务的详细信息和日志。 Return detailed information and logs of sync task.

path Parameters
docType
required
string
docId
required
string
configId
required
string
taskId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

取消同步任务

取消同步任务

Cancel sync task

取消正在执行的同步任务。 Cancel running sync task.

path Parameters
docType
required
string
docId
required
string
configId
required
string
taskId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

手动触发同步

手动触发同步

Trigger sync manually

立即执行一次同步任务。 Execute sync task immediately.

path Parameters
docType
required
string
docId
required
string
configId
required
string
Request Body schema: application/json
optional
fullSync
boolean

是否完全同步（忽略增量设置） Full sync (ignore incremental setting)

dryRun
boolean

是否空运行（仅检查，不实际同步） Dry run (check only, don't actually sync)

Responses

Request samples

Content type
application/json
{
  • "fullSync": true,
  • "dryRun": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Collaboration

列出评论

列出指定位置的评论

List comments at specified location

支持按位置（文档/字段/行/单元格）过滤评论。 Supports filtering by location (document/field/row/cell).

查询参数示例:

  • scope=document - 文档级评论
  • scope=field&fieldId=field-123 - 指定字段的评论
  • scope=row&rowId=row-456 - 指定行的评论
  • scope=cell&rowId=row-456&fieldId=field-123 - 指定单元格的评论
  • parentId=comment-789 - 指定评论的回复

Query examples:

  • scope=document - Document-level comments
  • scope=field&fieldId=field-123 - Comments on specific field
  • scope=row&rowId=row-456 - Comments on specific row
  • scope=cell&rowId=row-456&fieldId=field-123 - Comments on specific cell
  • parentId=comment-789 - Replies to specific comment
path Parameters
docType
required
string
docId
required
string
query Parameters
scope
string
fieldId
string
rowId
string
parentId
string
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建评论

创建新评论

Create new comment

在指定位置创建评论。如果是回复，需指定 parentId。 Create a comment at specified location. Specify parentId if it's a reply.

示例 - 创建文档级评论 (Document-level comment):

{
  "target": { "scope": "document" },
  "content": "这是一条文档级评论"
}

示例 - 创建单元格评论 (Cell comment):

{
  "target": { "scope": "cell", "rowId": "row-1", "fieldId": "name" },
  "content": "这个单元格的数据看起来不对"
}

示例 - 创建回复 (Reply to comment):

{
  "target": { "scope": "cell", "rowId": "row-1", "fieldId": "name" },
  "parentId": "comment-original-1",
  "content": "我同意，需要修正这个数据"
}
path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
id
required
string

评论唯一标识 Unique identifier of the comment

required
object

评论位置定位 Comment target location

指定评论在文档中的确切位置。 Specifies the exact location of the comment in the document.

parentId
string

父评论ID（如果是回复） Parent comment id (if this is a reply)

如果此评论是对另一条评论的回复，记录父评论ID。 If this comment is a reply to another, record the parent comment id.

content
required
string

评论内容（支持富文本） Comment content (rich text supported)

支持 Markdown 格式和 HTML 标签。 Supports Markdown format and HTML tags.

Array of objects (Common.UserRef)
Array of objects (Common.Attachment)

附件集合 Attachments

评论中附加的文件。 Files attached to the comment.

Array of objects (Document.Reaction)

表情反应集合 Emoji reactions

其他用户对此评论的表情反应。 Emoji reactions from other users to this comment.

resolved
boolean

是否已解决 Resolved flag

标记此评论（及其讨论线程）是否已解决。 Mark if this comment (and its thread) is resolved.

resolvedAt
string

解决时间 Resolved at

评论解决的时间戳。 Timestamp when comment was resolved.

object

解决人 Resolved by

解决此评论的人。 Who resolved this comment.

pinned
boolean

是否置顶 Pinned flag

重要评论可以置顶展示。 Important comments can be pinned.

createdAt
string

创建时间 Created at

object

创建人 Created by

updatedAt
string

更新时间 Updated at

object

更新人 Updated by

replyCount
integer <int32>

回复数量 Reply count

此评论下的直接回复数（不包括递归回复）。 Direct reply count to this comment (not recursive).

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "target": {
    },
  • "parentId": "string",
  • "content": "string",
  • "mentions": [
    ],
  • "attachments": [
    ],
  • "reactions": [
    ],
  • "resolved": true,
  • "resolvedAt": "string",
  • "resolvedBy": {
    },
  • "pinned": true,
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string",
  • "updatedBy": {
    },
  • "replyCount": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取评论详情

获取评论详情

Get comment detail

包括所有回复和反应信息。 Includes all replies and reactions.

path Parameters
docType
required
string
docId
required
string
commentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新评论

更新评论

Update comment

只有创建者或管理员可以编辑评论。 Only creator or admin can edit comment.

path Parameters
docType
required
string
docId
required
string
commentId
required
string
Request Body schema: application/json
required
id
required
string

评论唯一标识 Unique identifier of the comment

required
object

评论位置定位 Comment target location

指定评论在文档中的确切位置。 Specifies the exact location of the comment in the document.

parentId
string

父评论ID（如果是回复） Parent comment id (if this is a reply)

如果此评论是对另一条评论的回复，记录父评论ID。 If this comment is a reply to another, record the parent comment id.

content
required
string

评论内容（支持富文本） Comment content (rich text supported)

支持 Markdown 格式和 HTML 标签。 Supports Markdown format and HTML tags.

Array of objects (Common.UserRef)
Array of objects (Common.Attachment)

附件集合 Attachments

评论中附加的文件。 Files attached to the comment.

Array of objects (Document.Reaction)

表情反应集合 Emoji reactions

其他用户对此评论的表情反应。 Emoji reactions from other users to this comment.

resolved
boolean

是否已解决 Resolved flag

标记此评论（及其讨论线程）是否已解决。 Mark if this comment (and its thread) is resolved.

resolvedAt
string

解决时间 Resolved at

评论解决的时间戳。 Timestamp when comment was resolved.

object

解决人 Resolved by

解决此评论的人。 Who resolved this comment.

pinned
boolean

是否置顶 Pinned flag

重要评论可以置顶展示。 Important comments can be pinned.

createdAt
string

创建时间 Created at

object

创建人 Created by

updatedAt
string

更新时间 Updated at

object

更新人 Updated by

replyCount
integer <int32>

回复数量 Reply count

此评论下的直接回复数（不包括递归回复）。 Direct reply count to this comment (not recursive).

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "target": {
    },
  • "parentId": "string",
  • "content": "string",
  • "mentions": [
    ],
  • "attachments": [
    ],
  • "reactions": [
    ],
  • "resolved": true,
  • "resolvedAt": "string",
  • "resolvedBy": {
    },
  • "pinned": true,
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string",
  • "updatedBy": {
    },
  • "replyCount": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除评论

删除评论

Delete comment

删除评论会同时删除其所有回复。 Deleting comment also deletes all its replies.

path Parameters
docType
required
string
docId
required
string
commentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

置顶评论

置顶评论

Pin comment

将评论置顶，重要评论可以固定在顶部。 Pin important comments to the top.

path Parameters
docType
required
string
docId
required
string
commentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

添加表情反应

添加表情反应

Add emoji reaction

在评论上添加表情反应（如 👍、❤️ 等）。 Add emoji reaction to comment (e.g. 👍, ❤️).

path Parameters
docType
required
string
docId
required
string
commentId
required
string
query Parameters
emoji
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

移除表情反应

移除表情反应

Remove emoji reaction

path Parameters
docType
required
string
docId
required
string
commentId
required
string
emoji
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

标记已解决

标记为已解决

Mark comment as resolved

标记评论及其讨论线程为已解决。 Mark comment and its discussion thread as resolved.

path Parameters
docType
required
string
docId
required
string
commentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

取消置顶

取消置顶

Unpin comment

path Parameters
docType
required
string
docId
required
string
commentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

取消已解决标记

取消解决标记

Unresolved comment

path Parameters
docType
required
string
docId
required
string
commentId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

应用 Yjs 更新

应用 Yjs 更新

Apply Yjs update

应用客户端的 Yjs 更新到服务器。 Apply client Yjs update to server.

注意：通常应该通过 WebSocket 发送更新，此 HTTP 接口用于备用场景。 Note: Updates should normally be sent via WebSocket. This HTTP endpoint is for fallback scenarios.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
update
required
string

Yjs 更新数据（Base64） Yjs update data (Base64)

clientVersion
integer <int64>

客户端版本 Client version

Responses

Request samples

Content type
application/json
{
  • "update": "string",
  • "clientVersion": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Awareness

更新 Awareness 状态

Update awareness state

更新用户的 awareness 状态（光标、选择等）。 Update user awareness state (cursor, selection, etc).

注意：通常应该通过 WebSocket 发送，此接口用于备用场景。 Note: Should normally be sent via WebSocket. This endpoint is for fallback scenarios.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
awareness
required
any

Awareness 状态 Awareness state

Responses

Request samples

Content type
application/json
{
  • "awareness": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取连接信息

获取 WebSocket 连接信息

Get WebSocket connection info

返回 WebSocket 连接 URL 和认证令牌。 Return WebSocket connection URL and auth token.

客户端使用流程：

  1. 调用此 API 获取连接信息
  2. 使用返回的 wsUrl 和 token 建立 WebSocket 连接
  3. 发送认证消息
  4. 开始接收和发送实时事件
path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

断开所有会话

断开所有会话

Disconnect all sessions

强制断开文档的所有实时协作会话。 Force disconnect all realtime collaboration sessions of the document.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
optional
reason
string

断开原因 Reason

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取事件历史

获取实时事件历史

Get realtime event history

返回文档的实时协作事件历史。 Return realtime collaboration event history of the document.

path Parameters
docType
required
string
docId
required
string
query Parameters
eventType
string (Document.RealtimeEventType)
Enum: "yjs_update" "awareness_update" "user_joined" "user_left" "cell_locked" "cell_unlocked" "cursor_moved" "selection_changed" "comment_added" "data_changed"

实时事件类型 Realtime event type

userId
string
startTime
string
endTime
string
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

SSE 事件流

事件流（SSE） Server-Sent Events stream

Content-Type: text/event-stream 用于只读的实时事件推送（替代 WebSocket 的只读场景）。

path Parameters
docType
required
string
docId
required
string
query Parameters
since
string
types
string

Responses

锁定单元格

锁定单元格

Lock cell

请求锁定单元格以进行编辑。 Request cell lock for editing.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
rowId
required
string

行ID Row id

fieldId
required
string

字段ID Field id

duration
integer <int32>

锁定时长（秒） Lock duration in seconds

autoRenew
boolean

是否自动续期 Auto renew

Responses

Request samples

Content type
application/json
{
  • "rowId": "string",
  • "fieldId": "string",
  • "duration": 0,
  • "autoRenew": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取锁定列表

获取当前锁定

Get current locks

返回文档的所有活跃锁定。 Return all active locks of the document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

获取 Yjs 快照

获取 Yjs 文档快照

Get Yjs document snapshot

返回最新的 Yjs 文档快照，用于初始化客户端。 Return latest Yjs document snapshot for client initialization.

path Parameters
docType
required
string
docId
required
string
query Parameters
version
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

保存 Yjs 快照

保存 Yjs 文档快照

Save Yjs document snapshot

保存当前 Yjs 文档状态。通常由服务器定期调用。 Save current Yjs document state. Usually called periodically by server.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
stateVector
required
string

Yjs 状态向量（Base64） Yjs state vector (Base64)

docUpdate
required
string

Yjs 文档更新（Base64） Yjs document update (Base64)

Responses

Request samples

Content type
application/json
{
  • "stateVector": "string",
  • "docUpdate": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取快照历史

获取快照历史

Get snapshot history

返回文档的 Yjs 快照历史。 Return Yjs snapshot history of the document.

path Parameters
docType
required
string
docId
required
string
query Parameters
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

解锁单元格

解锁单元格

Unlock cell

释放单元格锁定。 Release cell lock.

path Parameters
docType
required
string
docId
required
string
lockId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取在线用户

获取在线用户列表

Get online users

返回当前文档的所有在线用户。 Return all online users of current document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

获取 WebSocket 消息格式

获取 WebSocket 消息格式 Get WebSocket message schema

返回客户端与服务端的消息帧模型以及可用的消息类型枚举。 Return client/server message frames and available message kinds.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Workflow

获取审批

获取审批流程定义或实例概述。

Get approval flow definition or instance overview.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

发起审批

在文档上发起审批流程。

Start approval flow on the document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

审批详情

获取审批实例详情。

Get approval instance detail.

path Parameters
docType
required
string
docId
required
string
instanceId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

审批决策

对审批实例进行通过或拒绝的决策。

Decide approval (approve or reject).

path Parameters
docType
required
string
docId
required
string
instanceId
required
string
query Parameters
result
required
string (Common.ApprovalDecision)
Enum: "approve" "reject" "request_changes"

审批决议 Approval decision

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出合并请求

列出文档的未生效变更请求。

List uncommitted merge requests of the document.

path Parameters
docType
required
string
docId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

创建合并请求

创建新的合并请求以提交未生效变更。

Create a new merge request for uncommitted changes.

path Parameters
docType
required
string
docId
required
string
Request Body schema: application/json
required
id
required
string

请求ID Request id

合并请求的唯一标识。 Unique identifier of the merge request.

title
string

标题 Title

合并请求标题。 Title of the merge request.

description
string

描述 Description

合并请求描述。 Description of the merge request.

status
required
string
Enum: "open" "merged" "closed"

状态 Status

当前状态：open/merged/closed。 Current status: open/merged/closed.

object

作者 Author

创建者。 Author.

Array of objects (Common.UserRef)

评审人 Reviewers

评审人列表。 List of reviewers.

Array of objects (Common.UserRef)

贡献者 Contributors

对该请求添加或修改变更的所有用户。 All users who added or modified changes in this request.

Array of objects (Document.Change)

变更集 Changes

包含待合并的变更。支持数据行、属性、视图等多种类型的变更。 Contains changes to be merged. Supports data rows, properties, views, and other types.

generatedRevisionId
string

生成的修订ID Generated revision id

当请求合并后，系统生成的修订ID。 Revision id generated when the request is merged.

createdAt
string

创建时间 Created at

创建时间戳。 Created timestamp.

updatedAt
string

更新时间 Updated at

更新时间戳。 Updated timestamp.

mergedAt
string

合并时间 Merged at

请求被合并的时间戳。 Timestamp when the request was merged.

object

合并者 Merged by

执行合并操作的用户。 User who performed the merge.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "status": "open",
  • "author": {
    },
  • "reviewers": [
    ],
  • "contributors": [
    ],
  • "changes": [
    ],
  • "generatedRevisionId": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "mergedAt": "string",
  • "mergedBy": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取合并请求详情

获取合并请求的详细信息。

Get merge request detail.

path Parameters
docType
required
string
docId
required
string
reqId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

关闭请求

关闭指定合并请求。

Close specified merge request.

path Parameters
docType
required
string
docId
required
string
reqId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

检查冲突

检查合并请求与当前文档的冲突。

Check conflicts between merge request and current document.

path Parameters
docType
required
string
docId
required
string
reqId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

合并请求

将合并请求的变更应用到文档并生成修订。

Apply merge request changes to the document and generate revision.

当请求被合并时：

  1. 系统冻结该请求中的所有变更
  2. 应用变更到文档
  3. 创建新的修订记录整个变更历史
  4. 记录所有贡献者（对请求做过修改的人）
  5. 返回生成的修订ID

When request is merged:

  1. System freezes all changes in the request
  2. Apply changes to document
  3. Create new revision recording the entire change history
  4. Record all contributors (users who modified the request)
  5. Return generated revision id

请求体支持以下选项:

  • squash - 是否合并为单一变更（true/false）
  • message - 合并消息
  • deleteBranch - 合并后是否删除关联分支

Request body supports:

  • squash - Whether to squash into single change
  • message - Merge message
  • deleteBranch - Delete associated branch after merge

响应包含:

  • revisionId - 生成的修订ID
  • version - 修订版本号
  • changesApplied - 应用的变更数量
  • contributors - 所有贡献者列表

Response includes:

  • revisionId - Generated revision id
  • version - Revision version number
  • changesApplied - Number of applied changes
  • contributors - List of all contributors
path Parameters
docType
required
string
docId
required
string
reqId
required
string
Request Body schema: application/json
optional
message
string

合并消息 Merge message

squash
boolean

是否合并为单一变更 Squash into single change

deleteBranch
boolean

合并后是否删除关联分支 Delete branch after merge

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "squash": true,
  • "deleteBranch": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

重新打开请求

重新打开已关闭的合并请求。

Reopen closed merge request.

path Parameters
docType
required
string
docId
required
string
reqId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

列出修订历史

列出文档的修订历史

List document revisions

按时间逆序返回修订列表，支持分页。 Returns revisions in reverse chronological order, supports pagination.

查询参数:

  • page - 页码（默认1）
  • pageSize - 每页数量（默认20）
  • contributor - 按贡献者过滤
  • search - 按标题或描述搜索

Query parameters:

  • page - Page number (default 1)
  • pageSize - Items per page (default 20)
  • contributor - Filter by contributor
  • search - Search by title or description
path Parameters
docType
required
string
docId
required
string
query Parameters
page
integer <int32>
pageSize
integer <int32>
contributor
string
search
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

查询变更历史

查询特定目标的变更历史

Query change history for specific target

查看某个特定对象（行/字段）在所有修订中的变更历史。 View change history of a specific object (row/field) across all revisions.

示例 - 查询某行的变更历史:

curl 'https://open.nexusbook.app/api/v1/doc/product/123/revisions/history?targetKind=row&rowId=row-1' \\
  -H 'Authorization: Bearer TOKEN'
path Parameters
docType
required
string
docId
required
string
query Parameters
targetKind
required
string
rowId
string
fieldId
string
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取修订详情

获取指定修订的完整详情

Get revision detail

返回修订的完整信息，包含所有操作和统计数据。 Returns complete revision information including all operations and statistics.

path Parameters
docType
required
string
docId
required
string
revId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

对比修订差异

比较两个修订之间的差异

Compare revisions

返回两个修订之间的所有差异，支持按目标类型过滤。 Returns all differences between two revisions, supports filtering by target type.

示例（cURL）:

# 比较 rev-2 与 rev-1（base）的差异
curl 'https://open.nexusbook.app/api/v1/doc/product/123/revisions/rev-2/diff?base=rev-1' \\
  -H 'Authorization: Bearer TOKEN'
path Parameters
docType
required
string
docId
required
string
revId
required
string
query Parameters
base
string
targetKind
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

导出修订

导出修订数据

Export revision

导出修订的完整数据为 JSON、CSV 等格式。 Export revision data in JSON, CSV, or other formats.

path Parameters
docType
required
string
docId
required
string
revId
required
string
query Parameters
format
string

Responses

查看修订操作列表

查看修订的变更操作列表

List operations in revision

分页返回修订中的所有变更操作，支持按操作类型过滤。 Returns all change operations in the revision, supports filtering by operation type.

path Parameters
docType
required
string
docId
required
string
revId
required
string
query Parameters
type
string
targetKind
string
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取源请求

获取修订的源请求

Get source request of revision

获取生成此修订的原始合并请求。 Get the original merge request that generated this revision.

path Parameters
docType
required
string
docId
required
string
revId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

回滚到指定修订

回滚到指定修订

Revert to revision

将文档回滚到指定修订的状态，创建一个新的修订记录此操作。 Revert document to specified revision state, creates a new revision recording this action.

注意：回滚操作本身会生成新的修订（类型为 "revert"）。 Note: The revert action itself generates a new revision (type "revert").

path Parameters
docType
required
string
docId
required
string
revId
required
string
Request Body schema: application/json
optional
reason
string

回滚原因 Revert reason

selectiveTypes
Array of strings

选择性回滚 Selective revert

只回滚特定类型的变更（如只回滚行的变更，保留字段变更）。 Only revert specific types of changes (e.g., only row changes, keep field changes).

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "selectiveTypes": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Document - Tenancy

多租户（组织/工作区级文档）

获取组织文档聚合数据

获取组织级文档聚合数据 Get organization document aggregate

一次性获取组织级文档的多种数据。需要是组织成员。 Get multiple types of data for organization-level document in one request. Requires organization membership.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/doc/policy/doc-456?include=metadata,views,data' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

docType
required
string

文档类型 Document type

docId
required
string

文档ID Document ID

query Parameters
include
string

包含的数据部分（逗号分隔） Included data parts (comma-separated)

可选值: properties, metadata, views, data, comments, revisions, settings Options: properties, metadata, views, data, comments, revisions, settings

viewId
string

视图ID View ID

page
integer <int32>

页码 Page number

pageSize
integer <int32>

每页数量 Page size

commentsLimit
integer <int32>

评论数量限制 Comments limit

revisionsLimit
integer <int32>

修订数量限制 Revisions limit

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出组织文档

列出组织文档 List organization documents

获取组织下的所有文档列表。需要是组织成员。 Get the list of all documents under the organization. Requires organization membership.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/documents?docType=policy&page=1&pageSize=20' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
docType
string

文档类型过滤 Filter by document type

search
string

搜索关键词 Search keyword

createdBy
string

创建者过滤 Filter by creator

sort
string
Default: "updatedAt"

排序字段 Sort field

direction
string (Common.Direction)
Enum: "asc" "desc"

排序方向 Sort direction

page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取工作区文档聚合数据

获取工作区级文档聚合数据 Get workspace document aggregate

一次性获取工作区级文档的多种数据。需要是工作区成员。 Get multiple types of data for workspace-level document in one request. Requires workspace membership.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/doc/purchaseOrder/doc-789?include=metadata,views,data' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

docType
required
string

文档类型 Document type

docId
required
string

文档ID Document ID

query Parameters
include
string

包含的数据部分（逗号分隔） Included data parts (comma-separated)

可选值: properties, metadata, views, data, comments, revisions, settings Options: properties, metadata, views, data, comments, revisions, settings

viewId
string

视图ID View ID

page
integer <int32>

页码 Page number

pageSize
integer <int32>

每页数量 Page size

commentsLimit
integer <int32>

评论数量限制 Comments limit

revisionsLimit
integer <int32>

修订数量限制 Revisions limit

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出工作区文档

列出工作区文档 List workspace documents

获取工作区下的所有文档列表。需要是工作区成员。 Get the list of all documents under the workspace. Requires workspace membership.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/workspaces/ws-456/documents?docType=purchaseOrder&page=1&pageSize=20' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

workspaceId
required
string

工作区ID Workspace ID

query Parameters
docType
string

文档类型过滤 Filter by document type

search
string

搜索关键词 Search keyword

createdBy
string

创建者过滤 Filter by creator

sort
string
Default: "updatedAt"

排序字段 Sort field

direction
string (Common.Direction)
Enum: "asc" "desc"

排序方向 Sort direction

page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Catalog

创建 Catalog

创建 Catalog Create catalog

在组织下创建新的产品目录。需要组织管理员或有权限的成员。 Create a new product catalog under organization. Requires organization admin or authorized member.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "电子产品目录",
    "catalogType": "supplier",
    "sharingEnabled": true
  }'
path Parameters
organizationId
required
string

组织 ID Organization ID

Request Body schema: application/json
required

创建请求 Create request

name
required
string

Catalog 名称 Catalog name

description
string

Catalog 描述 Catalog description

catalogType
required
string
Enum: "supplier" "distributor" "manufacturer" "retail"

Catalog 类型 Catalog type

docType
string
Default: "catalog"

文档类型(默认为 "catalog") Document type (default: "catalog")

workspaceId
string

所属工作区 ID(可选,null 表示组织级别) Workspace ID (optional, null for organization-level)

sharingEnabled
boolean
Default: false

是否启用分享 Enable sharing

Array of objects (Document.Catalog.CatalogFieldDefinition)

自定义字段定义 Custom field definitions

不同行业的商品字段可能不一样,例如:

  • 电子产品: 品牌、型号、规格参数
  • 服装: 尺码、颜色、材质
  • 食品: 保质期、产地、配料

Different industries have different product fields:

  • Electronics: brand, model, specs
  • Clothing: size, color, material
  • Food: expiry date, origin, ingredients
views
Array of any

初始视图配置(可选) Initial view configurations (optional)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "catalogType": "supplier",
  • "docType": "catalog",
  • "workspaceId": "string",
  • "sharingEnabled": false,
  • "fields": [
    ],
  • "views": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 Catalog

列出组织的 Catalog List organization catalogs

获取组织下的所有 Catalog 列表。 Get list of all catalogs under organization.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs?catalogType=supplier&page=1&pageSize=20' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

query Parameters
workspaceId
string

工作区 ID 过滤(可选) Filter by workspace ID

catalogType
string (Document.Catalog.CatalogType)
Enum: "supplier" "distributor" "manufacturer" "retail"

Catalog 类型过滤 Filter by catalog type

search
string

搜索关键词 Search keyword

sharingEnabled
boolean

仅显示启用分享的 Catalog Show only sharing-enabled catalogs

sort
string
Default: "updatedAt"

排序字段 Sort field

direction
string (Common.Direction)
Enum: "asc" "desc"

排序方向 Sort direction

page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 Catalog 详情

获取 Catalog 详情 Get catalog details

获取指定 Catalog 的详细信息。 Get detailed information of specified catalog.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

catalogId
required
string

Catalog ID Catalog ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Catalog

更新 Catalog Update catalog

更新 Catalog 的基本信息和设置。 Update catalog basic information and settings.

示例（cURL）:

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "更新后的产品目录",
    "sharingEnabled": true
  }'
path Parameters
organizationId
required
string

组织 ID Organization ID

catalogId
required
string

Catalog ID Catalog ID

Request Body schema: application/json
required

更新请求 Update request

name
string

Catalog 名称 Catalog name

description
string

Catalog 描述 Catalog description

catalogType
string
Enum: "supplier" "distributor" "manufacturer" "retail"

Catalog 类型 Catalog type

sharingEnabled
boolean

是否启用分享 Enable sharing

object

分享设置 Sharing settings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "catalogType": "supplier",
  • "sharingEnabled": true,
  • "sharingSettings": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 Catalog

删除 Catalog Delete catalog

删除指定的 Catalog。如果 Catalog 有活跃的 Connection,需要先删除或禁用 Connection。 Delete specified catalog. If catalog has active connections, must delete or disable connections first.

示例（cURL）:

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

catalogId
required
string

Catalog ID Catalog ID

query Parameters
force
boolean
Default: false

强制删除(即使有活跃的 Connection) Force delete (even if has active connections)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取字段定义

获取 Catalog 字段定义 Get catalog field definitions

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456/fields' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string
catalogId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

添加字段

添加 Catalog 字段 Add catalog field

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456/fields' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "品牌",
    "type": "text",
    "required": true
  }'
path Parameters
organizationId
required
string
catalogId
required
string
Request Body schema: application/json
required
id
string

字段 ID(可选,创建时不提供) Field ID (optional, not provided on creation)

name
required
string

字段名称 Field name

type
required
string
Enum: "text" "long_text" "number" "currency" "percent" "date" "datetime" "boolean" "single_select" "multi_select" "attachment" "user" "relation"

字段类型 Field type

required
boolean
Default: false

是否必填 Required

unique
boolean
Default: false

是否唯一 Unique

readOnly
boolean
Default: false

是否只读 Read only

defaultValue
any

默认值 Default value

Array of objects (Common.SelectOption)

选择类字段的选项(type=single_select 或 multi_select 时) Select options (when type=single_select or multi_select)

description
string

字段描述 Field description

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "text",
  • "required": false,
  • "unique": false,
  • "readOnly": false,
  • "defaultValue": null,
  • "selectOptions": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新字段

更新 Catalog 字段 Update catalog field

示例（cURL）:

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456/fields/field-789' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "required": false
  }'
path Parameters
organizationId
required
string
catalogId
required
string
fieldId
required
string
Request Body schema: application/json
required
id
string

字段 ID(可选,创建时不提供) Field ID (optional, not provided on creation)

name
required
string

字段名称 Field name

type
required
string
Enum: "text" "long_text" "number" "currency" "percent" "date" "datetime" "boolean" "single_select" "multi_select" "attachment" "user" "relation"

字段类型 Field type

required
boolean
Default: false

是否必填 Required

unique
boolean
Default: false

是否唯一 Unique

readOnly
boolean
Default: false

是否只读 Read only

defaultValue
any

默认值 Default value

Array of objects (Common.SelectOption)

选择类字段的选项(type=single_select 或 multi_select 时) Select options (when type=single_select or multi_select)

description
string

字段描述 Field description

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "text",
  • "required": false,
  • "unique": false,
  • "readOnly": false,
  • "defaultValue": null,
  • "selectOptions": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除字段

删除 Catalog 字段 Delete catalog field

示例（cURL）:

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456/fields/field-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string
catalogId
required
string
fieldId
required
string
query Parameters
force
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取产品统计

获取 Catalog 的产品统计 Get catalog product statistics

获取 Catalog 中产品的统计信息。 Get product statistics of catalog.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/catalogs/catalog-456/stats' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

catalogId
required
string

Catalog ID Catalog ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

OrderBook

创建 OrderBook

创建 OrderBook Create orderbook

可以基于已连接的 Connection 创建,自动生成字段定义和初始数据。 Can create based on connected Connections, auto-generating field definitions and initial data.

示例（cURL）:

# 基于 Connection 创建
curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/orderbooks' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "我的订货本",
    "sourceConnectionIds": ["conn-456", "conn-789"]
  }'
path Parameters
organizationId
required
string
Request Body schema: application/json
required
name
required
string

OrderBook 名称 OrderBook name

description
string

OrderBook 描述 OrderBook description

docType
string
Default: "orderbook"

文档类型(默认为 "orderbook") Document type (default: "orderbook")

workspaceId
string

所属工作区 ID(可选,null 表示组织级别) Workspace ID (optional, null for organization-level)

sourceConnectionIds
Array of strings

基于已连接的 Connection 创建 Create based on connected connections

如果提供,将从这些 Connection 的源 Catalog 自动生成字段定义和初始数据。 If provided, will auto-generate field definitions and initial data from source Catalogs.

Array of objects (Document.OrderBook.OrderBookFieldDefinition)

自定义字段定义(可选) Custom field definitions (optional)

如果提供 sourceConnectionIds,会与源字段合并。 If sourceConnectionIds provided, will merge with source fields.

views
Array of any

初始视图配置(可选) Initial view configurations (optional)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "docType": "orderbook",
  • "workspaceId": "string",
  • "sourceConnectionIds": [
    ],
  • "fields": [
    ],
  • "views": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 OrderBook

列出 OrderBook List orderbooks

path Parameters
organizationId
required
string
query Parameters
workspaceId
string
search
string
canShareAsCatalog
boolean
sort
string
Default: "updatedAt"
direction
string (Common.Direction)
Enum: "asc" "desc"
page
integer <int32>
Default: 1
pageSize
integer <int32>
Default: 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 OrderBook 详情

获取 OrderBook 详情 Get orderbook details

path Parameters
organizationId
required
string
orderBookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 OrderBook

更新 OrderBook Update orderbook

path Parameters
organizationId
required
string
orderBookId
required
string
Request Body schema: application/json
required
name
string

OrderBook 名称 OrderBook name

description
string

OrderBook 描述 OrderBook description

canShareAsCatalog
boolean

能否作为 Catalog 分享 Can be shared as catalog

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "canShareAsCatalog": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 OrderBook

删除 OrderBook Delete orderbook

path Parameters
organizationId
required
string
orderBookId
required
string
query Parameters
force
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

创建 Binding

创建 Connection Binding Create connection binding

将 OrderBook 与 Connection 建立 Binding 关系,配置字段映射和过滤条件。 Establish a Binding relationship between OrderBook and Connection, configuring field mapping and filter conditions.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/orderbooks/orderbook-456/bindings' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "connectionId": "conn-789",
    "fieldMapping": {
      "rules": [
        {
          "sourceFieldId": "src-field-1",
          "targetFieldId": "tgt-field-1",
          "transformType": "direct"
        }
      ],
      "unmappedFields": "create"
    },
    "receiverFilter": {
      "acceptMode": "auto"
    }
  }'
path Parameters
organizationId
required
string
orderBookId
required
string
Request Body schema: application/json
required
connectionId
required
string

Connection ID Connection ID

targetOrderBookId
required
string

目标 OrderBook ID Target OrderBook ID

object

接收方过滤配置(Inbound 配置) Receiver filter (Inbound config)

object

字段映射配置(Inbound 配置) Field mapping (Inbound config)

object

冲突解决配置(Inbound 配置) Conflict resolution (Inbound config)

Responses

Request samples

Content type
application/json
{
  • "connectionId": "string",
  • "targetOrderBookId": "string",
  • "receiverFilter": {
    },
  • "fieldMapping": {
    },
  • "conflictResolution": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 Binding

列出 OrderBook 的 Binding List orderbook bindings

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/orderbooks/orderbook-456/bindings' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string
orderBookId
required
string
query Parameters
status
string (Document.Connection.BindingStatus)
Enum: "pending" "active" "paused" "rejected"

ConnectionBinding 状态枚举 ConnectionBinding status enum

page
integer <int32>
Default: 1
pageSize
integer <int32>
Default: 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Binding

更新 Binding Update binding

示例（cURL）:

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/orderbooks/orderbook-456/bindings/binding-999' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "bindingStatus": "active"
  }'
path Parameters
organizationId
required
string
orderBookId
required
string
bindingId
required
string
Request Body schema: application/json
required
bindingStatus
string
Enum: "pending" "active" "paused" "rejected"

Binding 状态 Binding status

object

接收方过滤配置 Receiver filter

object

字段映射配置 Field mapping

object

冲突解决配置 Conflict resolution

Responses

Request samples

Content type
application/json
{
  • "bindingStatus": "pending",
  • "receiverFilter": {
    },
  • "fieldMapping": {
    },
  • "conflictResolution": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 Binding

删除 Binding Delete binding

示例（cURL）:

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/orderbooks/orderbook-456/bindings/binding-999' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string
orderBookId
required
string
bindingId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

预览字段映射

预览字段映射 Preview field mapping

根据源 Catalog 和目标 OrderBook 的字段,生成建议的字段映射规则。 Generate suggested field mapping rules based on source Catalog and target OrderBook fields.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/orderbooks/orderbook-456/field-mapping/preview' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "connectionId": "conn-789"
  }'
path Parameters
organizationId
required
string
orderBookId
required
string
Request Body schema: application/json
required
connectionId
required
string

Connection ID Connection ID

Responses

Request samples

Content type
application/json
{
  • "connectionId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取行来源

获取行来源信息 Get row source information

path Parameters
organizationId
required
string
orderBookId
required
string
rowId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 OrderBook 统计

获取 OrderBook 统计 Get orderbook statistics

path Parameters
organizationId
required
string
orderBookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Connection

列出 Inbound Binding

列出组织的 Inbound Binding List organization's inbound bindings

path Parameters
organizationId
required
string
query Parameters
targetOrderBookId
string
bindingStatus
string (Document.Connection.BindingStatus)
Enum: "pending" "active" "paused" "rejected"

ConnectionBinding 状态枚举 ConnectionBinding status enum

sourceOrganizationId
string
page
integer <int32>
Default: 1
pageSize
integer <int32>
Default: 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建 Connection

创建 Connection Create connection

path Parameters
organizationId
required
string
Request Body schema: application/json
required
name
required
string

Connection 名称 Connection name

description
string

Connection 描述 Connection description

sourceCatalogId
required
string

源 Catalog ID Source catalog ID

shareMode
required
string
Enum: "single" "multiple" "public"

分享模式 Share mode

required
object

访问控制配置 Access control

required
object

分享范围配置 Share scope

object

默认接收方配置 Default receiver config

object

传播事件配置 Propagation events

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "sourceCatalogId": "string",
  • "shareMode": "single",
  • "accessControl": {
    },
  • "shareScope": {
    },
  • "defaultReceiverConfig": {
    },
  • "propagationEvents": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 Connection

列出 Connection List connections

path Parameters
organizationId
required
string
query Parameters
sourceCatalogId
string
shareMode
string (Document.Connection.ShareMode)
Enum: "single" "multiple" "public"

分享模式枚举 Share mode enum

status
string (Document.Connection.ConnectionStatus)
Enum: "active" "paused" "disabled"

Connection 状态枚举 Connection status enum

search
string
sort
string
Default: "createdAt"
direction
string (Common.Direction)
Enum: "asc" "desc"
page
integer <int32>
Default: 1
pageSize
integer <int32>
Default: 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 Connection 详情

获取 Connection 详情 Get connection details

path Parameters
organizationId
required
string
connectionId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Connection

更新 Connection Update connection

path Parameters
organizationId
required
string
connectionId
required
string
Request Body schema: application/json
required
name
string

Connection 名称 Connection name

description
string

Connection 描述 Connection description

status
string
Enum: "active" "paused" "disabled"

Connection 状态 Connection status

object

访问控制配置 Access control

object

分享范围配置 Share scope

object

默认接收方配置 Default receiver config

object

传播事件配置 Propagation events

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "active",
  • "accessControl": {
    },
  • "shareScope": {
    },
  • "defaultReceiverConfig": {
    },
  • "propagationEvents": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 Connection

删除 Connection Delete connection

path Parameters
organizationId
required
string
connectionId
required
string
query Parameters
force
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

关联 Connection

创建 ConnectionBinding Create connection binding

path Parameters
organizationId
required
string
connectionId
required
string
Request Body schema: application/json
required
connectionId
required
string

Connection ID Connection ID

targetOrderBookId
required
string

目标 OrderBook ID Target OrderBook ID

object

接收方过滤配置(Inbound 配置) Receiver filter (Inbound config)

object

字段映射配置(Inbound 配置) Field mapping (Inbound config)

object

冲突解决配置(Inbound 配置) Conflict resolution (Inbound config)

Responses

Request samples

Content type
application/json
{
  • "connectionId": "string",
  • "targetOrderBookId": "string",
  • "receiverFilter": {
    },
  • "fieldMapping": {
    },
  • "conflictResolution": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 Binding

列出 Connection 的 Binding List connection bindings

path Parameters
organizationId
required
string
connectionId
required
string
query Parameters
bindingStatus
string (Document.Connection.BindingStatus)
Enum: "pending" "active" "paused" "rejected"

ConnectionBinding 状态枚举 ConnectionBinding status enum

targetOrganizationId
string
page
integer <int32>
Default: 1
pageSize
integer <int32>
Default: 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 Binding 详情

获取 Binding 详情 Get binding details

path Parameters
organizationId
required
string
connectionId
required
string
bindingId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Binding

更新 ConnectionBinding Update connection binding

path Parameters
organizationId
required
string
connectionId
required
string
bindingId
required
string
Request Body schema: application/json
required
bindingStatus
string
Enum: "pending" "active" "paused" "rejected"

Binding 状态 Binding status

object

接收方过滤配置 Receiver filter

object

字段映射配置 Field mapping

object

冲突解决配置 Conflict resolution

Responses

Request samples

Content type
application/json
{
  • "bindingStatus": "pending",
  • "receiverFilter": {
    },
  • "fieldMapping": {
    },
  • "conflictResolution": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 Binding

删除 ConnectionBinding Delete connection binding

path Parameters
organizationId
required
string
connectionId
required
string
bindingId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

审批 Binding

审批 ConnectionBinding Approve connection binding

path Parameters
organizationId
required
string
connectionId
required
string
bindingId
required
string
Request Body schema: application/json
required
action
required
string
Enum: "approve" "reject"
comment
string

Responses

Request samples

Content type
application/json
{
  • "action": "approve",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

手动触发同步

手动触发同步 Manually trigger sync

path Parameters
organizationId
required
string
connectionId
required
string
Request Body schema: application/json
required
forceFullSync
boolean
bindingIds
Array of strings

Responses

Request samples

Content type
application/json
{
  • "forceFullSync": true,
  • "bindingIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取同步状态

获取同步状态 Get sync status

path Parameters
organizationId
required
string
connectionId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Connector

创建 Connector

创建 Connector Create connector

在组织内创建文档之间的联动关系。需要有源文档和目标文档的访问权限。 Create linkage between documents within organization. Requires access to both source and target documents.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "主商品库到分店商品库",
    "connectorType": "catalog_clone",
    "sourceDocId": "catalog-main-001",
    "targetDocId": "catalog-branch-001",
    "catalogCloneConfig": {
      "syncMode": "full",
      "syncDirection": "one_way",
      "linkedScope": {"mode": "all"},
      "localEnhancements": {
        "allowLocalAdd": true,
        "allowLocalDelete": true,
        "allowLocalModify": true
      },
      "conflictResolution": {"defaultStrategy": "keep_upstream"}
    }
  }'
path Parameters
organizationId
required
string

组织 ID Organization ID

Request Body schema: application/json
required

创建请求 Create request

name
required
string

Connector 名称 Connector name

description
string

Connector 描述 Connector description

connectorType
required
string
Enum: "catalog_clone" "orderbook_to_catalog"

Connector 类型 Connector type

sourceDocId
required
string

源文档 ID Source document ID

targetDocId
required
string

目标文档 ID Target document ID

workspaceId
string

所属工作区 ID(可选,null 表示组织级别) Workspace ID (optional, null for organization-level)

object

Catalog 复制配置(connectorType=catalog_clone 时) Catalog clone config (when connectorType=catalog_clone)

object

OrderBook 转 Catalog 配置(connectorType=orderbook_to_catalog 时) OrderBook to Catalog config (when connectorType=orderbook_to_catalog)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "connectorType": "catalog_clone",
  • "sourceDocId": "string",
  • "targetDocId": "string",
  • "workspaceId": "string",
  • "catalogCloneConfig": {
    },
  • "orderbookToCatalogConfig": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 Connector

列出组织的 Connector List organization connectors

获取组织下的所有 Connector 列表。 Get list of all connectors under organization.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors?connectorType=catalog_clone&status=active' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

query Parameters
workspaceId
string

工作区 ID 过滤 Filter by workspace ID

connectorType
string (Document.Connector.ConnectorType)
Enum: "catalog_clone" "orderbook_to_catalog"

Connector 类型过滤 Filter by connector type

sourceDocId
string

源文档 ID 过滤 Filter by source document ID

targetDocId
string

目标文档 ID 过滤 Filter by target document ID

status
string (Document.Connector.ConnectorStatus)
Enum: "active" "paused" "disabled"

Connector 状态过滤 Filter by connector status

search
string

搜索关键词 Search keyword

sort
string
Default: "updatedAt"

排序字段 Sort field

direction
string (Common.Direction)
Enum: "asc" "desc"

排序方向 Sort direction

page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 Connector 详情

获取 Connector 详情 Get connector details

获取指定 Connector 的详细信息。 Get detailed information of specified connector.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Connector

更新 Connector Update connector

更新 Connector 的配置信息。 Update connector configuration.

示例（cURL）:

curl -X PATCH 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "paused"
  }'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

Request Body schema: application/json
required

更新请求 Update request

name
string

Connector 名称 Connector name

description
string

Connector 描述 Connector description

status
string
Enum: "active" "paused" "disabled"

Connector 状态 Connector status

object

Catalog 复制配置 Catalog clone config

object

OrderBook 转 Catalog 配置 OrderBook to Catalog config

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "active",
  • "catalogCloneConfig": {
    },
  • "orderbookToCatalogConfig": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 Connector

删除 Connector Delete connector

删除指定的 Connector。删除后,联动关系将被解除。 Delete specified connector. After deletion, linkage will be removed.

示例（cURL）:

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

query Parameters
deleteLinkedData
boolean
Default: false

是否删除目标文档中的联动数据 Delete linked data in target document

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

列出联动行

列出 LinkedRow List linked rows

获取 Connector 的所有联动行记录。 Get all linked row records of connector.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456/linked-rows' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

query Parameters
linkStatus
string
Enum: "active" "broken" "paused"

联动状态过滤 Filter by link status

sourceRowId
string

源行 ID 过滤 Filter by source row ID

targetRowId
string

目标行 ID 过滤 Filter by target row ID

page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 20

每页数量 Page size

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取联动行详情

获取 LinkedRow 详情 Get linked row details

获取指定联动行的详细信息。 Get detailed information of specified linked row.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456/linked-rows/link-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

linkId
required
string

Link ID Link ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除联动行

删除 LinkedRow Delete linked row

删除指定的联动行记录,解除源行和目标行的联动关系。 Delete specified linked row record, remove linkage between source and target rows.

示例（cURL）:

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456/linked-rows/link-789' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

linkId
required
string

Link ID Link ID

query Parameters
deleteTargetRow
boolean
Default: false

是否删除目标行 Delete target row

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取统计信息

获取 Connector 统计信息 Get connector statistics

获取 Connector 的统计信息。 Get connector statistics.

示例（cURL）:

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456/stats' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

触发同步

触发 Connector 同步 Trigger connector sync

手动触发 Connector 的数据同步。 Manually trigger connector data synchronization.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/connectors/connector-456/sync' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织 ID Organization ID

connectorId
required
string

Connector ID Connector ID

query Parameters
fullSync
boolean
Default: false

是否全量同步 Full sync

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

OAuth

OIDC元数据

返回 OIDC 提供方的标准发现文档。

Return OIDC provider discovery document.

Responses

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "authorization_endpoint": "string",
  • "token_endpoint": "string",
  • "userinfo_endpoint": "string",
  • "jwks_uri": "string",
  • "scopes_supported": [
    ],
  • "response_types_supported": [
    ],
  • "grant_types_supported": [
    ],
  • "id_token_signing_alg_values_supported": [
    ],
  • "claims_supported": [
    ]
}

授权请求

授权码流程的授权端点。

Authorization endpoint for authorization code flow.

Responses

JWKS 公钥

返回 JSON Web Key Set 公钥集合。

Return JSON Web Key Set public keys.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

令牌颁发

颁发访问令牌与刷新令牌。

Issue access and refresh tokens.

示例（cURL）:

curl -X POST 'https://auth.nexusbook.app/token' \\
  -H 'Content-Type: application/x-www-form-urlencoded' \\
  -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=doc:read data:read'

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

用户信息

返回登录用户的信息声明。

Return user info claims.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Authentication

修改密码

修改密码 Change password

修改当前用户的密码（需要认证）。 Change current user's password (requires authentication).

Request Body schema: application/json
required
currentPassword
required
string

当前密码 Current password

newPassword
required
string

新密码 New password

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "newPassword": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

忘记密码

请求密码重置 Request password reset

发送密码重置验证码。 Send password reset verification code.

Request Body schema: application/json
required
target
required
string

邮箱或手机号 Email or phone number

Responses

Request samples

Content type
application/json
{
  • "target": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

用户登录

用户登录 User login

支持多种登录方式：邮箱+密码、手机+验证码、OAuth。 Supports multiple login methods: email+password, phone+code, OAuth.

示例（邮箱登录）：

curl -X POST 'https://open.nexusbook.app/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "rememberMe": true
  }'
Request Body schema: application/json
required
email
string

邮箱 Email

phone
string

手机号 Phone number

password
string

密码 Password

verificationCode
string

验证码（手机登录时使用） Verification code (for phone login)

authorizationCode
string

OAuth 授权码（OAuth 登录时使用） OAuth authorization code (for OAuth login)

provider
string

OAuth 提供商（OAuth 登录时使用） OAuth provider (for OAuth login)

twoFactorCode
string

两步验证码（如果启用了 2FA） Two-factor code (if 2FA enabled)

rememberMe
boolean

记住我（延长会话时间） Remember me (extend session)

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "phone": "string",
  • "password": "string",
  • "verificationCode": "string",
  • "authorizationCode": "string",
  • "provider": "string",
  • "twoFactorCode": "string",
  • "rememberMe": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

退出登录

退出登录 Logout

吊销当前访问令牌和刷新令牌。 Revoke current access and refresh tokens.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

刷新令牌

刷新令牌 Refresh token

使用刷新令牌获取新的访问令牌。 Use refresh token to get new access token.

Request Body schema: application/json
required
refreshToken
required
string

刷新令牌 Refresh token

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

用户注册

用户注册 User registration

支持邮箱注册和手机号注册。 Supports email and phone registration.

示例（邮箱注册）：

curl -X POST 'https://open.nexusbook.app/api/v1/auth/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "displayName": "张三",
    "agreeToTerms": true
  }'
Request Body schema: application/json
required
email
string

邮箱 Email

phone
string

手机号 Phone number

password
string

密码（邮箱注册时必填） Password (required for email registration)

displayName
required
string

显示名称 Display name

invitationCode
string

邀请码（可选） Invitation code (optional)

agreeToTerms
required
boolean

同意服务条款 Agree to terms of service

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "phone": "string",
  • "password": "string",
  • "displayName": "string",
  • "invitationCode": "string",
  • "agreeToTerms": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

重置密码

重置密码 Reset password

使用验证码重置密码。 Reset password using verification code.

Request Body schema: application/json
required
target
required
string

邮箱或手机号 Email or phone number

verificationCode
required
string

验证码 Verification code

newPassword
required
string

新密码 New password

Responses

Request samples

Content type
application/json
{
  • "target": "string",
  • "verificationCode": "string",
  • "newPassword": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

列出会话

列出活跃会话 List active sessions

获取当前用户的所有活跃会话。 Get all active sessions of current user.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

吊销所有其他会话

吊销所有其他会话 Revoke all other sessions

吊销除当前会话外的所有会话。 Revoke all sessions except the current one.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

吊销会话

吊销会话 Revoke session

吊销指定的会话。 Revoke specified session.

path Parameters
sessionId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

禁用两步验证

禁用两步验证 Disable two-factor authentication

禁用当前用户的两步验证。 Disable two-factor authentication for current user.

Request Body schema: application/json
required
password
required
string

当前密码或验证码 Current password or verification code

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

启用两步验证

启用两步验证 Enable two-factor authentication

确认并启用两步验证。 Confirm and enable two-factor authentication.

Request Body schema: application/json
required
method
required
string
Enum: "totp" "sms" "email" "backupCode"

两步验证方式 Two-factor method

code
required
string

验证码（用于确认） Verification code (for confirmation)

Responses

Request samples

Content type
application/json
{
  • "method": "totp",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

设置两步验证

设置两步验证 Setup two-factor authentication

初始化两步验证设置，返回 TOTP 密钥或备用码。 Initialize two-factor setup, returns TOTP secret or backup codes.

Request Body schema: application/json
required
method
required
string
Enum: "totp" "sms" "email" "backupCode"

两步验证方式 Two-factor method

Responses

Request samples

Content type
application/json
{
  • "method": "totp"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

发送验证码

发送验证码 Send verification code

发送验证码到邮箱或手机号。 Send verification code to email or phone.

Request Body schema: application/json
required
target
required
string

邮箱或手机号 Email or phone number

type
required
string
Enum: "login" "register" "resetPassword" "enableTwoFactor"

验证码类型 Code type

Responses

Request samples

Content type
application/json
{
  • "target": "string",
  • "type": "login"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

API Keys

创建 API Key

创建 API Key Create API Key

创建新的 API 密钥。密钥只在创建时返回完整内容，请妥善保存。 Create new API key. Full key is only returned on creation, please save it securely.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/api-keys' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "生产环境 API Key",
    "description": "用于生产环境的后端服务",
    "scopes": ["doc:read", "doc:write", "data:read", "data:write"],
    "expiresInDays": 365,
    "rateLimit": 1000
  }'
Request Body schema: application/json
required
name
required
string

名称 Name

description
string

描述 Description

scopes
required
Array of strings (Auth.AuthScope)
Items Enum: "doc:read" "doc:write" "doc:delete" "data:read" "data:write" "data:delete" "org:manage" "workspace:manage" "user:manage" "webhook:manage" "all"

权限范围 Scopes

organizationId
string

所属组织ID（可选） Organization ID (optional)

workspaceId
string

所属工作区ID（可选） Workspace ID (optional)

expiresInDays
integer <int32>

过期天数（不设置则永不过期） Expiration days (never expires if not set)

rateLimit
integer <int32>

速率限制（请求数/分钟） Rate limit (requests per minute)

ipWhitelist
Array of strings

IP 白名单 IP whitelist

allowedOrigins
Array of strings

允许的来源（CORS） Allowed origins (CORS)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "scopes": [
    ],
  • "organizationId": "string",
  • "workspaceId": "string",
  • "expiresInDays": 0,
  • "rateLimit": 0,
  • "ipWhitelist": [
    ],
  • "allowedOrigins": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出 API Keys

列出 API Keys List API Keys

获取当前用户的所有 API 密钥列表。 Get list of all API keys for current user.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/api-keys?page=1&pageSize=20&status=active' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
page
integer <int32>
Default: 1

页码（从1开始） Page number (starts from 1)

pageSize
integer <int32>
Default: 20

每页数量 Page size

status
string (Auth.ApiKeyStatus)
Enum: "active" "expired" "revoked" "disabled"

按状态筛选 Filter by status

organizationId
string

按组织ID筛选 Filter by organization ID

workspaceId
string

按工作区ID筛选 Filter by workspace ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

批量吊销 API Keys

批量吊销 API Keys Batch revoke API Keys

批量吊销多个 API 密钥。 Batch revoke multiple API keys.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/api-keys/batch-revoke' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKeyIds": ["key-1", "key-2", "key-3"]
  }'
Request Body schema: application/json
required
apiKeyIds
required
Array of strings

API Key ID 列表 API Key ID list

Responses

Request samples

Content type
application/json
{
  • "apiKeyIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 API Key 详情

获取 API Key 详情 Get API Key details

获取指定 API 密钥的详细信息（不包含完整密钥）。 Get details of specified API key (without full key).

path Parameters
apiKeyId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 API Key

更新 API Key Update API Key

更新 API 密钥的配置信息。 Update API key configuration.

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/api-keys/{apiKeyId}' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "生产环境 API Key (更新)",
    "scopes": ["doc:read", "data:read"],
    "rateLimit": 500
  }'
path Parameters
apiKeyId
required
string
Request Body schema: application/json
required
name
string

名称 Name

description
string

描述 Description

scopes
Array of strings (Auth.AuthScope)
Items Enum: "doc:read" "doc:write" "doc:delete" "data:read" "data:write" "data:delete" "org:manage" "workspace:manage" "user:manage" "webhook:manage" "all"

权限范围 Scopes

rateLimit
integer <int32>

速率限制（请求数/分钟） Rate limit (requests per minute)

ipWhitelist
Array of strings

IP 白名单 IP whitelist

allowedOrigins
Array of strings

允许的来源（CORS） Allowed origins (CORS)

enabled
boolean

启用/禁用 Enable/disable

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "scopes": [
    ],
  • "rateLimit": 0,
  • "ipWhitelist": [
    ],
  • "allowedOrigins": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 API Key

删除 API Key Delete API Key

彻底删除 API 密钥及其所有使用记录。 Permanently delete API key and all its usage logs.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/api-keys/{apiKeyId}' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
apiKeyId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

获取使用记录

获取 API Key 使用记录 Get API Key usage logs

获取 API 密钥的使用记录。 Get usage logs of API key.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/api-keys/{apiKeyId}/logs?page=1&pageSize=50&startTime=2024-12-01T00:00:00Z&endTime=2024-12-05T23:59:59Z' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
apiKeyId
required
string
query Parameters
page
integer <int32>
Default: 1

页码 Page number

pageSize
integer <int32>
Default: 50

每页数量 Page size

startTime
string

开始时间 Start time

endTime
string

结束时间 End time

method
string

按方法筛选 Filter by method

path
string

按路径筛选 Filter by path

statusCode
integer <int32>

按状态码筛选 Filter by status code

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

重新生成 API Key

重新生成 API Key Regenerate API Key

重新生成 API 密钥。旧密钥立即失效，新密钥只返回一次。 Regenerate API key. Old key is immediately invalidated, new key is returned only once.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/api-keys/{apiKeyId}/regenerate' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
apiKeyId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

吊销 API Key

吊销 API Key Revoke API Key

永久吊销 API 密钥，吊销后无法恢复。 Permanently revoke API key, cannot be restored after revocation.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/api-keys/{apiKeyId}/revoke' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
apiKeyId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

获取使用统计

获取 API Key 使用统计 Get API Key usage statistics

获取 API 密钥的使用统计信息。 Get usage statistics of API key.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/api-keys/{apiKeyId}/stats?period=7d' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
apiKeyId
required
string
query Parameters
period
string
Default: "7d"

统计周期（1h, 24h, 7d, 30d, 90d） Statistics period (1h, 24h, 7d, 30d, 90d)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Subscription Plans

列出订阅计划

列出可用订阅计划

query Parameters
includeArchived
boolean
Default: false

是否包含已归档计划

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

获取订阅计划详情

获取订阅计划详情

path Parameters
planId
required
string

计划 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Subscription Management

获取组织订阅信息

获取当前组织订阅信息

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建或更新订阅

创建或更新组织订阅

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

订阅请求

planId
required
string

计划 ID

billingCycle
required
string
Enum: "monthly" "yearly"

计费周期

paymentMethodId
string

支付方式 ID

Responses

Request samples

Content type
application/json
{
  • "planId": "string",
  • "billingCycle": "monthly",
  • "paymentMethodId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

取消订阅

取消订阅

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

取消请求

cancelImmediately
required
boolean

是否立即取消

reason
string

取消原因

feedback
string

反馈意见

Responses

Request samples

Content type
application/json
{
  • "cancelImmediately": true,
  • "reason": "string",
  • "feedback": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

变更订阅计划

升级/降级订阅

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

变更计划请求

targetPlanId
required
string

目标计划 ID

billingCycle
required
string
Enum: "monthly" "yearly"

计费周期

effectiveDate
required
string
Enum: "immediate" "next_billing_cycle"

生效日期

Responses

Request samples

Content type
application/json
{
  • "targetPlanId": "string",
  • "billingCycle": "monthly",
  • "effectiveDate": "immediate"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

恢复订阅

恢复已取消的订阅

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Invoices

列出账单

列出组织账单

path Parameters
organizationId
required
string

组织 ID

query Parameters
status
string (Billing.InvoiceStatus)
Enum: "draft" "open" "paid" "void_status" "uncollectible"

按状态过滤

page
integer <int32>
Default: 1

页码

pageSize
integer <int32>
Default: 20

每页数量

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取账单详情

获取账单详情

path Parameters
organizationId
required
string

组织 ID

invoiceId
required
string

账单 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

支付账单

支付账单

path Parameters
organizationId
required
string

组织 ID

invoiceId
required
string

账单 ID

Request Body schema: application/json
required

支付请求

paymentMethodId
required
string

支付方式 ID

Responses

Request samples

Content type
application/json
{
  • "paymentMethodId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Payment Methods

列出支付方式

列出支付方式

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

添加支付方式

添加支付方式

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

添加请求

type
required
string
Enum: "card" "alipay" "wechat" "bank_transfer"

支付类型

paymentToken
required
string

支付 Token（由支付网关生成）

setAsDefault
boolean

设为默认

Responses

Request samples

Content type
application/json
{
  • "type": "card",
  • "paymentToken": "string",
  • "setAsDefault": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除支付方式

删除支付方式

path Parameters
organizationId
required
string

组织 ID

paymentMethodId
required
string

支付方式 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

设置默认支付方式

设置默认支付方式

path Parameters
organizationId
required
string

组织 ID

paymentMethodId
required
string

支付方式 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Usage & Quota

获取当前使用量

获取组织当前使用量

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取使用量历史

获取使用量历史趋势

path Parameters
organizationId
required
string

组织 ID

query Parameters
metricType
required
string (Billing.MetricType)
Enum: "members" "workspaces" "documents" "storage_gb" "api_calls" "realtime_sessions"

指标类型

startDate
required
string

开始日期

endDate
required
string

结束日期

granularity
required
string
Default: "day"
Enum: "hour" "day" "month"

粒度（hour/day/month）

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取配额警告

获取配额警告

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Audit Logs

查询审计日志

查询审计日志

path Parameters
organizationId
required
string

组织 ID

query Parameters
actorId
string

操作者 ID

actorType
string (Audit.ActorType)
Enum: "user" "apikey" "system" "webhook"

操作者类型

actionCategory
string (Audit.ActionCategory)
Enum: "authentication" "authorization" "data_access" "data_modification" "configuration" "user_management" "permission_management" "billing" "security" "compliance"

操作分类

actionName
string

操作名称

resourceType
string (Audit.ResourceType)
Enum: "user" "organization" "workspace" "document" "data_row" "view" "comment" "apikey" "webhook" "subscription" "invoice"

资源类型

resourceId
string

资源 ID

resultStatus
string (Audit.ResultStatus)
Enum: "success" "failure" "partial"

结果状态

startDate
string

开始时间

endDate
string

结束时间

ipAddress
string

IP 地址

search
string

全文搜索

page
integer <int32>
Default: 1

页码

pageSize
integer <int32>
Default: 20

每页数量

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建告警规则

创建审计日志告警规则

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

告警规则请求

name
required
string

规则名称

enabled
required
boolean

是否启用

required
object

条件

required
object

动作

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "conditions": {
    },
  • "actions": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

列出告警规则

列出告警规则

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

删除告警规则

删除告警规则

path Parameters
organizationId
required
string

组织 ID

ruleId
required
string

规则 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": { }
}

导出审计日志

导出审计日志

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

导出请求

format
required
string
Enum: "csv" "json" "pdf"

导出格式

object

过滤条件

includeFields
Array of strings

包含字段

Responses

Request samples

Content type
application/json
{
  • "format": "csv",
  • "filters": {
    },
  • "includeFields": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取导出状态

获取导出任务状态

path Parameters
organizationId
required
string

组织 ID

exportId
required
string

导出任务 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取审计统计

获取审计统计

path Parameters
organizationId
required
string

组织 ID

query Parameters
startDate
string

开始时间

endDate
string

结束时间

groupBy
string
Enum: "action" "actor" "resource"

分组维度

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取审计日志详情

获取审计日志详情

path Parameters
organizationId
required
string

组织 ID

logId
required
string

日志 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Compliance

获取数据访问记录（GDPR）

获取数据访问记录（GDPR）

path Parameters
organizationId
required
string

组织 ID

query Parameters
userId
string

用户 ID

dataType
string

数据类型

startDate
string

开始时间

endDate
string

结束时间

page
integer <int32>
Default: 1

页码

pageSize
integer <int32>
Default: 20

每页数量

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

生成合规性报告

生成合规性报告

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

报告请求

reportType
required
string
Enum: "gdpr" "soc2" "hipaa" "custom"

报告类型

periodStart
required
string

周期开始

periodEnd
required
string

周期结束

includeAccessLogs
boolean

包含访问日志

includeDataChanges
boolean

包含数据变更

includePermissionChanges
boolean

包含权限变更

Responses

Request samples

Content type
application/json
{
  • "reportType": "gdpr",
  • "periodStart": "string",
  • "periodEnd": "string",
  • "includeAccessLogs": true,
  • "includeDataChanges": true,
  • "includePermissionChanges": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取数据保留策略

获取数据保留策略

path Parameters
organizationId
required
string

组织 ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新数据保留策略

更新数据保留策略

path Parameters
organizationId
required
string

组织 ID

Request Body schema: application/json
required

策略请求

required
Array of objects (Audit.RetentionPolicy)

策略列表

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Webhooks

列出 Webhooks

列出所有 Webhook

List all webhooks

返回当前用户/租户的所有 Webhook 配置。 Returns all webhook configurations for current user/tenant.

query Parameters
status
string (Extensions.Webhooks.WebhookStatus)
Enum: "active" "paused" "failed"

Webhook 状态 Webhook status

page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

创建 Webhook

创建 Webhook

Create webhook

创建新的 Webhook 订阅。 Create a new webhook subscription.

示例（cURL）:

curl -X POST 'https://open.nexusbook.app/api/v1/webhooks' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Request Merged Notification",
    "url": "https://example.com/webhooks/nexusbook",
    "events": ["request_merged", "approval_approved"],
    "filters": {
      "docTypes": ["product", "inventory"]
    }
  }'
Request Body schema: application/json
required
id
required
string

Webhook ID Webhook id

name
required
string

名称 Name

description
string

描述 Description

url
required
string

目标 URL Target URL

接收 Webhook 事件的 URL。 URL to receive webhook events.

events
required
Array of strings (Extensions.Webhooks.WebhookEventType)
Items Enum: "request_created" "request_merged" "request_closed" "request_reopened" "approval_started" "approval_approved" "approval_rejected" "approval_canceled" "approval_node_completed" "comment_created" "comment_updated" "comment_deleted" "comment_resolved" "comment_mentioned" "metadata_updated" "metadata_field_added" "metadata_field_updated" "metadata_field_deleted" "view_created" "view_updated" "view_deleted" "view_default_changed" "data_row_created" "data_row_updated" "data_row_deleted" "data_bulk_operation" "revision_created" "revision_reverted"

订阅的事件类型 Subscribed event types

object

事件过滤条件 Event filters

secret
string

密钥（用于签名验证） Secret (for signature verification)

用于生成 HMAC 签名，验证消息来源。 Used to generate HMAC signature for message verification.

status
required
string
Enum: "active" "paused" "failed"

状态 Status

object

自定义请求头 Custom headers

发送 Webhook 请求时附加的自定义头。 Custom headers to include in webhook requests.

timeout
integer <int32>

超时时间（秒） Timeout in seconds

maxRetries
integer <int32>

最大重试次数 Max retry attempts

retryInterval
integer <int32>

重试间隔（秒） Retry interval in seconds

createdAt
string

创建时间 Created at

object

创建人 Created by

updatedAt
string

更新时间 Updated at

lastTriggeredAt
string

最后触发时间 Last triggered at

triggerCount
integer <int64>

触发次数 Trigger count

failureCount
integer <int64>

失败次数 Failure count

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "url": "string",
  • "events": [
    ],
  • "filters": {
    },
  • "secret": "string",
  • "status": "active",
  • "headers": {
    },
  • "timeout": 0,
  • "maxRetries": 0,
  • "retryInterval": 0,
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string",
  • "lastTriggeredAt": "string",
  • "triggerCount": 0,
  • "failureCount": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取 Webhook 详情

获取 Webhook 详情

Get webhook detail

path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新 Webhook

更新 Webhook

Update webhook

path Parameters
webhookId
required
string
Request Body schema: application/json
required
id
required
string

Webhook ID Webhook id

name
required
string

名称 Name

description
string

描述 Description

url
required
string

目标 URL Target URL

接收 Webhook 事件的 URL。 URL to receive webhook events.

events
required
Array of strings (Extensions.Webhooks.WebhookEventType)
Items Enum: "request_created" "request_merged" "request_closed" "request_reopened" "approval_started" "approval_approved" "approval_rejected" "approval_canceled" "approval_node_completed" "comment_created" "comment_updated" "comment_deleted" "comment_resolved" "comment_mentioned" "metadata_updated" "metadata_field_added" "metadata_field_updated" "metadata_field_deleted" "view_created" "view_updated" "view_deleted" "view_default_changed" "data_row_created" "data_row_updated" "data_row_deleted" "data_bulk_operation" "revision_created" "revision_reverted"

订阅的事件类型 Subscribed event types

object

事件过滤条件 Event filters

secret
string

密钥（用于签名验证） Secret (for signature verification)

用于生成 HMAC 签名，验证消息来源。 Used to generate HMAC signature for message verification.

status
required
string
Enum: "active" "paused" "failed"

状态 Status

object

自定义请求头 Custom headers

发送 Webhook 请求时附加的自定义头。 Custom headers to include in webhook requests.

timeout
integer <int32>

超时时间（秒） Timeout in seconds

maxRetries
integer <int32>

最大重试次数 Max retry attempts

retryInterval
integer <int32>

重试间隔（秒） Retry interval in seconds

createdAt
string

创建时间 Created at

object

创建人 Created by

updatedAt
string

更新时间 Updated at

lastTriggeredAt
string

最后触发时间 Last triggered at

triggerCount
integer <int64>

触发次数 Trigger count

failureCount
integer <int64>

失败次数 Failure count

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "url": "string",
  • "events": [
    ],
  • "filters": {
    },
  • "secret": "string",
  • "status": "active",
  • "headers": {
    },
  • "timeout": 0,
  • "maxRetries": 0,
  • "retryInterval": 0,
  • "createdAt": "string",
  • "createdBy": {
    },
  • "updatedAt": "string",
  • "lastTriggeredAt": "string",
  • "triggerCount": 0,
  • "failureCount": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除 Webhook

删除 Webhook

Delete webhook

path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": null
}

获取投递历史

获取投递历史

Get delivery history

查看 Webhook 的投递记录。 View webhook delivery records.

path Parameters
webhookId
required
string
query Parameters
status
string
Enum: "pending" "success" "failed" "retrying"
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取投递详情

获取投递详情

Get delivery detail

path Parameters
webhookId
required
string
deliveryId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

重新投递

重新投递

Redeliver

重新发送失败的 Webhook 事件。 Resend a failed webhook event.

path Parameters
webhookId
required
string
deliveryId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

暂停 Webhook

暂停 Webhook

Pause webhook

暂停 Webhook，停止发送事件通知。 Pause webhook to stop sending event notifications.

path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

重新生成密钥

重新生成密钥

Regenerate secret

重新生成 Webhook 签名密钥。 Regenerate webhook signature secret.

path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

恢复 Webhook

恢复 Webhook

Resume webhook

恢复已暂停的 Webhook。 Resume a paused webhook.

path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取统计信息

获取 Webhook 统计

Get webhook statistics

获取 Webhook 的统计信息（成功率、失败率等）。 Get webhook statistics (success rate, failure rate, etc).

path Parameters
webhookId
required
string
query Parameters
startDate
string
endDate
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

测试 Webhook

测试 Webhook

Test webhook

发送测试事件到 Webhook URL，验证配置是否正确。 Send a test event to webhook URL to verify configuration.

path Parameters
webhookId
required
string
Request Body schema: application/json
optional
event
required
string
Enum: "request_created" "request_merged" "request_closed" "request_reopened" "approval_started" "approval_approved" "approval_rejected" "approval_canceled" "approval_node_completed" "comment_created" "comment_updated" "comment_deleted" "comment_resolved" "comment_mentioned" "metadata_updated" "metadata_field_added" "metadata_field_updated" "metadata_field_deleted" "view_created" "view_updated" "view_deleted" "view_default_changed" "data_row_created" "data_row_updated" "data_row_deleted" "data_bulk_operation" "revision_created" "revision_reverted"

测试事件类型 Test event type

payload
any

测试载荷 Test payload

Responses

Request samples

Content type
application/json
{
  • "event": "request_created",
  • "payload": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

Internationalization

获取货币列表

获取货币列表 Get currency list

获取系统支持的货币列表。 Get list of supported currencies.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/i18n/currencies' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
includeInactive
boolean
Default: false

是否包含不活跃的货币 Whether to include inactive currencies

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

检测文本语言

检测文本语言 Detect text language

自动检测给定文本的语言。 Automatically detect language of given text.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/i18n/detect-language' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"text": "这是一段测试文本"}'
Request Body schema: application/json
required
text
required
string

待检测文本 Text to detect

Responses

Request samples

Content type
application/json
{
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

格式化数据预览

格式化数据预览 Format data preview

根据指定的语言和格式设置预览格式化结果。 Preview formatting results based on specified language and format settings.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/i18n/format-preview' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "language": "zh",
    "timezone": "Asia/Shanghai",
    "dateFormat": "YYYY-MM-DD",
    "timeFormat": "24h",
    "currency": "CNY",
    "samples": {
      "date": "2024-12-06T10:30:00Z",
      "number": 1234567.89,
      "currency": 9999.99
    }
  }'
Request Body schema: application/json
required
language
required
string

语言代码 Language code

timezone
required
string

时区 Timezone

dateFormat
required
string

日期格式 Date format

timeFormat
required
string

时间格式 Time format

currency
required
string

货币代码 Currency code

required
object

示例数据 Sample data

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "timezone": "string",
  • "dateFormat": "string",
  • "timeFormat": "string",
  • "currency": "string",
  • "samples": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取支持的语言列表

获取支持的语言列表 Get supported languages list

返回系统支持的所有语言配置列表。 Returns list of all supported language configurations.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/i18n/languages?enabledOnly=true' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
enabledOnly
boolean
Default: false

仅返回已启用的语言 Only return enabled languages

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": [
    ]
}

获取语言详细配置

获取语言详细配置 Get language detailed configuration

返回指定语言的详细配置信息。 Returns detailed configuration for specified language.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/i18n/languages/zh' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
languageCode
required
string

语言代码 Language code

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取翻译术语表

获取翻译术语表 Get translation glossary

获取组织的翻译术语表。 Get organization's translation glossary.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/glossary?sourceLanguage=zh&targetLanguage=en' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
sourceLanguage
string

源语言 Source language

targetLanguage
string

目标语言 Target language

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

添加术语到翻译术语表

添加术语到翻译术语表 Add term to translation glossary

添加术语到组织的翻译术语表。需要 owner 或 admin 权限。 Add term to organization's translation glossary. Requires owner or admin permission.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/glossary' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceLanguage": "zh",
    "targetLanguage": "en",
    "entries": [{
      "term": "订货单",
      "translation": "Purchase Order",
      "context": "business_document",
      "category": "general"
    }]
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required
sourceLanguage
required
string

源语言 Source language

targetLanguage
required
string

目标语言 Target language

required
Array of objects

术语条目列表 Glossary entries

Responses

Request samples

Content type
application/json
{
  • "sourceLanguage": "string",
  • "targetLanguage": "string",
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取时区列表

获取时区列表 Get timezone list

获取系统支持的时区列表。 Get list of supported timezones.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/i18n/timezones?region=Asia' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
region
string

按地区过滤 Filter by region

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

翻译文本内容

翻译文本内容 Translate text content

将文本从源语言翻译到目标语言。 Translate text from source language to target languages.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/i18n/translate' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceLanguage": "zh",
    "targetLanguages": ["en", "ja"],
    "texts": ["产品名称", "这是产品描述"],
    "context": "product_catalog"
  }'
Request Body schema: application/json
required
sourceLanguage
required
string

源语言 Source language

targetLanguages
required
Array of strings

目标语言列表 Target languages

texts
required
Array of strings

待翻译文本列表 Texts to translate

context
string

上下文 Context

Responses

Request samples

Content type
application/json
{
  • "sourceLanguage": "string",
  • "targetLanguages": [
    ],
  • "texts": [
    ],
  • "context": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取翻译完整度统计

获取翻译完整度统计 Get translation coverage statistics

获取各语言的翻译完整度统计信息。 Get translation coverage statistics for each language.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/i18n/translation-coverage?namespace=common' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
ns
string

命名空间过滤 Namespace filter

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取翻译建议

获取翻译建议 Get translation suggestions

获取文本的翻译建议。 Get translation suggestions for text.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/i18n/translation-suggestions' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "产品",
    "sourceLanguage": "zh",
    "targetLanguage": "en",
    "context": "field_label",
    "maxSuggestions": 5
  }'
Request Body schema: application/json
required
text
required
string

待翻译文本 Text to translate

sourceLanguage
required
string

源语言 Source language

targetLanguage
required
string

目标语言 Target language

context
string

上下文 Context

maxSuggestions
integer <int32>

最大建议数 Maximum suggestions

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "sourceLanguage": "string",
  • "targetLanguage": "string",
  • "context": "string",
  • "maxSuggestions": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取翻译资源

获取翻译资源 Get translation resources

获取指定语言的翻译资源。 Get translation resources for specified language.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/i18n/translations?language=zh&namespace=common' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
language
required
string

语言代码（必填） Language code (required)

ns
string

命名空间过滤 Namespace filter

keys
Array of strings

指定键列表 Specified keys

category
string (I18n.ResourceCategory)
Enum: "ui" "field_label" "validation_message" "notification_template" "email_template" "system_message"

资源分类 Resource category

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

批量获取多语言翻译

批量获取多语言翻译 Batch get multi-language translations

一次性获取多个语言的翻译资源。 Get translation resources for multiple languages at once.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/i18n/translations/batch' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "languages": ["zh", "en", "ja"],
    "namespace": "common",
    "keys": ["button.save", "button.cancel"]
  }'
Request Body schema: application/json
required
languages
required
Array of strings

语言列表 Languages

ns
string

命名空间 Namespace

keys
Array of strings

键列表 Keys

Responses

Request samples

Content type
application/json
{
  • "languages": [
    ],
  • "ns": "string",
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取组织国际化配置

获取组织国际化配置 Get organization i18n configuration

返回组织的国际化配置信息。 Returns organization's i18n configuration.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/config' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新组织国际化配置

更新组织国际化配置 Update organization i18n configuration

更新组织的国际化配置。需要 owner 或 admin 权限。 Update organization's i18n configuration. Requires owner or admin permission.

示例（cURL）：

curl -X PUT 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/config' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "defaultLanguage": "zh",
    "supportedLanguages": ["zh", "en", "ja"],
    "enforceLanguage": false,
    "autoDetectLanguage": true,
    "fallbackLanguage": "en",
    "defaultTimezone": "Asia/Shanghai",
    "defaultCurrency": "CNY",
    "dateFormat": "YYYY-MM-DD",
    "timeFormat": "24h"
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required
defaultLanguage
required
string

默认语言 Default language

supportedLanguages
required
Array of strings

支持的语言列表 Supported languages

enforceLanguage
required
boolean

强制使用指定语言 Enforce specific language

autoDetectLanguage
required
boolean

自动检测语言 Auto detect language

fallbackLanguage
required
string

备用语言 Fallback language

defaultTimezone
required
string

默认时区 Default timezone

defaultCurrency
required
string

默认货币 Default currency

dateFormat
required
string

日期格式 Date format

timeFormat
required
string

时间格式 Time format

required
object

数字格式 Number format

Responses

Request samples

Content type
application/json
{
  • "defaultLanguage": "string",
  • "supportedLanguages": [
    ],
  • "enforceLanguage": true,
  • "autoDetectLanguage": true,
  • "fallbackLanguage": "string",
  • "defaultTimezone": "string",
  • "defaultCurrency": "string",
  • "dateFormat": "string",
  • "timeFormat": "string",
  • "numberFormat": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取组织自定义翻译

获取组织自定义翻译 Get organization custom translations

获取组织自定义的翻译资源。 Get organization's custom translation resources.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/custom-translations?language=zh&namespace=custom' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
language
string

语言代码 Language code

ns
string

命名空间 Namespace

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

添加/更新组织自定义翻译

添加/更新组织自定义翻译 Add/update organization custom translations

添加或更新组织的自定义翻译。需要 owner 或 admin 权限。 Add or update organization's custom translations. Requires owner or admin permission.

示例（cURL）：

curl -X PUT 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/custom-translations' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "language": "zh",
    "namespace": "custom",
    "translations": {
      "field.custom_status": "自定义状态",
      "label.department": "部门名称"
    }
  }'
path Parameters
organizationId
required
string

组织ID Organization ID

Request Body schema: application/json
required
language
required
string

语言代码 Language code

ns
required
string

命名空间 Namespace

required
object

翻译内容 Translations

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "ns": "string",
  • "translations": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

删除组织自定义翻译

删除组织自定义翻译 Delete organization custom translations

删除组织的自定义翻译。需要 owner 或 admin 权限。 Delete organization's custom translations. Requires owner or admin permission.

示例（cURL）：

curl -X DELETE 'https://open.nexusbook.app/api/v1/organizations/org-123/i18n/custom-translations?language=zh&keys=field.custom_status,label.department' \
  -H 'Authorization: Bearer TOKEN'
path Parameters
organizationId
required
string

组织ID Organization ID

query Parameters
language
required
string

语言代码 Language code

keys
required
Array of strings

要删除的键列表 Keys to delete

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

User Preferences

获取当前用户偏好设置

获取当前用户偏好设置 Get current user preferences

返回当前用户的完整偏好设置或指定部分。 Returns complete preferences or specified section for current user.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/users/me/preferences?section=regional' \
  -H 'Authorization: Bearer TOKEN'
query Parameters
section
string

获取特定部分 Get specific section (general/appearance/notifications/regional/accessibility/privacy)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新用户偏好设置

更新用户偏好设置 Update user preferences

更新当前用户的偏好设置（部分更新）。 Update current user's preferences (partial update).

示例（cURL）：

curl -X PATCH 'https://open.nexusbook.app/api/v1/users/me/preferences' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "regional": {
      "language": "zh",
      "timezone": "Asia/Shanghai",
      "dateFormat": "YYYY-MM-DD",
      "timeFormat": "24h",
      "firstDayOfWeek": "monday",
      "currency": "CNY"
    }
  }'
Request Body schema: application/json
required
object

通用偏好 General preferences

object

外观偏好 Appearance preferences

object

地区偏好 Regional preferences

object

辅助功能偏好 Accessibility preferences

object

隐私偏好 Privacy preferences

Responses

Request samples

Content type
application/json
{
  • "general": {
    },
  • "appearance": {
    },
  • "regional": {
    },
  • "accessibility": {
    },
  • "privacy": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

获取用户语言偏好

获取用户语言偏好 Get user language preferences

获取当前用户的语言相关偏好设置。 Get language-related preferences for current user.

示例（cURL）：

curl -X GET 'https://open.nexusbook.app/api/v1/users/me/preferences/language' \
  -H 'Authorization: Bearer TOKEN'

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

更新用户语言偏好

更新用户语言偏好 Update user language preferences

更新当前用户的语言相关偏好设置。 Update language-related preferences for current user.

示例（cURL）：

curl -X PUT 'https://open.nexusbook.app/api/v1/users/me/preferences/language' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "primaryLanguage": "zh",
    "contentLanguages": ["zh", "en", "ja"],
    "autoDetect": true,
    "fallbackLanguage": "en"
  }'
Request Body schema: application/json
required
primaryLanguage
required
string

主要语言 Primary language

contentLanguages
required
Array of strings

内容语言列表 Content languages

autoDetect
required
boolean

自动检测语言 Auto detect language

fallbackLanguage
required
string

备用语言 Fallback language

Responses

Request samples

Content type
application/json
{
  • "primaryLanguage": "string",
  • "contentLanguages": [
    ],
  • "autoDetect": true,
  • "fallbackLanguage": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}

重置用户偏好为默认值

重置用户偏好为默认值 Reset user preferences to defaults

将指定部分或全部偏好设置重置为默认值。 Reset specified sections or all preferences to defaults.

示例（cURL）：

curl -X POST 'https://open.nexusbook.app/api/v1/users/me/preferences/reset' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sections": ["appearance", "notifications"],
    "resetAll": false
  }'
Request Body schema: application/json
required
sections
Array of strings

要重置的部分列表 Sections to reset

resetAll
boolean

重置全部 Reset all

Responses

Request samples

Content type
application/json
{
  • "sections": [
    ],
  • "resetAll": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "BAD_USER_NAME",
  • "message": {
    },
  • "payload": {
    }
}