核心概念

深入了解快速入门中介绍的术语。

1. API

用于程序之间交换数据的通信协议。

在 3Min API 中：

• 无需后端代码即可创建 API
• 接收标准 JSON 数据
• 数据自动存储，可通过 Webhook 转发

2. 端点

接收数据的 API 地址。一个 API = 一个端点。

每个端点包含：

• 唯一 URL 路径（自动生成）
• 必填字段（可选）
• 沙盒/生产环境隔离
• 各环境独立的 API 密钥 (tm_test_xxx..., tm_live_xxx...)

3. JSON

3Min API 接受标准 JSON 数据。

支持的字段类型：

示例（订单信息）：

{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true,
  "customer": {
    "name": "John Doe",
    "phone": "010-1234-5678"
  }
}

4. 必填字段（可选）

您可以指定 JSON 数据中必须包含的字段。

设置必填字段后：

• 缺少必填字段的请求将被拒绝（400 错误）
• 确保数据质量
• 字符串字段可设为可搜索，用于日志检索

5. 沙盒 vs 生产环境

• 环境由 API 密钥前缀决定
• 每个环境可单独配置 Webhook
• 部署到生产环境前请在沙盒中充分测试

6. API 密钥

调用端点时用于身份认证。所有者的默认 API 密钥在创建端点时自动生成，不可删除。如密钥泄露，可重新生成。

协作密钥

创建协作密钥并邀请协作者，按协作密钥分别管理日志和统计数据。

按协作密钥筛选日志，跟踪每个协作密钥的使用情况。

为每个协作密钥设置允许的操作（POST/GET/PUT/DELETE），每个环境独立配置。

7. Webhook

数据到达时自动发送通知到指定 URL。

两种类型的 Webhook：

重试策略：失败后最多重试3次（间隔60秒）

注意：即使所有 Webhook 重试均失败，您的数据仍会安全存储。请在日志中查看 Webhook 状态。

8. 事件通知（Discord / Slack / Telegram）

通过 Discord、Slack 或 Telegram 即时接收重要事件通知。

设置方式：仪表盘 → API → 端点详情 → 通知设置

支持的事件：

• Webhook 发送失败（仅通知受影响方）
• 月度用量达到80%警告（仅限所有者）
• 月度用量超出限制（仅限所有者）
• 新的部署请求（仅限所有者）
• 部署完成（仅限协作者）

注意：通知为尽力发送。发送失败不会重试，通知历史不会保存。

9. 数据归档

生产数据在30天后自动归档。归档记录的元数据（状态、时间戳、Webhook 结果等）被保留，而 Payload（正文数据）被转移到独立存储。

各环境策略：

归档后：

• 记录在日志列表中仍可见（元数据保留）
• Payload 搜索仅限最近30天
• 可通过"查看原始数据"查看单条记录的 Payload

归档下载：

• 位置：仪表盘 > 归档
• JSONL.gz：包含所有系统字段的完整记录（原始归档）
• CSV：仅 Payload 字段，递归展开（最大深度5），兼容 Excel（UTF-8 BOM）
• 每个文件包含一天的生产记录
• 仅限付费套餐