测试与集成指南
概述
这是在端点详情页点击立即测试后打开的页面。您可以直接在浏览器中测试 API 调用，无需任何额外工具，还可以与协作者分享，让他们在一个地方找到集成所需的所有信息。
此页面的测试仅在沙盒环境中进行。不会影响生产环境数据，请放心试验。
页面有两个标签页：
- 快速开始 — 使用 API 密钥认证并立即测试调用
- 指南 — 面向所有者和协作者的集成参考（分步指南、API 端点、头信息、字段定义、代码示例等）
如何进入
- 端点详情右侧边栏 > 立即测试 按钮（沙盒环境标签页）
- 协作者接受邀请后也可以从自己的仪表盘访问
端点信息
- 显示端点名称和描述
- 旁边显示环境标签（沙盒环境）和版本信息
- 在 快速开始 / 指南 标签页之间切换
快速开始标签页
认证
要开始测试，需要先使用 API 密钥进行认证。
认证后，输入框消失，显示 退出 按钮。要使用其他密钥测试，先退出再重新认证。
试一试
认证后，CRUD 调用执行区域被激活。选择方法，输入请求体（JSON），点击 Execute 即可立即看到结果。
如果想一次性测试完整流程，请按以下顺序进行：
完整 CRUD 测试指南
CREATE (POST) — 在请求体中输入测试 JSON 并执行。从响应中复制
id——后续步骤需要用到。READ (GET) — 将
id粘贴到 Record ID 字段并执行。验证刚创建的数据是否正确返回。UPDATE (PUT) — 输入相同的
id，并在请求体中提供修改后的 JSON。这是完全替换，所以要保留的字段和要更改的字段都需要包含。DELETE — 输入相同的
id并执行。之后再试一次 READ，确认记录已被删除。
权限检查：使用协作密钥测试时，只能执行该密钥权限允许的方法。调用未授权的方法返回 403 错误。请在协作密钥 > 权限中查看权限。
协作者 Webhook
试一试区域底部有一个可折叠的 Webhook 设置区域。这与所有者在仪表盘配置的 Webhook 不同——它是让 API 调用者在请求头中包含 Webhook 信息，以便在指定的 URL 接收处理结果。您可以在此测试这些头信息。
- 与所有者 Webhook 独立运行
- 在实际集成中，Webhook 头信息直接包含在 API 调用代码中
- 详细的头名称和实现方法请参阅指南标签页的 Webhook 设置部分
指南标签页
指南标签页的结构让所有者和协作者都可以在一个地方查看完整的集成流程和技术细节。顶部是角色专属的分步指南，下方是技术参考。
入门 — 所有者
选择 我创建了端点 标签页，从所有者的视角查看步骤。
- 创建端点 — 只需设置 API 名称，CRUD 自动创建。描述和必填字段可以稍后添加
- 沙盒环境测试和日志检查 — 在快速开始标签页使用默认 API 密钥发起调用，然后在仪表盘日志中验证数据接收
- 创建协作密钥并邀请 — 在详情页创建密钥并发送邮件邀请
- 集成测试 — 通过日志共同验证协作者在沙盒环境中的调用是否正确
- 生产环境部署 — 批准协作者的部署请求，或直接部署。部署后协作者会收到通知
入门 — 协作者
选择 我被邀请了 标签页，从协作者的视角查看步骤。
- 接受邀请 — 查看邀请邮件，登录后在仪表盘上接受
- 查看 API 密钥 — 在端点详情页找到您的沙盒环境 API 密钥（
tm_test_） - 集成和测试 — 在快速开始标签页测试调用，参考指南标签页的技术信息进行开发。如果收到 202 响应，说明系统保证处理
- 请求部署 — 测试完成后，在端点详情页提交部署请求
- 切换到生产环境 — 所有者完成部署后您会收到通知。从生产环境标签页查看并应用生产环境 API 密钥（
tm_live_）
API 端点
显示该端点可用的 API 路径和方法。创建端点时自动准备四种方法。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/data/{slug} |
创建新记录 |
| GET | /api/v1/data/{slug}/{record_id} |
获取记录 |
| PUT | /api/v1/data/{slug}/{record_id} |
替换记录 |
| DELETE | /api/v1/data/{slug}/{record_id} |
删除记录 |
{slug} 是端点创建时自动分配的唯一标识符。您可以在此页面查看实际值。
API 密钥
API 调用认证所需的密钥信息。
| 环境 | 密钥前缀 | 用途 |
|---|---|---|
| 沙盒环境 | tm_test_ |
开发和测试 |
| 生产环境 | tm_live_ |
正式服务 |
生产环境 API 密钥可在部署完成后在端点详情页找到。部署前，使用生产环境密钥的调用将被拒绝。
请求头
API 调用中需要包含的 HTTP 头信息。Content-Type 和 Authorization 为必需；Webhook 头仅在需要时添加。
| 头信息 | 是否必需 | 说明 |
|---|---|---|
Content-Type |
必需 | application/json（用于 POST/PUT） |
Authorization |
必需 | Bearer {API_KEY} 格式 |
X-Webhook-Callback |
可选 | 接收调用者 Webhook 的 URL |
X-Webhook-Auth |
可选 | Webhook 认证值（例如 Bearer token） |
X-Webhook-Auth-Header |
可选 | Webhook 认证头键（默认：Authorization） |
请求体
关于 POST/PUT 请求发送的 JSON 请求体的信息。
- 格式：JSON（
application/json）· 最大 100KB · UTF-8 - 如果所有者定义了必填字段，这些字段必须包含。必填字段以外的额外字段可以自由发送
- 如果未定义必填字段，任何 JSON 都可接受
- 请求异步处理。您会立即收到 202 响应，实际存储和 Webhook 发送在后台进行
响应格式
显示各方法的成功响应和错误代码。
成功响应：
- POST/PUT/DELETE →
202 Accepted（请求已接受并加入队列） - GET →
200 OK（数据立即返回）
错误代码：
| 代码 | 状态 | 含义 |
|---|---|---|
| 400 | Bad Request | 无效 JSON、缺少必填字段、无效记录 ID |
| 401 | Unauthorized | API 密钥缺失或无效 |
| 403 | Forbidden | 端点未激活、无订阅或权限不足 |
| 415 | Unsupported Media Type | Content-Type 不是 application/json |
| 429 | Too Many Requests | 月度使用量超出限额 |
| 5xx | Server Error | 临时服务器错误——请实现重试逻辑 |
如果收到 5xx 错误，请求未到达服务器。请在代码中实现重试逻辑（例如 1 秒 → 2 秒 → 4 秒退避）。如果收到 202 响应，系统保证处理。
Webhook 设置
设置调用者 Webhook 以自动接收处理结果的说明。与所有者在仪表盘配置的 Webhook 独立运行。
设置方法：在 API 调用中包含以下头信息。
| 头信息 | 是否必需 | 说明 |
|---|---|---|
X-Webhook-Callback |
必需 | 接收 Webhook 的 URL |
X-Webhook-Auth |
可选 | 认证值（例如 Bearer token） |
X-Webhook-Auth-Header |
可选 | 认证头键（默认：Authorization） |
重试策略：
- 失败后最多重试 3 次（1-2 秒退避）
- 成功标准：2xx 状态码
- 即使 3 次尝试全部失败，数据仍安全存储。在日志中查看 Webhook 状态
代码示例
提供包括 curl、JavaScript 和 Python 在内的主要语言的 API 调用代码示例。切换标签页查看各语言的示例。实际端点 URL 和必需头信息已预填，可以直接复制使用。
常见问题
- 点击授权后没有反应：请检查 API 密钥是否以
tm_test_（沙盒环境密钥）开头。生产环境密钥（tm_live_）不能在此页面使用 - CREATE 后丢失了 ID：再次调用 CREATE 生成新记录继续测试。如果需要之前记录的 ID，请在仪表盘日志页面查看调用历史
- 收到 403 错误：您使用的协作密钥可能没有该方法的权限。请在协作密钥 > 权限中查看
- Webhook 未到达：Webhook 服务器必须在 7 秒内响应。请检查是否可公开访问且使用 HTTPS。Discord 和 Slack 等平台有速率限制——如果短时间内触发了过多 Webhook，部分可能会被拦截