# API 使用指南

> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
> 仅在需要了解 API 基地址、公共 Headers、公共响应结构或 curl 调用示例时加载。

## Base URL

```
https://sbappstoreapi.ziniao.com/openapi-router
```

所有服务端接口路径均以此为前缀拼接。

## 公共请求 Headers

| Header | 值 | 说明 |
|--------|------|------|
| Content-Type | application/json | 所有接口统一使用 JSON 格式 |
| Authorization | Bearer {API_Key} | API Key 从开放平台自建应用获取 |

## 认证方式

支持两种鉴权模式：

### 简单鉴权模式（推荐）

1. 在紫鸟开放平台创建"卖家自研应用"
2. API 身份验证选择"简单通用模式"
3. 获取 API Key
4. 每次请求在 Header 中携带 `Authorization: Bearer {API_Key}`

无需调用 `get_app_token` 接口，直接用 API Key 即可调用所有业务接口。

### 复杂鉴权模式

1. 创建应用后获取 API Key
2. 调用 `/auth/get_app_token` 获取 appAuthToken
3. 后续请求使用 appAuthToken 进行身份验证

## 公共响应参数

所有接口的网关层返回以下统一结构：

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| request_id | 全局请求 ID，用于追踪定位 | string |
| code | 网关返回码，`"0"` 表示成功 | string |
| msg | 网关返回码描述 | string |
| sub_code | 业务返回码，成功时不返回 | string |
| sub_msg | 业务返回码描述，成功时不返回 | string |
| data | 业务响应参数 | object |

### 业务层响应（data 内部）

部分接口（员工查询、账号查询等）的 data 内部有二级结构：

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| ret | 状态码，0=成功，其他=失败 | number |
| status | `"success"` 或 `"faile"` | string |
| data | 业务数据（数组或对象） | array/object |
| msg | 错误信息 | string |
| count | 总条数 | string/number |

### 响应判断逻辑

```
1. 检查网关层 code 是否为 "0"
   ├── 否 → 打印 request_id、msg、sub_msg，检查 API Key 和权限配置
   └── 是 → 检查业务层是否成功
            ├── 否 → 打印响应获取错误原因
            └── 是 → 解析 data 获取业务数据
```

> **异常处理要求**：请求异常（包括状态码异常）时，必须将 `request_id`、`msg` 和 `sub_msg` 都打印出来，便于追踪定位问题。

## 前置准备

1. 在紫鸟开放平台注册并创建"卖家自研应用"
2. 选择鉴权模式（简单鉴权或复杂鉴权）
3. 获取 API Key
4. 申请所需权限点（如需使用 `user-login` 接口，需联系紫鸟在线客服走特殊申请 OA 单，Boss 验证后生效）
5. 配置 IP 白名单
6. 获取 companyId（调用 `/app/builtin/company` 或在开放平台首页右侧查看）