> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 数据开放 API

通过 API Key，从您自己的服务端按**推广链接**或**应用（APP）**查询访问数与安装数，支持区间合计与按天明细，便于接入自有的 BI、报表或投放系统。

|       |                                             |
| :---- | :------------------------------------------ |
| 接口地址  | `https://openapi.roibest.com/open/v1/stats` |
| 请求方式  | `GET`                                       |
| 鉴权方式  | 请求头 `X-Api-Key`                             |
| 响应格式  | JSON（UTF-8）                                 |
| 时区    | UTC+0                                       |
| 可查询范围 | 最近 90 天内，单次最长 30 天                          |

## 快速开始

1. 使用**主账号**登录 ROIBest 后台，点击右上角头像 →「开放 API」→「生成 API Key」，并完成邮箱验证。
2. API Key 明文仅在生成成功时展示一次，请立即复制或下载，妥善保存在服务端。
3. 在服务端发起第一次请求（将示例中的 ID 和 Key 替换为您自己的）：

```bash
curl -s 'https://openapi.roibest.com/open/v1/stats?promote_url_id=6347317793&start_date=2026-10-01&end_date=2026-10-07&group_by=day' \
  -H 'X-Api-Key: rbk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
```

## 鉴权

在每个请求的请求头中携带 API Key：

