快速开始

本教程使用生产 API。密钥只应保存在你控制的服务器或插件服务端配置中。不要写入网页 JavaScript、客户端模组、公开仓库或日志。

1. 创建密钥

打开个人中心，切换到 API & Webhooks → 生成密钥。

名称：建议填写应用和部署用途，如“生存服查端机器人”。
授权归属：选择“个人”或一个你实际担任管理员的有效组织。
权限：仅勾选应用需要的权限。
有效期：选择“指定天数”（1–365 天，默认 90 天）或“永久有效”；个人和组织密钥都支持。
生成：登录后点击“生成并显示密钥”，无需再次输入账户密码或两步验证码。

完整密钥只在创建成功时显示一次。丢失后只能撤销并重新生成。

永久密钥的 /v1/me 响应中 expires_at 为 null，表示没有自动到期时间。撤销、账号停用、密码变更和组织授权失效仍会使密钥失效，调用也仍受同样的频率与总量限制。此设置不会延长一次性邀请链接的 7 天有效期。

2. 设置环境变量

以下命令中的值是占位符。请通过自己的密钥管理系统安全注入实际密钥。

export SCREENSHARE_API_KEY='YOUR_SERVER_SIDE_API_KEY'
export SCREENSHARE_PARTNER_ID='YOUR_PARTNER_ID'

PowerShell 对应使用 $env:SCREENSHARE_API_KEY 和 $env:SCREENSHARE_PARTNER_ID。不要在共享终端或可记录输入的演示环境粘贴生产密钥。

3. 检查凭证

curl --fail-with-body https://api.screenshare.cn/v1/me \
  -H "Authorization: Bearer $SCREENSHARE_API_KEY"

成功响应示例：

{
  "ok": true,
  "data": {
    "key_id": "11111111-1111-4111-8111-111111111111",
    "account_id": "22222222-2222-4222-8222-222222222222",
    "partner_id": "33333333-3333-4333-8333-333333333333",
    "scopes": ["invitations:write", "invitations:read", "tickets:read"],
    "expires_at": "2026-12-24T00:00:00.000Z"
  },
  "request_id": "req_44444444-4444-4444-8444-444444444444"
}

启动时检查 partner_id 是否等于服务端配置，检查所需权限是否包含在 scopes 中。不匹配时停止该组织的调用，并交由管理员更新配置。

4. 生成一个邀请

请为每次业务上的新邀请生成新的随机请求编号，并把它连同组织 ID 和请求正文持久化。网络超时或服务返回 5xx 后，使用原编号、原密钥和原正文重试。

curl --fail-with-body -X POST \
  "https://api.screenshare.cn/v1/partners/$SCREENSHARE_PARTNER_ID/invitations" \
  -H "Authorization: Bearer $SCREENSHARE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 74e123d0-53f0-47dd-a2ef-678513162c44' \
  --data '{"game":"minecraft","notes":"请配合本次服务器查端。"}'

成功响应中的 data.link 是发给玩家的完整邀请地址。必须保留 #token=... 部分；不要把这个链接写入公共日志。保存 data.id 作为邀请 ID。

5. 让玩家自行完成认领

玩家打开链接、填写游戏 ID、联系方式、远程信息及所需备注后加入。预览链接不占用名额。第一个完整提交成功的浏览器获得会话凭证；不能用 API 代替玩家认领。

收到 invitation.joined 通知后，用事件里的 invitation_id 查询工单进度。查端记录生成后，处理 record.created 并读取记录详情。

在本地先验证集成

仓库中的本地模拟服务提供合成数据，可验证请求和错误分支。它不代表生产认证，也不会创建真实工单。当前没有生产 test key 或独立沙箱域名；实际调用生成邀请会创建真实的组织邀请，但不会因此扣除查端次数。