archive: 紫鸟/HubStudio 文档快照（3889 篇 Markdown）
来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。 只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
This commit is contained in:
admin9webs committed
commit
322b7737eb
3976 files changed
+695714
No files matched your search
@@ -0,0 +1,129 @@
|
||||
# 认证鉴权接口
|
||||
|
||||
> 本文件是 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 以上）。
|
||||
@@ -0,0 +1,256 @@
|
||||
# 企业信息与员工/账号查询接口
|
||||
|
||||
> 本文件是 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"
|
||||
}'
|
||||
```
|
||||
@@ -0,0 +1,84 @@
|
||||
# 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` 或在开放平台首页右侧查看）
|
||||
@@ -0,0 +1,88 @@
|
||||
# 客户端 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¬PromptForDownload=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 个账号。如需关闭多个，需多次调用。
|
||||
Reference in new issue
Block a user