Skill: ziniao-open/ziniao-sso-doc (version 1.0.0)

--- name: ziniao-sso-doc description: > Use when 需要理解紫鸟单点登录 OpenAPI 的定位、能力、集成流程或接口清单， 用于 ERP 系统 SSO 对接规划、集成设计或接口评估。 不要用于直接查阅具体接口参数——查阅时读取 reference/ 下对应文件。 --- # ziniao-sso-doc（紫鸟单点登录 API 文档） ## 何时使用 / 不使用 | 场景 | 做法 | |------|------| | 需要了解紫鸟单点登录能做什么 | 读本 Skill | | 需要做 ERP SSO 对接的集成设计 | 读本 Skill | | 需要查阅某个接口的请求/响应参数 | 读本 Skill §按需深入 获取路径，再读 reference/ 文件 | | 需要 Schema URL 协议详细参数 | 读 `reference/client-schema.md` | --- ## Level 0：定位与边界 ### 是什么 紫鸟单点登录 OpenAPI，面向 ERP/第三方系统，通过服务端 API 获取认证令牌，结合 `superbrowser://` Schema URL 协议拉起紫鸟浏览器并自动登录指定账号，实现免密单点登录。支持两种鉴权模式：简单鉴权（直接用 API Key，无需调用 get_app_token）和复杂鉴权（需额外获取 appAuthToken）。 ### 能力概览 | 能力域 | 说明 | |--------|------| | 应用认证 | 获取应用级 Token（appAuthToken）——仅复杂鉴权模式需要，简单鉴权模式直接用 API Key | | 企业信息 | 获取自建应用关联的公司 ID（companyId） | | 员工查询 | 分页查询公司员工列表，支持按角色/状态/部门筛选 | | 账号查询 | 查询公司全部账号或指定用户有权限的账号列表 | | 用户登录 | 获取指定用户的登录 Token（openapiToken），用于 SSO 鉴权 | | 客户端控制 | 通过 Schema URL 打开/关闭账号、退出浏览器（仅 Windows） | ### 不做什么（边界） - 不包含账号 CRUD（创建/删除/编辑）——见 ziniao-erp-api-doc - 不包含标签、授权、设备管理接口——见 ziniao-erp-api-doc - 不提供浏览器自动化（RPA/脚本注入）能力 - Schema URL 仅支持 Windows 客户端 --- ## Level 1：架构与流程 ### 核心概念 **两种鉴权模式**：**简单鉴权模式**——直接用 API Key 放入 `Authorization: Bearer {API_Key}` 请求头，无需调用 `get_app_token`；**复杂鉴权模式**——需先调用 `get_app_token` 获取 appAuthToken 再进行后续调用。大多数场景使用简单鉴权即可。 **用户登录 Token**：openapiToken，通过 `user-login` 接口获取，有过期时长，用于 Schema URL 拉起浏览器时的用户身份鉴权。 **Schema URL 协议**：以 `superbrowser://` 为前缀的自定义 URL 协议，支持三个 Action：OpenStrore（打开账号）、CloseStrore（关闭账号）、exit（退出浏览器）。可通过浏览器链接或命令行 `SuperBrowser.exe "url"` 调用。 **双层响应结构**：网关层（request_id / code / msg）+ 业务层（ret / status / data / msg）。网关 code="0" 表示请求到达业务层；业务 ret=0 表示操作成功。 ### SSO 集成全流程 ```mermaid graph LR A[创建应用<br/>获取 API Key] --> B[获取 companyId] B --> C[查询员工列表] C --> D[查询用户有权限的账号] D --> E[获取用户 openapiToken] E --> F[Schema URL<br/>打开账号] ``` 1. 在开放平台创建自建应用，获取 API Key（简单鉴权模式） 2. 调用 `builtin/company` 获取 companyId（固定值，获取一次即可） 3. 调用 `staff/list` 查询员工，获取 userId 4. 调用 `user/stores` 查询该用户有权限的账号，获取 storeId 5. 调用 `user-login` 获取用户的 openapiToken（需提前申请接口权限） 6. 拼接 Schema URL：`superbrowser://OpenStrore?storeId={storeId}&openapiToken={token}&userId={userId}` > 如使用复杂鉴权模式，需在步骤 1 之后额外调用 `get_app_token` 获取 appAuthToken。 ### 接口摘要表 | 分组 | 接口名称 | 路径 | 方法 | |------|---------|------|------| | 认证 | 获取应用 token（仅复杂鉴权模式） | /auth/get_app_token | POST | | 企业 | 获取公司信息 | /app/builtin/company | GET | | 员工 | ERP-员工查询 | /superbrowser/rest/v1/erp/staff/list | POST | | 账号 | ERP-账号列表查询 | /superbrowser/rest/v1/erp/store/list | POST | | 账号 | ERP-查询用户有权限的账号 | /superbrowser/rest/v1/erp/user/stores | POST | | 登录 | 获取用户登录 token | /superbrowser/rest/v1/token/user-login | POST | ### 公共响应结构 > **所有接口返回双层嵌套结构，解析时必须先剥离网关层再读业务层。** > **异常处理：请求异常时，必须将 request_id、msg 和 sub_msg 都打印出来，便于追踪定位。** ```json { "request_id": "全局请求追踪ID", "code": "0", // ← 网关层：code="0" 表示请求到达业务层 "msg": "SUCCESS", "sub_code": "", // ← 业务返回码，成功时不返回 "sub_msg": "", // ← 业务返回码描述，成功时不返回 "data": { ... } // ← 业务层：各接口文档中的响应参数均在此内部 } ``` ### 环境约定 - Base URL：`https://sbappstoreapi.ziniao.com/openapi-router` - 请求编码：UTF-8，Content-Type：application/json - 前提：在开放平台创建"卖家自研应用"，获取 API Key，申请所需权限点，配置 IP 白名单 - `user-login` 接口需联系紫鸟客服申请权限（需 Boss 验证） --- ## 按需深入（Level 2 路由表） > **规则：以下内容不要主动加载。** > 仅在你明确需要了解某个细节时，按路由表读取对应的 reference/ 文件。 | 你需要了解 | 读取文件 | |-----------|---------| | 认证接口详细参数（get_app_token + user-login） | `reference/account-auth.md` | | 企业信息、员工查询、账号查询接口的详细参数 | `reference/account-crud.md` | | Schema URL 协议详细参数（OpenStrore / CloseStrore / exit） | `reference/client-schema.md` | | API 使用指南（基地址、公共 Headers、公共响应、curl 示例） | `reference/api-guide.md` |

