# 接口总览

BioTech 开放平台当前对外接口、认证要求与公共响应约定。

## 对外接口清单

生产基础地址：`https://backend.biotech-mkt.com`。完整请求 URL 由“生产基础地址 + 接口路径”组成，接口详情页会直接展示可请求的完整 URL。

| 方法   | 路径                                                | Access Token | 说明                                |
| ------ | --------------------------------------------------- | ------------ | ----------------------------------- |
| `POST` | `/openapi/auth/token`                               | 不需要       | 使用 App Key 和 App Secret 获取令牌 |
| `POST` | `/openapi/auth/refresh`                             | 不需要       | 使用 Refresh Token 轮换令牌         |
| `POST` | `/openapi/auth/revoke`                              | 不需要       | 吊销 Refresh Token 对应的令牌       |
| `GET`  | `/openapi/profile`                                  | 需要         | 获取当前调用应用和令牌上下文        |
| `GET`  | `/openapi/v1/doudian/order/union-settlement-orders` | 需要         | 分页查询抖音精选联盟订单            |

前三个认证接口是固定公共路径，不需要在接口管理中登记。后两个接口虽然已经在代码中发布，仍必须在后台登记、启用并授权给当前应用。

## 请求约定

- 生产基础地址为 `https://backend.biotech-mkt.com`；非生产环境地址由平台管理员提供。
- JSON 请求使用 `Content-Type: application/json`。
- 受保护接口推荐使用 `Authorization: Bearer <access_token>`。
- 路径会去除末尾 `/` 后参与精确匹配；请求方法必须正确。
- 不接受通过 URL 查询参数传递 Access Token。

## 成功响应

```json
{
  "code": 200,
  "message": "成功",
  "data": {}
}
```

业务接口成功时还会返回：

- `X-Request-Id`
- `X-RateLimit-Status`
- 启用频控时的 QPS 和 30 天额度响应头

## 错误响应

```json
{
  "code": 401,
  "message": "access_token 已过期",
  "data": []
}
```

调用方应同时判断 HTTP 状态码和响应 `code`，并保存 `X-Request-Id` 供平台管理员查询调用日志。不要依赖 `message` 做程序分支。

## 保护接口的校验顺序

服务端按以下顺序处理受保护请求：

1. 验证 Access Token 和应用状态。
2. 验证接口是否由代码发布。
3. 验证接口登记状态和应用授权。
4. 消耗当前应用与接口维度的频控额度。
5. 执行业务控制器。

因此，同一个路径可能因为令牌、发布、授权或频控阶段不同而返回不同状态码。详见[错误与频控](/guides/errors-rate-limits)。