核心概念
深入了解快速入门中介绍的术语。
1. API
用于程序之间交换数据的通信协议。
在 3Min API 中：
- 无需后端代码即可创建 API
- 接收标准 JSON 数据
- 数据自动存储，可通过 Webhook 转发
2. 端点
接收数据的 API 地址。一个 API = 一个端点。
每个端点包含：
- 唯一 URL 路径（自动生成）
- 必填字段（可选）
- 沙盒/生产环境隔离
- 各环境独立的 API 密钥 (
tm_test_xxx...,tm_live_xxx...)
3. JSON
3Min API 接受标准 JSON 数据。
支持的字段类型：
| String | 文本 | Example |
|---|---|---|
| string | 文本 | "hello" |
| number | 数字 | 123, 45.67 |
| boolean | 真/假 | true, false |
| array | 列表 | [1, 2, 3] |
| object | 嵌套数据 | {"key": "value"} |
示例（订单信息）：
{
"order_id": "ORD-2024-001",
"amount": 45000,
"items": ["Item A", "Item B"],
"paid": true,
"customer": {
"name": "John Doe",
"phone": "010-1234-5678"
}
}4. 必填字段（可选）
即使不定义必填字段，也可接受标准 JSON。
您可以指定 JSON 数据中必须包含的字段。
设置必填字段后：
- 缺少必填字段的请求将被拒绝（400 错误）
- 确保数据质量
5. 沙盒 vs 生产环境
| 环境 | API 密钥 | 用途 |
|---|---|---|
| 沙盒 | tm_test_xxx... | 开发和测试 |
| 生产 | tm_live_xxx... | 正式服务 |
- 环境由 API 密钥前缀决定
- 每个环境可单独配置 Webhook
- 部署到生产环境前请在沙盒中充分测试
6. API 密钥
调用端点时用于身份认证。所有者的默认 API 密钥在创建端点时自动生成，不可删除。如密钥泄露，可重新生成。
| API 密钥 | 环境 | 用途 |
|---|---|---|
tm_test_xxx... | 沙盒 | 用于测试，不影响生产环境 |
tm_live_xxx... | 生产 | 用于正式服务，处理真实数据 |
API 密钥泄露时请立即重新生成。
协作密钥
创建协作密钥并邀请协作者，按协作密钥分别管理日志和统计数据。
按协作密钥筛选日志，跟踪每个协作密钥的使用情况。
为每个协作密钥设置允许的操作（POST/GET/PUT/DELETE），每个环境独立配置。读取（GET）权限同时适用于单条、列表、搜索查询。
7. Webhook
数据到达时自动发送通知到指定 URL。
两种类型的 Webhook：
| Webhook | 配置位置 | 描述 |
|---|---|---|
| 所有者 Webhook | 仪表盘 → API → 端点详情 | 接收所有 API 调用通知 |
| 协作者 Webhook | 调用 API 时的请求头 | 协作者直接接收处理结果 |
重试策略：请在 15 秒内返回 2xx。失败后从队列以小时级间隔重试
注意：即使所有 Webhook 重试均失败，您的数据仍会安全存储。请在日志中查看 Webhook 状态。
8. 轮询
接收数据的另一种方式。不是由我们调用您的 URL，而是您的客户端循环调用轮询端点，只取回上次调用之后到达的记录。
Webhook 与轮询对比：
| 对比项 | Webhook（推送） | 轮询（拉取） |
|---|---|---|
| 由谁发起 | 3Min API 调用您 | 您的客户端调用我们 |
| 前提条件 | 一个能在 15 秒内响应的公网 URL | 无需任何入站连接，只要能发出 HTTPS 请求 |
| 延迟 | 记录存储后数秒 | 一个轮询周期，再加约 60 秒的沉淀延迟 |
| 费用 | 免费——投递不计入 API 调用 | 每次轮询请求计一次 API 调用，空响应也计 |
如果接收方有公网 URL，并且需要在数据到达时立即响应，请选 Webhook。这是默认选择。
如果没有公网 URL——本地开发、内网、防火墙之后、没有常驻服务器——或者接收方需要自己控制节奏，请选轮询。
两者并不互斥。同一个端点可以同时开启：用 Webhook 做实时响应，再用每晚一次的轮询补齐接收方漏掉的记录。
请求示例：
# First call - since a point in time
GET /api/v1/data/my-endpoint/poll?since=2026-09-01
Authorization: Bearer tm_test_xxx
# Response - oldest first
{
"success": true,
"data": [ ... ],
"pagination": {
"limit": 100,
"poll_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ"
}
}
# Next call - send the cursor back
GET /api/v1/data/my-endpoint/poll?cursor=eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ游标的工作方式：
- 首次调用可以带 since（RFC 3339 或 YYYY-MM-DD，一律按 UTC 解析），也可以什么都不带，那就表示从此刻开始订阅。since 与 cursor 不能同时发送。
- next_cursor 表示还有积压——请立即再次调用
- poll_cursor 表示已经追平——保存它，等到下一个周期
- 记录按从旧到新返回，每页最多 100 条（limit，1-100）。每次响应只会包含两个游标中的一个
最近 60 秒左右的记录会在队列追平之前暂时保留，因此只是推迟到之后的轮询，而不是被跳过。重试和重启可能重复投递同一条记录，请按记录 id 做幂等处理。
9. 数据保留
记录只保留有限的时间。请把 Webhook 或轮询端点——而不是仪表盘——当作数据离开 3Min API 的通道。
各环境策略：
| 环境 | 策略 | 备注 |
|---|---|---|
| 生产（付费套餐） | 至少保留 60 天 | 超过保留期后按月整批删除 |
| 沙盒（付费套餐） | 30 天后自动删除 | 用于测试，不是存储 |
| 免费套餐 | 端点创建 7 天后全部删除 | 按端点删除 |
如何导出数据：
- Webhook：记录一到达就推送到您指定的 URL
- 轮询：自行拉取上次调用之后到达的记录——参见上面第 8 节
- 日志：在保留期内可在仪表盘查看或搜索单条记录
- 使用统计单独保存，不随记录删除，仪表盘图表保持完整