path: reference/account-auth.md
content: # 认证鉴权接口

> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
> 仅在需要查阅 get_app_token 或 user-login 接口的详细参数时加载。
>
> **响应说明**：以下各接口的"响应参数"均为业务层字段，实际位于网关响应的 `data` 内部。完整响应结构见 `api-guide.md` 公共响应参数。

## 获取应用 Token

> 仅在"复杂鉴权模式"下需要调用此接口。如使用"简单鉴权模式"（直接用 API Key），无需调用此接口，跳过本节即可。

### 基本信息

| 项目 | 值 |
|------|------|
| 路径 | `/auth/get_app_token` |
| 方法 | POST |
| Content-Type | application/json |

### 请求 Headers

| 参数名称 | 参数值 | 是否必须 |
|----------|--------|----------|
| Content-Type | application/json | true |
| Authorization | Bearer {API_Key} | true |

### 请求 Body

无需请求体参数。

### 响应参数

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| appAuthToken | 应用授权令牌 | string |
| expiresIn | 令牌有效期（秒），-1 表示永久有效 | string |

### 请求示例

```bash
curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/auth/get_app_token' \
--header 'Authorization: Bearer {API_Key}' \
--header 'Content-Type: application/json' \
--data-raw ''
```

### 响应示例

```json
{
  "appAuthToken": "xxxxxxxxxxxxxxxx",
  "expiresIn": "-1"
}
```

---

## 获取指定用户登录 Token

