snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/zh/developers/extend/capabilities/apis.mdx

@@ -0,0 +1,147 @@
+---
+title: 接口
+description: 使用 REST 或 GraphQL 以编程方式查询和修改您的客户关系管理数据。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+Twenty 的设计对开发者友好，提供适合您定制数据模型的强大API。 我们提供四种不同的API类型来满足不同的集成需求。
+
+## 开发者优先的方法
+
+Twenty 会针对您的数据模型生成专用 API：
+
+* **无需长ID**：直接在终端使用对象和字段名称
+* **标准与自定义对象平等对待**：您的自定义对象将获得与内置对象相同的API处理
+* **专用终端**：每个对象和字段都有自己的API终端
+* **自定义文档**：专门为您的工作区的数据模型生成
+
+<Note>
+创建 API 密钥后，可在 **设置 → API & Webhooks** 中查看您的个性化 API 文档。 由于 Twenty 会生成与您的自定义数据模型相匹配的 API，因此文档对您的工作区是唯一的。
+</Note>
+
+## 两种 API 类型
+
+### 核心API
+
+访问路径：`/rest/`或`/graphql/`。
+
+处理您实际的**记录**（数据）：
+
+* 创建、读取、更新、删除 People、Companies、Opportunities 等。
+* 查询并筛选数据
+* 管理记录关系
+
+### 元数据API
+
+访问路径：`/rest/metadata/`或`/metadata/`。
+
+管理您的**工作区和数据模型**：
+
+* 创建、修改或删除对象和字段
+* 配置工作区设置
+* 定义对象之间的关系
+
+## REST 与 GraphQL
+
+Core 和 Metadata API 均提供 REST 和 GraphQL 格式：
+
+| 格式          | 可用操作                            |
+| ----------- | ------------------------------- |
+| **REST**    | CRUD、批量操作、Upsert                |
+| **GraphQL** | 同上 + **批量 Upsert**，在一次调用中进行关系查询 |
+
+可根据需要选择 — 两种格式访问的是同一份数据。
+
+## API端点
+
+| 环境      | 基础 URL                    |
+| ------- | ------------------------- |
+| **云端**  | `https://api.twenty.com/` |
+| **自托管** | `https://{your-domain}/`  |
+
+## 身份验证
+
+每个 API 请求都需要在请求头中包含 API 密钥：
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+### 创建 API 密钥
+
+1. 前往 **设置 → APIs & Webhooks**
+2. 点击 **+ 创建密钥**
+3. 配置:
+   * **名称**：密钥的描述性名称
+   * **到期日期**：密钥的到期时间
+4. 单击 **保存**
+5. **立即复制** — 密钥仅显示一次
+
+<VimeoEmbed videoId="928786722" title="创建 API 密钥" />
+
+<Warning>
+您的 API 密钥可访问敏感数据。 不要与不受信任的服务共享它。 如果遭到泄露，请立即将其禁用并生成一个新的。
+</Warning>
+
+### 为 API 密钥分配角色
+
+为提高安全性，请分配特定角色以限制访问：
+
+1. 转到 **设置 → 成员 → 角色**
+2. 点击要分配的角色
+3. 打开 **分配** 选项卡
+4. 在 **API Keys** 下，点击 **+ Assign to API key**
+5. 选择该 API 密钥
+
+该密钥将继承该角色的权限。 详见 [权限](/l/zh/user-guide/permissions-access/capabilities/permissions)。
+
+### 管理 API 密钥
+
+**Regenerate**: 设置 → APIs & Webhooks → 点击密钥 → **Regenerate**
+
+**Delete**: 设置 → APIs & Webhooks → 点击密钥 → **Delete**
+
+## API 操作台
+
+使用我们内置的操作台，可直接在浏览器中测试您的 API — 同时支持 **REST** 和 **GraphQL**。
+
+### 访问操作台
+
+1. 前往 **设置 → APIs & Webhooks**
+2. 创建 API 密钥（必需）
+3. 点击 **REST API** 或 **GraphQL API** 打开操作台
+
+### 您将获得
+
+* **交互式文档**：针对您的特定数据模型生成
+* **实时测试**：对您的工作区执行真实的 API 调用
+* **架构浏览器**：浏览可用的对象、字段和关系
+* **请求构建器**：使用自动补全构建查询
+
+操作台会反映您的自定义对象和字段，因此文档始终与您的工作区保持一致且准确。
+
+## 批量操作
+
+REST 和 GraphQL 均支持批量操作：
+
+* **批量大小**：每个请求最多60条记录
+* **操作**：创建、更新、删除多条记录
+
+**仅 GraphQL 功能：**
+
+* **批量 Upsert**：在一次调用中创建或更新
+* 使用复数对象名称（例如，用 `CreateCompanies` 而不是 `CreateCompany`）
+
+## 速率限制
+
+为确保平台稳定性，API 请求将受到限流：
+
+| 限制       | 值           |
+| -------- | ----------- |
+| **请求**   | 每分钟 100 次调用 |
+| **批量大小** | 每次调用 60 条记录 |
+
+<Tip>
+使用批量操作以最大化吞吐量 — 在一次 API 调用中处理最多 60 条记录，而不是发起单独的请求。
+</Tip>

