API 集成

API 集成的技术规范。

1. Base URL

您的端点 URL 显示在端点详情页上。

POST

https://api.chikage.io/api/v1/data/{slug}

GET / PUT / DELETE

https://api.chikage.io/api/v1/data/{slug}/{record_id}

2. 身份认证

在请求头中包含您的 API 密钥。

请求头	描述	是否必填
Authorization	`Bearer tm_test_xxx...` / `Bearer tm_live_xxx...`	Yes
Content-Type	`application/json`	Yes
X-Webhook-Callback	Webhook URL	No
X-Webhook-Auth	认证值（例如 Bearer token）	No
X-Webhook-Auth-Header	认证头名称	No

3. 请求格式

Content-Type: 仅支持 application/json
最大大小: 每次请求 100KB
方法: POST / GET / PUT / DELETE

CRUD 端点

每个端点自动支持四种 HTTP 方法：

方法	路径	描述
`POST`	`/api/v1/data/{slug}`	创建新记录（异步，加入队列）
`GET`	`/api/v1/data/{slug}/{record_id}`	按 ID 查询记录
`PUT`	`/api/v1/data/{slug}/{record_id}`	按 ID 替换记录（异步，加入队列）
`DELETE`	`/api/v1/data/{slug}/{record_id}`	按 ID 删除记录（异步，加入队列）

GET、PUT、DELETE 需要使用之前 POST 响应中返回的记录 ID。

POST — 创建:

curl -X POST https://api.chikage.io/api/v1/data/{slug} \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true
}'

GET — 读取:

curl https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

PUT — 更新:

curl -X PUT https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 50000,
  "items": ["Item A", "Item B", "Item C"],
  "paid": true
}'

DELETE — 删除:

curl -X DELETE https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

4. 响应格式

成功响应 (202):

{
  "success": true,
  "id": "rec_abc123",
  "message": "Request queued"
}

错误响应示例 (400):

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "order_id", "error": "Required field is missing" }
  ]
}

错误响应:

Code	Status	Description
`400`	请求错误	无效的 JSON 或缺少必填字段
`401`	未授权	缺少或无效的 API 密钥，或 API 密钥已被所有者停用
`403`	禁止访问	端点未激活或订阅已过期
`415`	不支持的媒体类型	Content-Type 必须为 application/json
`429`	请求过多	月度请求限额已用完
`5xx`	服务器错误	内部服务器错误（500、502、503 等）

5. 协作者 Webhook

API 协作者可以直接接收处理结果。

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

6. 测试工具

上线前在沙盒中测试。

内置测试页面: 在端点详情页点击测试按钮即可访问 — 无需额外工具
cURL: 从命令行测试
Postman: 使用 API 测试工具

7. 生产控制台

部署到生产环境后，端点所有者可以直接从仪表盘管理生产数据 — 无需外部 API 工具或代码。

访问方式

前往端点详情 → 生产标签页 → 点击"打开控制台"在新标签页打开。

功能

完整 CRUD 支持（POST / GET / PUT / DELETE）操作生产数据
生产环境 API 密钥已自动配置 — 无需手动输入
控制台的请求不会触发 Webhook

仅限所有者

只有端点所有者可以访问生产控制台。协作者无法使用。