> 需联系紫鸟在线客服申请接口权限（走特殊申请 OA 单，Boss 验证后生效）。
> 目前仅支持 Windows 版客户端。

### 基本信息

| 项目 | 值 |
|------|------|
| 路径 | `/superbrowser/rest/v1/token/user-login` |
| 方法 | POST |
| Content-Type | application/json |

### 请求 Headers

| 参数名称 | 参数值 | 是否必须 |
|----------|--------|----------|
| Content-Type | application/json | true |
| Authorization | Bearer {API_Key} | true |

### 请求 Body

| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
|----------|----------|----------|----------|
| companyId | 公司 ID | false | number |
| userId | 用户 ID | false | number |

### 响应参数

> 注意：此接口业务层使用 `code`/`msg` 结构，与其他接口的 `ret`/`status`/`msg`/`count` 结构不同，判断成功应检查 `code == 0` 而非 `ret == 0`。

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| code | 0 表示成功 | number |
| msg | 状态描述（成功时为 "SUCCESS"） | string |
| data | 响应数据对象 | object |
| data.token | 用户登录 token（即 openapiToken） | string |
| data.expireTime | 过期时长（秒） | number |
| data.timeUnit | 时间单位（SECONDS） | string |

### 请求示例

```bash
curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/token/user-login' \
--header 'Authorization: Bearer {API_Key}' \
--header 'Content-Type: application/json' \
--data-raw '{"companyId":"15393571083459","userId":"15393571087094"}'
```

### 响应示例

```json
{
  "code": 0,
  "msg": "SUCCESS",
  "data": {
    "token": "79db5b0c8d16d5d7eecded06101a7e39",
    "expireTime": 1800,
    "timeUnit": "SECONDS"
  }
}
```

### 使用说明

获取到的 token 即为 Schema URL 中的 `openapiToken` 参数，拼接格式为：

```
superbrowser://OpenStrore?storeId={账号ID}&openapiToken={token}&userId={用户ID}
```

如果本地已登录紫鸟客户端，且 userId 与本地登录用户一致，可不传 openapiToken（客户端版本 v5.290 或 v6.25 以上）。


path: reference/account-crud.md
content: # 企业信息与员工/账号查询接口

> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
> 仅在需要查阅企业信息、员工查询或账号查询接口的详细参数时加载。

> **响应说明**：以下各接口的"响应参数"均为业务层字段，实际位于网关响应的 `data` 内部。完整响应结构见 `api-guide.md` 公共响应参数。

## 获取当前自建应用的公司信息

### 基本信息

| 项目 | 值 |
|------|------|
| 路径 | `/app/builtin/company` |
| 方法 | GET |
| Content-Type | application/json |

### 请求 Headers

| 参数名称 | 参数值 | 是否必须 |
|----------|--------|----------|
| Content-Type | application/json | true |
| Authorization | Bearer {API_Key} | true |

### 请求 Body

无。

### 响应参数

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| companyId | 企业 ID（固定值，获取一次后复用） | integer |

### 请求示例

```bash
curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/app/builtin/company' \
--header 'Authorization: Bearer {API_Key}'
```

### 响应示例

```json
{
  "companyId": 15393571083459
}
```

> companyId 为固定值，也可在开放平台首页右侧直接获取。

---

## ERP-员工查询

### 基本信息

| 项目 | 值 |
|------|------|
| 路径 | `/superbrowser/rest/v1/erp/staff/list` |
| 方法 | POST |
| Content-Type | application/json |

### 请求 Headers

| 参数名称 | 参数值 | 是否必须 |
|----------|--------|----------|
| Content-Type | application/json | true |
| Authorization | Bearer {API_Key} | true |

### 请求 Body

| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
|----------|----------|----------|----------|
| companyId | 公司 ID | true | number |
| page | 页码 | true | number |
| limit | 每页条数 | true | number |
| username | 用户账号 | false | string |
| name | 用户真实姓名 | false | string |
| departmentIds | 部门 ID 数组 | false | array\<number\> |
| level | 角色类型：0=Boss，1=经理，2=员工，3=超级管理员 | false | string |
| delflag | 删除标志：0=正常，1=禁用，2=删除（不传返回全部） | false | string |
| isAccurate | 查询模式：0=模糊查询，1=精确查询（默认 0） | false | number |

