API 概览

每个 RolChat REST 端点都遵循同一套约定：相同的基础 URL、相同的响应封装、相同的分页方式、相同的错误结构。只需学习一次，端点参考中的每个端点系列读起来都一样。

基础 URL 和版本控制

https://api.rolchat.com/api/v1/

版本号位于路径中。添加可选字段、新端点或带默认值的新查询参数不属于破坏性变更，不会提升版本。破坏性变更会以 v2 发布，已弃用的 v1 端点在公布后至少继续工作六个月（参见弃用）。

身份验证

方式	标头	用途
JWT 持有者令牌	`Authorization: Bearer <access_token>`	交互式会话（网页应用、移动应用）
API 密钥	`Authorization: Bearer rcp_<secret>`	机器之间的调用、插件 API 密钥
HMAC 签名	`X-RolChat-Signature: sha256=…`	来自您系统的入站 Webhook，请参阅 Webhook
无	-	公开的小组件端点（`/widget/…`、`/forms/…`），按站点和来源限定范围

集成请使用 API 密钥（个人访问令牌）。密钥在 设置 → 插件 → RolChat API 密钥 中创建，只显示一次，并且仅以哈希形式存储。密钥的权限永远不会超过创建它的成员：每次调用时都会根据该成员当前的权限检查其作用域。有关 JWT 有效期、X-Account-Id 标头和多公司会话，请参阅身份验证。

响应封装

单个资源：

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

列表：

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

没有正文的响应（删除后的 204 No Content）仍会带有 X-Request-Id 标头。

错误：

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code 是机器可读的 snake_case 值，也是用于分支判断的值；message 为英文，供日志使用。field 和 details 在有帮助时出现，且绝不包含个人数据。API 绝不会在返回 200 的同时附带 errors 数组：只要存在错误，状态码就是 400 或更高。完整的代码列表见错误页面。

分页

可能不断增长的列表端点使用游标分页。请求第一页时不带游标，之后原样传回收到的 next_cursor：

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

limit 默认为 50，上限为 200；更大的值会以 400 validation_failed 被拒绝。
游标是不透明的，24 小时后过期（400 validation_failed，附带 code: cursor_expired）。
结果与第一页时获取的快照保持一致：在两次翻页之间删除的记录会消失，新记录只有在您不带游标重新开始时才会出现。
还会为偏好这种方式的客户端发送带有 rel="next" 和 rel="prev" 的 Link 标头。

幂等性

在任何 POST、PATCH 或 DELETE 请求中发送 Idempotency-Key 标头（UUID 或 ULID，最多 255 个字符）：

带有某个键的第一个请求会被执行，其状态和正文会保存 24 小时。
使用相同的键且正文相同的重复请求会返回已保存的响应，而不会再次产生副作用。
使用相同的键但正文不同的重复请求会以 409 idempotency_key_conflict 被拒绝。

对每个会产生副作用的创建操作都应使用它：发送消息、电子邮件或 SMS，拨打电话，以及任何会计费的操作。GET 请求始终是幂等的，会忽略该标头。

速率限制

限制按分钟计数，按账户、API 密钥或用户计算（无需登录的路由按 IP 地址计算）。默认上限：

类别	默认限制	每分钟
无需登录的请求（按 IP）	60	每个 IP
已登录用户（控制台）	1 000	每个用户
API 密钥	1 000	每个密钥
公开小组件端点	每位访客 60，每个网络地址 600	每分钟
登录（`/auth/login`）	5	每个 IP
入站 Webhook	300	每分钟
MCP 服务器	600	每分钟
OAuth 端点	600	每分钟

这些上限是平台默认值，运营方可以调整；您的套餐不会将其放大，Enterprise 的限制在合同中约定。受速率限制的端点会返回：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

超过限制时，响应为 429，errors 数组中带有 code: rate_limited，并附带以秒为单位的 Retry-After 标头。请等待该时长后再发起下一次调用。登录失败十次会将账户锁定 30 分钟。

大小和超时

类别	请求正文上限	服务器超时
默认	1 MB	30 秒
带附件的消息	25 MB	30 秒
CSV 导入	50 MB	返回 `202` 并在后台运行
知识库图片	10 MB	30 秒
批量 API	10 MB	30 秒
搜索	1 MB	10 秒
AI 请求	1 MB	60 秒
小组件端点	100 KB	30 秒

超出大小的正文会得到 413 payload_too_large。上游超时时会返回 504，附带 code: upstream_timeout，并在重试可能有帮助时提供 retry_after 提示。

内容类型、日期和 ID

请求和响应为 application/json; charset=utf-8。文件上传使用 multipart/form-data；CSV 导出返回 text/csv。无效的 UTF-8 会以 400 validation_failed 被拒绝。
时间戳为 UTC 的 ISO-8601 格式，精确到毫秒：2026-04-20T14:23:45.123Z。输入时接受任意 ISO-8601 时区偏移，并规范化为 UTC。
标识符是不透明的 ULID 或 UUID。没有数字 ID，电子邮件地址或电话号码绝不会出现在 URL 中。

租户隔离和权限

每个经过身份验证的请求都在一个账户内运行。属于其他账户的资源，或属于调用者角色未涵盖站点的资源，会返回 404 not_found 而不是 403，从而绝不泄露记录是否存在。缺少所需权限（例如 contacts.delete）的有效令牌会返回 403 forbidden。部分权限带有范围后缀（conversations.read:own、:team、:all），用于缩小列表返回的内容。

PATCH 只接受可写字段。id、account_id、created_at、updated_at 以及 resolved_at 等状态字段是只读的；发送这些字段会返回 400 validation_failed，并附带 details.forbidden_fields。状态变更通过专门的操作进行，例如 POST /tickets/:id/resolve。

每次写入都会记录在账户审计日志中。

可观测性标头

每个响应都带有：

X-Request-Id: req_01HK…

请记录 X-Request-Id。这是支持团队首先会询问的内容。

CORS

浏览器仪表板的来源是 https://app.rolchat.com。公开小组件端点允许任意来源，或仅允许您为站点验证过的来源。使用 API 密钥进行的服务器之间调用不受 CORS 约束。

弃用

变更会在更新日志中公布，受影响的端点开始发送 Deprecation: true 以及带有移除日期的 Sunset 标头。
公开端点在公布后至少继续工作六个月。
移除只会在新的主版本中进行。在 v1 内的变更只做增量添加。

健康检查

每个服务都公开 /healthz（存活）和 /readyz（就绪）。