admin9webs
322b7737eb
来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。 只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
109 lines
4.0 KiB
Markdown
109 lines
4.0 KiB
Markdown
# 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 获取错误详情。
|