### 响应参数

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| ret | 状态码，0=成功 | number |
| status | success / faile | string |
| data | 员工列表 | array |
| data[].username | 用户名 | string |
| data[].userId | 用户 ID | number |
| data[].name | 联系人姓名 | string |
| data[].level | 角色类型：0=Boss，1=经理，2=员工，3=超级管理员 | string |
| data[].mobile | 手机号 | string |
| data[].delflag | 状态：0=正常，1=禁用，2=删除 | string |
| data[].authPhone | 登录手机号 | string |
| msg | 错误信息 | string |
| count | 总条数 | string |

### 请求示例

```bash
curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/staff/list' \
--header 'Authorization: Bearer {API_Key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "companyId": "15393571083459",
  "page": "1",
  "limit": "10",
  "level": "",
  "isAccurate": "",
  "departmentIds": [],
  "delflag": "",
  "name": "",
  "username": ""
}'
```

---

## ERP-账号列表查询

### 基本信息

| 项目 | 值 |
|------|------|
| 路径 | `/superbrowser/rest/v1/erp/store/list` |
| 方法 | POST |
| Content-Type | application/json |

### 请求 Headers

| 参数名称 | 参数值 | 是否必须 |
|----------|--------|----------|
| Content-Type | application/json | true |
| Authorization | Bearer {API_Key} | true |

### 请求 Body

| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
|----------|----------|----------|----------|
| companyId | 公司 ID | true | number |
| storeName | 账号名称 | false | string |
| ip | 设备 IP | false | string |
| page | 页码 | false | number |
| limit | 每页条数（私有化账号建议传 20） | false | number |

### 响应参数

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| ret | 状态码，0=成功 | number |
| status | success / faile | string |
| data | 账号列表 | array |
| data[].id | 账号 ID（即 storeId） | number |
| data[].ip | 设备 IP | string |
| data[].lastuserId | 最后登录用户 ID | number |
| data[].lastusetime | 最后登录时间 | string |
| data[].name | 账号名 | string |
| data[].platform | 账号所属平台（如"美国亚马逊"） | string |
| data[].proxyId | 设备 ID | string |
| data[].siteId | 平台 ID | string |
| data[].username | 平台登录账号 | string |
| data[].createtime | 账号创建时间 | string |
| data[].siteName | 站点名称 | string |
| data[].packageName | 套餐名称 | string |
| data[].platformName | 平台名称 | string |
| msg | 错误信息 | string |
| count | 总条数 | string |

### 请求示例

```bash
curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list' \
--header 'Authorization: Bearer {API_Key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "companyId": "15393571083459",
  "storeName": "",
  "ip": "",
  "page": "1",
  "limit": "10"
}'
```

---

## ERP-查询某用户有权限的账号列表

### 基本信息

| 项目 | 值 |
|------|------|
| 路径 | `/superbrowser/rest/v1/erp/user/stores` |
| 方法 | POST |
| Content-Type | application/json |

### 请求 Headers

| 参数名称 | 参数值 | 是否必须 |
|----------|--------|----------|
| Content-Type | application/json | true |
| Authorization | Bearer {API_Key} | true |

### 请求 Body

| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
|----------|----------|----------|----------|
| companyId | 公司 ID | true | number |
| userId | 用户 ID | true | number |
| storeName | 账号名称 | false | string |
| isAccurate | 查询模式：0=模糊，1=精确（默认精确） | false | number |
| page | 页码 | false | number |
| limit | 每页条数 | false | number |

### 响应参数

