archive: 紫鸟/HubStudio 文档快照（3889 篇 Markdown）

来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
2026-10-05 12:11:35 +00:00
commit 322b7737eb
@@ -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` 或在开放平台首页右侧查看）