```
X-Api-Key: rbk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

- API Key 只能通过请求头传递，放在 URL 参数或请求体中均视为未携带。
- 仅主账号可以生成和管理 API Key，每个主账号同一时间仅有 1 把有效 Key。
- 在后台「重新生成」后，**旧 Key 立即失效**。请先准备好替换服务端配置，再执行重新生成。

::: warning 安全提示

API Key 仅限服务端使用，请勿写入网页、移动端 App 或公开的代码仓库。如怀疑泄露，请立即在后台重新生成。

:::

## 调用频率

每分钟最多 **10 次**请求。超出后返回 HTTP 429，请稍候再试。

::: tip 建议

- 需要逐日数据时，请使用 `group_by=day` 一次查询完整区间（最长 30 天），无需逐天调用。
- 需要查询多个推广链接或应用时，请分批、错峰调用。

:::

## 查询统计数据

```
GET https://openapi.roibest.com/open/v1/stats
```

### 请求参数

所有参数均通过 URL 参数（Query String）传递。

| 参数名            | 类型     | 是否必须 | 参考值        | 描述                        |
| :------------- | :----- | :--- | :--------- | :------------------------ |
| promote_url_id | string | 二选一  | 6347317793 | 推广链接 ID                   |
| app_id         | string | 二选一  | 1024       | 应用 ID                     |
| start_date     | string | 否    | 2026-10-01 | 开始日期，格式 `YYYY-MM-DD`，包含当天 |
| end_date       | string | 否    | 2026-10-07 | 结束日期，格式 `YYYY-MM-DD`，包含当天 |
| group_by       | string | 否    | day        | 不传：返回区间合计；传 `day`：返回逐日数据  |

查询规则：

- `promote_url_id` 与 `app_id` **必须且只能传其中一个**。
- 日期均按 UTC+0 计算，例如 `2026-10-01` 指 UTC 时间 `2026-10-01 00:00:00` 至 `23:59:59`。
- 开始、结束日期都不传时查询今天；只传其中一个时，仅查询该日。
- 结束日期不能晚于今天（UTC+0）。
- 单次查询区间最长 **30 天**（含开始、结束日期）。
- 仅支持查询**最近 90 天**内的数据：开始日期不能早于今天往前推 90 天。例如今天（UTC+0）为 11 月 6 日，最早可查询 8 月 8 日。
- 只能查询本账号下的推广链接和应用；已删除或已隐藏的同样可以查询，响应中通过 `deleted`、`hidden` 字段标识。

### 响应参数

| 参数名                  | 类型             | 描述                                             |
| :------------------- | :------------- | :--------------------------------------------- |
| code                 | int            | 业务码，`0` 表示成功                                   |
| msg                  | string         | 结果说明（英文），成功时为 `success`                        |
| request_id           | string         | 请求 ID，反馈问题时请提供                                 |
| data.promote_url_id  | string \| null | 按推广链接查询时为该 ID，否则为 `null`                       |
| data.app_id          | string \| null | 按应用查询时为该 ID，否则为 `null`                         |
| data.deleted         | bool           | 是否已删除                                          |
| data.hidden          | bool           | 是否已在后台隐藏                                       |
| data.metrics         | string\[]      | 本次返回的指标，当前为 `["visit", "install"]`             |
| data.timezone        | string         | 统计时区，固定为 `UTC`                                 |
| data.start_date      | string         | 本次查询的开始日期                                      |
| data.end_date        | string         | 本次查询的结束日期                                      |
| data.total           | object         | 不传 `group_by` 时返回，为区间内 `visit`、`install` 的合计   |
| data.rows            | array          | `group_by=day` 时返回，每天一条，按日期升序；无数据的日期同样返回，计数为 0 |
| data.rows\[].date    | string         | 日期 `YYYY-MM-DD`                                |
| data.rows\[].visit   | int            | 访问数                                            |
| data.rows\[].install | int            | 安装数                                            |

### 示例：查询区间合计

```
GET /open/v1/stats?promote_url_id=6347317793&start_date=2026-10-01&end_date=2026-10-02
```

```json
{
  "code": 0,
  "msg": "success",
  "request_id": "9f1c2e7a4b3d4c6e8a0b1c2d3e4f5a6b",
  "data": {
    "app_id": null,
    "promote_url_id": "6347317793",
    "deleted": false,
    "hidden": false,
    "timezone": "UTC",
    "metrics": ["visit", "install"],
    "start_date": "2026-10-01",
    "end_date": "2026-10-02",
    "total": { "visit": 180, "install": 21 }
  }
}
```

### 示例：按天查询

```
GET /open/v1/stats?app_id=1024&start_date=2026-10-01&end_date=2026-10-03&group_by=day
```

```json
{
  "code": 0,
  "msg": "success",
  "request_id": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "data": {
    "app_id": "1024",
    "promote_url_id": null,
    "deleted": false,
    "hidden": false,
    "timezone": "UTC",
    "metrics": ["visit", "install"],
    "start_date": "2026-10-01",
    "end_date": "2026-10-03",
    "rows": [
      { "date": "2026-10-01", "visit": 100, "install": 12 },
      { "date": "2026-10-02", "visit": 80, "install": 9 },
      { "date": "2026-10-03", "visit": 0, "install": 0 }
    ]
  }
}
```

## 指标说明

| 指标           | 说明                                     |
| :----------- | :------------------------------------- |
| 访问数（visit）   | 对应后台「推广链接 → 数据详情」中「广告访问」与「Chrome 访问」之和 |
| 安装数（install） | 对应后台「推广链接 → 数据详情」中的「安装」                |

- 两项指标均已过滤系统识别出的无效流量。
- 统计日期按 UTC+0 划分，当天数据为截至查询时刻的累计值。

## 错误码

请求失败时，HTTP 状态码与业务码同时返回（HTTP 429 除外），响应示例：

```json
{ "code": 40003, "msg": "date range must not exceed 30 days", "request_id": "9f1c2e7a4b3d4c6e8a0b1c2d3e4f5a6b" }
```

| HTTP 状态码 | 业务码   | 说明                                       | 处理建议                             |
| :------- | :---- | :--------------------------------------- | :------------------------------- |
| 400      | 40001 | `promote_url_id` / `app_id` 缺失、同时传入或格式错误 | 二者只传其一，且为纯数字                     |
| 400      | 40002 | 日期格式错误、开始日期晚于结束日期，或结束日期晚于今天              | 检查日期参数                           |
| 400      | 40003 | 查询区间超过 30 天                              | 拆分为多次查询                          |
| 400      | 40004 | 开始日期超出最近 90 天的可查询范围                      | 将开始日期调整到最近 90 天内                 |
| 400      | 40005 | `group_by` 取值错误                          | 不传，或传 `day`                      |
| 401      | 40101 | API Key 缺失、无效或已被重新生成                     | 检查请求头 `X-Api-Key`，确认使用的是最新的 Key  |
| 401      | 40102 | 账号未激活或受限                                 | 未激活请先完成账号激活，其他情况请联系客户经理          |
| 404      | 40401 | 推广链接或应用不存在，或不属于当前账号                      | 检查 ID 是否正确、是否属于当前账号              |
| 429      | —     | 超出调用频率限制                                 | 等待 1 分钟后重试，并降低调用频率               |
| 500      | 50001 | 服务内部错误                                   | 稍后重试；持续出现请携带 `request_id` 联系客户经理 |
| 503      | 50301 | 服务繁忙，暂时无法查询                              | 稍后重试，请勿在短时间内密集重试                 |

::: tip 重试建议

- 429：等待 1 分钟后再重试。
- 500、503：按递增间隔（如 2 秒、4 秒、8 秒）重试，最多 3 次。
- 其他 4xx 错误：重试不会成功，请修正请求后再发起。

:::