ziniao-erp-api-doc（紫鸟ERP API 文档）

何时使用 / 不使用

场景	做法
需要了解紫鸟 API 的能力和模块	读本 Skill
需要了解接口权限点以申请开通

Level 0：定位与边界

是什么

紫鸟ERP REST API，面向 ERP/第三方系统，通过"简单通用模式"（Bearer API Key）认证，实现紫鸟浏览器的企业级管理——涵盖账号、设备、访问策略、角色权限、部门员工五大模块，共 72 个接口。

能力概览

能力域	接口数	说明
账号管理	22	账号 CRUD、授权管理、标签体系、缓存清除
设备管理

不做什么（边界）

- 不包含 OAuth 授权模式（仅覆盖简单通用模式）
不包含浏览器指纹配置或窗口管理
不包含账单/支付明细（仅含设备购买/续费操作）
不包含企业创建/注销等顶级管理

Level 1：架构与流程

核心概念

API Key 认证：在开放平台创建"卖家自研应用"并选择"简单通用模式"获取 API Key。请求头：Authorization: Bearer {API_Key}。

双层响应结构：网关层（requestid / code / msg / data(业务层)）+ 业务层（ret / status / msg + 业务字段）。网关 code="0" 到达业务层；业务 ret=0 操作成功。失败时额外返回 subcode / sub_msg。注意：业务数据不一定在业务层的 data 字段中，部分接口的业务字段直接位于业务层根级（参见各 reference 文件中的响应说明）。

核心 ID 体系：companyId（紫鸟企业ID，几乎所有接口必传，可在开放平台首页右侧获取）、storeId（账号ID）、userId/staffId（用户ID）、proxyId（设备ID）、tagId/tid（标签ID）、roleId（角色ID）、ruleId（规则ID）。

权限点体系：每个接口归属一个"所属权限点"，应用需在开放平台申请开通对应权限后才能调用。多个接口可共享同一权限点。

调用流程

CODEBLOCK0

Base URL：INLINECODE1

权限点汇总

应用需在开放平台申请开通以下权限点，才能调用对应接口：

模块	需申请的权限点
账号管理	ERP-创建与删除账号权限、ERP-账号查看权限、ERP-编辑账号基础信息、ERP-账号授权权限、ERP-清除账号授权、ERP-清除账号缓存、ERP-查询某用户有权限的账号列表、ERP-标签列表、账号标签管理权限
设备管理

每个 reference 文件中标注了各接口的具体权限点归属。

公共响应结构

CODEBLOCK1

注意：业务数据位置因接口而异。多数接口的业务数据在 data.data 中，但部分接口的业务字段直接在业务层根级（与 ret/status 同级）。例如"ERP-员工新增v2"返回的 id、password 直接在业务层，不在 data 字段内。请以各 reference 文件中"响应 data"或"响应"的标注为准——标注"响应 data"表示数据在 data 字段中，标注"响应"则表示字段在业务层根级。

环境约定

- 请求编码：UTF-8，Content-Type：application/json
域名：INLINECODE3
几乎所有接口均为 POST + JSON body
前提：创建"卖家自研应用"，选择"简单通用模式"，申请所需权限点，配置 IP 白名单

按需深入（Level 2 路由表）

规则：以下内容不要主动加载。
仅在需要了解某个细节时，按路由表读取对应的 reference/ 文件。

你需要了解	读取文件
认证方式、请求构造、代码示例（Java/Python/JS）、常见错误	INLINECODE4
账号创建/删除/编辑/列表查询/标签列表/缓存清除

ziniao-erp-api-doc（紫鸟ERP API 文档）

何时使用 / 不使用

场景	做法
需要了解紫鸟 API 的能力和模块	阅读本 Skill
需要了解接口权限点以申请开通

Level 0：定位与边界

是什么

紫鸟ERP REST API，面向 ERP/第三方系统，通过简单通用模式（Bearer API Key）认证，实现紫鸟浏览器的企业级管理——涵盖账号、设备、访问策略、角色权限、部门员工五大模块，共 72 个接口。

能力概览

能力域	接口数	说明
账号管理	22	账号 CRUD、授权管理、标签体系、缓存清除
设备管理

不做什么（边界）

- 不包含 OAuth 授权模式（仅覆盖简单通用模式）
不包含浏览器指纹配置或窗口管理
不包含账单/支付明细（仅含设备购买/续费操作）
不包含企业创建/注销等顶级管理

Level 1：架构与流程

核心概念

API Key 认证：在开放平台创建卖家自研应用并选择简单通用模式获取 API Key。请求头：Authorization: Bearer {API_Key}。

双层响应结构：网关层（requestid / code / msg / data(业务层)）+ 业务层（ret / status / msg + 业务字段）。网关 code=0 到达业务层；业务 ret=0 操作成功。失败时额外返回 subcode / sub_msg。注意：业务数据不一定在业务层的 data 字段中，部分接口的业务字段直接位于业务层根级（参见各 reference 文件中的响应说明）。

权限点体系：每个接口归属一个所属权限点，应用需在开放平台申请开通对应权限后才能调用。多个接口可共享同一权限点。

调用流程

mermaid
graph LR
A[获取 API Key] --> B[申请权限点]
B --> C[构造请求头]
C --> D[POST 请求]
D --> E{网关 code=0?}
E -- 是 --> F{业务 ret=0?}
E -- 否 --> G[检查 Key/权限]
F -- 是 --> H[解析业务字段]
F -- 否 --> I[读取 msg]

Base URL：https://sbappstoreapi.ziniao.com/openapi-router