0 Fork 0

Files

T

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

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

2026-10-05 12:11:35 +00:00

4.0 KiB

Raw Permalink Blame History

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）

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）

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）

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 获取错误详情。

4.0 KiB Raw Permalink Blame History Unescape Escape