Screenshare请求与响应约定
地址与版本
所有业务接口位于 https://api.screenshare.cn/v1。不要调用主站或 Dashboard 的内部 /api/... 路径；它们使用网站会话或内部服务授权，不属于开放协议。
请求 JSON 使用 UTF-8 和 Content-Type: application/json。邀请正文最大 4096 字节（无 Content-Length 的流式正文也检查），读取期限为 5 秒；不接受压缩正文。撤销邀请不发送请求体。路径最多 512 字符，查询字符串最多 2048 字符。仅使用已公开参数，不重复传入同名参数，不在 URL 传递凭证。
当前服务端接口面向服务端集成，不提供跨域浏览器调用；不要在前端暴露 API Key 来绕过这一边界。
响应信封
{"ok":true,"data":{"example":"value"},"request_id":"req_UUID"}
{"ok":false,"error":{"code":"INSUFFICIENT_SCOPE","message":"需要 records:read 权限。"},"request_id":"req_UUID"}
根据 HTTP 状态和 error.code 编写逻辑，message 供人阅读。每个 API 响应都包含 X-Request-Id；请求支持时请提供此编号。响应使用 Cache-Control: no-store，客户端不要把受组织权限保护的响应放进共享缓存。
时间采用 ISO 8601，正常输出 UTC Z。所有 ID 都应视为不透明字符串；不要推断时间、顺序或权限。只有公开查端记录的 uuid 使用明确的 USS 格式。
分页
- 组织记录使用
limit（1–100，默认 20）和cursor。按updated_at、id升序返回；next_cursor为null时结束。 - 邀请与工单列表使用
page（1–10000，默认 1），每页 20 条，返回page_count。 - 翻页期间保持相同筛选条件。记录列表是实时视图，不是冻结快照；并发修改可能令条目移动。客户端按记录 ID 去重，并用重叠时间窗口同步。
- 邀请列表以创建时间倒序，新邀请可能导致页面移动。完整同步时按邀请 ID 去重。
限流
| 范围 | 限制 |
|---|---|
| 每把有效 API Key | 60 次/分钟，5,000 次/天 |
| 同一创建账号的所有 API Key | 300 次/分钟，20,000 次/天 |
| 同一组织的全部 API Key（包括不同管理员创建的密钥） | 300 次/分钟，20,000 次/天 |
| 创建邀请的请求（组织共享，包括幂等重试） | 10 次/分钟，60 次/小时，200 次/天 |
| 邀请及工单接口合计（组织共享，包括链接取回、撤销） | 60 次/分钟 |
| 邀请及工单接口正在处理的请求 | 每把密钥 2 个、每组织 4 个、每账号 6 个 |
| 来源 IP 的边缘保护（包括健康接口） | 约 30 次/10 秒，180 次/分钟 |
| 凭证的边缘保护（包括格式有效但不存在的凭证） | 约 20 次/10 秒，60 次/分钟 |
账号、密钥、组织的基础配额由共享数据库原子检查，跨边缘位置生效，不会因更换 IP 或增加密钥而重置。分钟、小时和日配额采用固定窗口；日配额在 UTC 00:00（北京时间 08:00） 重置。业务成功与失败请求都计入已通过的配额；某层拒绝后不再执行后续业务。创建邀请重试同样受限，不能通过不断更换幂等编号绕过限制。
边缘保护是按 Cloudflare 位置执行的近似计数，用于在数据库查询前拦截突发流量；不是全局精确配额。另有每边缘位置约 3,000 次/分钟的整体认证保护，降低大量不同凭证冲击数据库的风险。边缘阈值可能先于业务配额触发；生产限流设施不可用时返回 503 RATE_LIMIT_UNAVAILABLE，不会自动取消保护。
达到配额返回 429 RATE_LIMITED，同时处理太多工单请求则返回 429 CONCURRENCY_LIMITED。以响应中的 Retry-After 秒数 为准，不要固定等待 60 秒；日配额耗尽时可能需要等待至次日。并发限制通常返回 2 秒。收到 503 时也应遵守服务端给出的重试时间。
通过基础配额检查的响应携带以下请求时刻的快照；有并发调用时不保证后续仍有同样额度：
| 响应头 | 含义 |
|---|---|
X-RateLimit-Limit |
当前策略的窗口最大次数 |
X-RateLimit-Remaining |
本次检查后剩余次数 |
X-RateLimit-Reset |
窗口结束时间，Unix 秒 |
X-RateLimit-Policy |
正常为 key-minute；拒绝时说明触发策略，例如 organization-day、invitation-hour、ticket-concurrency |
Retry-After |
至少等待的秒数，仅需重试指导的响应提供 |
业务配额拒绝时，前三个头描述触发的配额。边缘或并发拒绝只保证提供策略名称及 Retry-After，可能没有额度数字。
客户端为每个组织安排共享任务队列，每把密钥同时最多发起 2 个工单请求。优先用 Webhook 同步；状态核对通常以 30–60 秒或更长间隔进行。429 后暂停对应组织/账号的任务，加入少量随机延迟后恢复；不要切换 IP、账号或密钥继续刷请求。
个人中心与 Webhook 操作
| 操作 | 共享限制 |
|---|---|
| 查看 API 设置或投递列表 | 每账号 30 次/分钟 |
| 配置修改（创建、验证、重发等） | 每账号 10 次/分钟、60 次/小时、200 次/天 |
| 撤销 API Key / 停用 Webhook | 独立的每账号 10 次/分钟，不受上述修改的小时和日配额阻挡 |
| 创建 API Key | 每账号 20 次/小时、50 次/天；最多 20 把未到期有效密钥 |
| 创建 Webhook | 每账号 5 次/小时、20 次/天；每账号及每组织最多 10 个未停用回调 |
| 验证或测试回调 | 同一回调 1 次/分钟；每账号 3 次/分钟、30 次/小时；每组织 60 次/小时 |
| 手动重发 | 同一回调 5 次/分钟；每账号 10 次/小时；每组织 20 次/小时；同一投递 3 次/天 |
个人中心还在会话及审计读取前执行来源 IP 边缘保护：约 30 次/10 秒、60 次/分钟。上述限制不会赋予原本没有的组织权限。
限流日志
正常进入业务处理的请求保留脱敏调用日志。已识别密钥的限流拒绝每把密钥每分钟最多保存一条样本，ID 以 rate_ 开头；边缘拦截和无效凭证不逐条写入业务数据库。个人中心调用统计因此不是被拦截流量的完整计费计数；平台 HTTP 429 指标用于观察整体拒绝量。这避免攻击者利用日志本身放大存储开销。
网络故障与幂等
GET 可以在网络错误、超时、429、502、503、504 时进行有限次数重试，使用退避和少量随机延迟。401/403 不应持续自动重试。
新建邀请要求 Idempotency-Key。其格式为 16–128 位 ASCII 字母、数字、_ 或 -，推荐随机 UUID。相同密钥、组织、编号和规范化正文再次提交返回同一邀请。正文变化返回 409 IDEMPOTENCY_CONFLICT。
首次创建返回 201；重放返回 200，data.replayed=true。请求编号不会因为邀请加入、撤销或到期而重新用于新邀请；需要新邀请时使用新编号。网络错误不代表服务器没有创建成功。
兼容性
同一 v1 版本可增加可选字段和新的错误码。忽略不认识的响应字段；处理未知枚举时采用保守分支。现有字段的含义或授权范围若发生不兼容变化，会通过版本更新说明。调用方不要把某次返回字段的排列顺序作为协议。