# 快速开始

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

## 1. 创建密钥

打开 [个人中心](https://www.screenshare.cn/profile)，切换到 **API & Webhooks → 生成密钥**。

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

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

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

## 2. 设置环境变量

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

```bash
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. 检查凭证

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

成功响应示例：

```json
{
  "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 后，使用**原编号、原密钥和原正文**重试。

```bash
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` 查询 [工单进度](/tickets/)。查端记录生成后，处理 `record.created` 并读取记录详情。

## 在本地先验证集成

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