| 参数名称 | 参数说明 | 类型 |
|----------|----------|------|
| ret | 状态码，0=成功 | number |
| status | success / faile | string |
| data | 账号列表 | array |
| data[].id | 账号 ID（即 storeId） | number |
| data[].ipId | 设备 ID | number |
| data[].ip | 设备 IP | string |
| data[].platform | 账号所属平台 | string |
| data[].name | 账号名 | string |
| data[].lastUserId | 最后登录用户 ID | string |
| data[].lastUserName | 最后登录用户姓名 | string |
| data[].lastOpenUsername | 最后登录用户名称 | string |
| data[].lastUsetime | 最后登录时间 | string |
| data[].ipExpiryTime | 设备到期时间 | string |
| data[].tags | 账号标签列表 | array\<string\> |
| data[].regionInfo | 套餐信息 | string |
| data[].platformCategory | 平台类目 | string |
| data[].userName | 登录凭证 | string |
| msg | 错误信息 | string |
| count | 总条数 | number |

### 请求示例

```bash
curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/user/stores' \
--header 'Authorization: Bearer {API_Key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "companyId": "15393571083459",
  "userId": "15393571087094",
  "storeName": "",
  "isAccurate": "",
  "page": "1",
  "limit": "10"
}'
```


path: reference/api-guide.md
content: # 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` 或在开放平台首页右侧查看）


path: reference/client-schema.md
content: # 客户端 Schema URL 协议

> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
> 仅在需要查阅 superbrowser:// Schema URL 的详细参数与用法时加载。

## 概述

通过 `superbrowser://` 自定义 URL 协议控制紫鸟浏览器，支持打开/关闭账号和退出程序。
调用方式有两种：

1. **浏览器链接**：在浏览器地址栏打开 `superbrowser://...`（需通过安装程序安装紫鸟）
2. **命令行**：`SuperBrowser.exe "superbrowser://..."` （需主程序路径正确）

---

## Action: OpenStrore（打开账号）

### 完整示例

```
superbrowser://OpenStrore?storeId=xxxxxxx&openapiToken=xxxxxxxxx&userId=xxxxxxx&lanuchUrl=aHR0cHM6Ly93d3cuYmFpZHUuY29t&autoopen=true&debuggPort=60001&notPromptForDownload=1&forceDownloadPath=Rjpc5a6J6KOF5YyF --disable-gpu start-maximized
```

### 必须参数

| 参数 | 说明 |
|------|------|
| storeId | 账号 ID |
| userId | 紫鸟的用户 ID（如果发生变化需要重新登录） |
| openapiToken | 鉴权 token（通过 `user-login` 接口获取） |

> 如果本地已登录紫鸟客户端，且 userId 与本地登录用户一致，openapiToken 可不传（客户端版本 v5.290 或 v6.25 以上）。

### 可选参数

| 参数 | 说明 |
|------|------|
| lanuchUrl | 将要打开的目标地址，需 Base64 编码（如 `https://www.baidu.com` → `aHR0cHM6Ly93d3cuYmFpZHUuY29t`） |
| autoopen | 设为 `true` 时自动打开 lanuchUrl 配置的地址 |
| debuggPort | 指定 debug 端口号 |
| notPromptForDownload | `1`=下载文件不弹出选择路径提示框，直接下载；`0` 或不传则弹出选择路径提示框 |
| forceDownloadPath | 设置默认下载路径，路径需 Base64 编码 |

### 命令行参数

命令参数添加在链接后面，用空格隔开，多个参数也用空格隔开。

> 添加的命令参数需要向管理员申请使用权限，否则不生效。

### 响应结果

启动紫鸟浏览器并打开对应账号。

---

## Action: exit（退出浏览器）

### 请求格式

```
superbrowser://exit
```

### 说明

退出紫鸟浏览器程序，关闭所有账号。

> 如果上次打开的程序未完全退出，下次调用打开账号将会发生异常。建议在重新打开前先调用 exit。

---

## Action: CloseStrore（关闭账号）

### 请求格式

```
superbrowser://CloseStrore?storeId=268682156400
```

### 参数

| 参数 | 说明 |
|------|------|
| storeId | 要关闭的账号 ID |

### 说明

关闭指定账号，每次只能关闭 1 个账号。如需关闭多个，需多次调用。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)