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

来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。
只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。

repos/skill-hub/skills/ziniao-erp-api-doc/reference/api-guide.md

@@ -0,0 +1,108 @@
+# API 调用指南
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要了解认证方式、请求构造方法、代码示例或常见错误时加载。
+
+## 概述
+
+紫鸟开放平台使用"简单通用模式"进行 API 认证，通过 API Key 作为 Bearer Token 传递。
+
+## 1. 获取 companyId（紫鸟企业ID）
+
+在开放平台首页右侧可获取紫鸟企业ID（即 companyId），几乎所有接口都需要传此参数。
+
+## 2. 获取 API Key
+
+前提：在紫鸟开放平台创建"卖家自研应用"，API 身份验证方式选择**简单通用模式**。在控制台中可以找到 API Key。
+
+## 3. 配置 IP 白名单
+
+在紫鸟开放平台的**应用管理**中，点击【设置】进入该应用的【应用概览】页面，点击【安全中心】下的【IP 白名单设置】，添加调用接口的服务器 IP。建议使用一台 IP 固定的服务器发起 API 请求。
+
+## 4. 构造请求头
+
+```
+Authorization: Bearer {你的API_Key}
+Content-Type: application/json
+```
+
+`Bearer` 和 API Key 之间必须有一个空格。
+
+## 5. 请求地址
+
+Base URL：`https://sbappstoreapi.ziniao.com/openapi-router`
+
+完整请求地址 = Base URL + 接口路径。例如：
+`https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list`
+
+## 6. 响应结构
+
+### 网关层（外层）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| request_id | string | 全局请求ID |
+| code | string | "0" 表示成功 |
+| msg | string | 返回码描述 |
+| sub_code | string | 业务返回码（成功时不返回） |
+| sub_msg | string | 业务返回码描述（成功时不返回） |
+| data | object | 业务响应参数 |
+
+### 业务层（data 内部）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| ret | number | 0 成功，其他失败 |
+| status | string | "success" 或 "faile" |
+| data | array/object | 业务数据（部分接口有） |
+| msg | string | 错误信息 |
+| count | number | 列表查询时的总条数 |
+| 其他字段 | - | 部分接口的业务字段直接在此层级 |
+
+> **关键提醒**：业务数据位置因接口而异，不要假设所有业务数据都在 `data` 字段中。各 reference 文件对每个接口标注了"响应 data"或"响应"——"响应 data"表示数据在业务层的 data 字段中；"响应"后直接列出的字段（如 id、password）表示它们与 ret/status 同级，直接位于业务层根级。
+
+## 7. 代码示例
+
+### Java（OkHttp）
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder().build();
+MediaType mediaType = MediaType.parse("application/json");
+RequestBody body = RequestBody.create(mediaType, "{\"companyId\": 123456}");
+Request request = new Request.Builder()
+  .url("https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list")
+  .method("POST", body)
+  .addHeader("Authorization", "Bearer 你的API_Key")
+  .addHeader("Content-Type", "application/json")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+### Python（requests）
+
+```python
+import requests, json
+url = "https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list"
+headers = {"Authorization": "Bearer 你的API_Key", "Content-Type": "application/json"}
+response = requests.post(url, headers=headers, data=json.dumps({"companyId": 123456}))
+print(response.json())
+```
+
+### JavaScript（Fetch）
+
+```javascript
+fetch("https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list", {
+  method: "POST",
+  headers: { "Authorization": "Bearer 你的API_Key", "Content-Type": "application/json" },
+  body: JSON.stringify({ companyId: 123456 }),
+})
+  .then(r => r.json()).then(console.log).catch(console.error);
+```
+
+## 8. 常见问题
+
+**401 错误**：检查 API Key 是否正确、Authorization 格式是否含空格、接口是否支持通用模式、应用是否已申请对应权限点。
+
+**code 非 "0"**：请求未到达业务层，通常是认证或权限问题。
+
+**ret 非 0**：业务操作失败，读取 msg 或 sub_msg 获取错误详情。