packages/twenty-docs/l/zh/developers/extend/capabilities/webhooks.mdx

@@ -0,0 +1,112 @@
+---
+title: Webhooks
+description: 当您的 CRM 中发生事件时接收实时通知。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+当 Twenty 中发生事件时，Webhook 会实时将数据推送到您的系统 — 无需轮询。 使用它们来保持外部系统同步、触发自动化或发送警报。
+
+## 创建 Webhook
+
+1. 前往 **设置 → APIs & Webhooks → Webhooks**
+2. 单击 **+ 创建 Webhook**
+3. 输入您的 Webhook URL（必须可公开访问）
+4. 单击 **保存**
+
+Webhook 会立即激活并开始发送通知。
+
+<VimeoEmbed videoId="928786708" title="创建 Webhook" />
+
+### 管理 Webhooks
+
+**编辑**：点击该 Webhook → 更新 URL → **保存**
+
+**删除**：点击该 Webhook → **删除** → 确认
+
+## 事件
+
+Twenty 会针对以下事件类型发送 Webhook：
+
+| 事件        | 示例                                                         |
+| --------- | ---------------------------------------------------------- |
+| **记录已创建** | `person.created`, `company.created`, `note.created`        |
+| **记录已更新** | `person.updated`, `company.updated`, `opportunity.updated` |
+| **记录已删除** | `person.deleted`, `company.deleted`                        |
+
+所有事件类型都会发送到您的 Webhook URL。 事件过滤可能会在未来的版本中添加。
+
+## 负载格式
+
+每个 Webhook 都会发送一个带有 JSON 正文的 HTTP POST：
+
+```json
+{
+  "event": "person.created",
+  "data": {
+    "id": "abc12345",
+    "firstName": "Alice",
+    "lastName": "Doe",
+    "email": "alice@example.com",
+    "createdAt": "2025-02-10T15:30:45Z",
+    "createdBy": "user_123"
+  },
+  "timestamp": "2025-02-10T15:30:50Z"
+}
+```
+
+| 字段    | 描述                         |
+| ----- | -------------------------- |
+| `事件`  | 发生了什么（例如，`person.created`） |
+| `数据`  | 已创建/更新/删除的完整记录             |
+| `时间戳` | 事件发生的时间（UTC）               |
+
+<Note>
+请返回 **2xx HTTP 状态**（200-299）以确认已接收。 非 2xx 的响应将被记录为投递失败。
+</Note>
+
+## Webhook 验证
+
+为了安全起见，Twenty 会对每个 Webhook 请求进行签名。 请验证签名以确保请求真实有效。
+
+### Headers
+
+| 标题                           | 描述             |
+| ---------------------------- | -------------- |
+| `X-Twenty-Webhook-Signature` | HMAC SHA256 签名 |
+| `X-Twenty-Webhook-Timestamp` | 请求时间戳          |
+
+### 验证步骤
+
+1. 从 `X-Twenty-Webhook-Timestamp` 获取时间戳
+2. 构造字符串：`{timestamp}:{JSON payload}`
+3. 使用您的 Webhook 密钥计算 HMAC SHA256
+4. 与 `X-Twenty-Webhook-Signature` 进行比较
+
+### 示例（Node.js）
+
+```javascript
+const crypto = require("crypto");
+
+const timestamp = req.headers["x-twenty-webhook-timestamp"];
+const payload = JSON.stringify(req.body);
+const secret = "your-webhook-secret";
+
+const stringToSign = `${timestamp}:${payload}`;
+const expectedSignature = crypto
+  .createHmac("sha256", secret)
+  .update(stringToSign)
+  .digest("hex");
+
+const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
+```
+
+## Webhooks 与工作流
+
+| 方法                  | 方向  | 用例                   |
+| ------------------- | --- | -------------------- |
+| **Webhooks**        | OUT | 自动通知外部系统任何记录变更       |
+| **工作流 + HTTP 请求**   | OUT | 使用自定义逻辑（过滤、转换）向外发送数据 |
+| **工作流 Webhook 触发器** | IN  | 从外部系统接收数据到 Twenty    |
+
+如需接收外部数据，请参见 [设置 Webhook 触发器](/l/zh/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger)。