# REST API 接入指南

Arkme REST API 面向服务端、脚本和桌面程序。接口使用 HTTP + JSON，通过个人 API Key 读取 Key 所属用户的数据。

| 参数 | 值 |
| --- | --- |
| API 地址 | `https://openapi.jotmo.cc` |
| 认证 | `Authorization: Bearer arkme_...` |
| 机器合同 | [OpenAPI 3.1](v1/openapi.yaml) |

先在 [开发者控制台](/console) 创建 Key。不要把 Key 写入浏览器前端代码、URL、日志或公开仓库。

## Web 页面接入

公开 Web 页面通过开发者自己的 Backend 或 BFF 调用 Arkme REST API。API Key 保存在服务端 Secret 中，浏览器只访问开发者自己的业务接口。

## 获取当前用户资料

```bash
curl -X POST 'https://openapi.jotmo.cc/api/v1/profile/get' \
  -H 'Authorization: Bearer arkme_<key-id>_<secret>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

成功响应：

```json
{
  "code": 200,
  "message": "请求成功",
  "request_id": "...",
  "data": {
    "nickname": "小明",
    "jotmo_id": "xiaoming",
    "created_at": 1700000000000
  }
}
```

## 获取账号绑定状态

```bash
curl -X POST 'https://openapi.jotmo.cc/api/v1/account-bindings/get' \
  -H 'Authorization: Bearer arkme_<key-id>_<secret>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

`data.items` 按 `phone`、`email`、`wechat`、`apple`、`google`、`huawei` 的固定顺序返回。每一项只包含 `provider` 和 `bound`，不返回手机号、邮箱或第三方账号标识。

## 错误处理

- `400`：请求体或参数不合法。
- `401`：API Key 缺失、无效、已删除，或所属账号不可用。
- `429`：调用过快；按 `Retry-After` 等待后进行有上限的重试。
- `502`：账号服务暂时不可用。
- `503`：开放平台存储或限流依赖暂时不可用。

请求体不得包含 `user_id`。删除 Key 后，后续请求会立即返回 `401`。