SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsziniao-sso-doc

ziniao-sso-doc

General & other

View repository

Updated 10-16 08:09

About this skill

ziniao-sso-doc (Ziniao Single Sign-On API Documentation)

When to use / not use

Scenario Approach
Need to understand what Ziniao single sign-on can do Read this Skill
Need to do integration design for ERP SSO connection Read this Skill
Need to look up the request/response parameters of a certain API Read this Skill §On-demand deep dive to get the path, then read the reference/ file
Need detailed parameters of the Schema URL protocol Read reference/client-schema.md

Level 0: Positioning and boundaries

What it is

Ziniao single sign-on OpenAPI, aimed at ERP/third-party systems, obtains authentication tokens through server-side APIs, and combines with the superbrowser:// Schema URL protocol to launch the Ziniao browser and automatically log in to the specified account, achieving password-free single sign-on. It supports two authentication modes: simple authentication (directly use the API Key, no need to call get_app_token) and complex authentication (requires additionally obtaining appAuthToken).

Capability overview

Capability domain Description
Application authentication Obtain application-level Token (appAuthToken)—only required for complex authentication mode; simple authentication mode directly uses the API Key
Enterprise information Obtain the company ID (companyId) associated with the self-built application

| Employee query | Paginated query of the company's employee list, supporting filtering by role/status/department | | Account query | Query all accounts of the company or the account list that a specified user has permission for | | User login | Obtain the login Token (openapiToken) of a specified user, used for SSO authentication | | Client control | Open/close accounts and exit the browser through the Schema URL (Windows only) |

What it does not do (boundaries)

  • Does not include account CRUD (create/delete/edit)—see ziniao-erp-api-doc
  • Does not include tags, authorization, or device management APIs—see ziniao-erp-api-doc
  • Does not provide browser automation (RPA/script injection) capabilities
  • Schema URL only supports the Windows client

Level 1: Architecture and process

Core concepts

Two authentication modes：Simple authentication mode—directly put the API Key into the Authorization: Bearer {API_Key} request header, no need to call get_app_token；Complex authentication mode—need to first call get_app_token to obtain appAuthToken before making subsequent calls. Most scenarios can use simple authentication.

User login Token: openapiToken, obtained through the user-login API, has an expiration duration, and is used for user identity authentication when the Schema URL launches the browser.

Schema URL protocol: a custom URL protocol prefixed with superbrowser:// , supporting three Actions: OpenStrore (open account), CloseStrore (close account), exit (exit browser). It can be called through a browser link or the command line SuperBrowser.exe "url" .

Two-layer response structure: Gateway layer (request_id / code / msg) + business layer (ret / status / data / msg). Gateway code="0" indicates the request reached the business layer; business ret=0 indicates the operation succeeded.

Full SSO Integration Process

graph LR
  A[创建应用<br/>获取 API Key] --> B[获取 companyId]
  B --> C[查询员工列表]
  C --> D[查询用户有权限的账号]
  D --> E[获取用户 openapiToken]
  E --> F[Schema URL<br/>打开账号]
  1. Create a self-built app on the open platform and obtain the API Key (simple authentication mode)
  2. Call builtin/company to obtain companyId (a fixed value; retrieve it only once)
  3. Call staff/list to query employees and obtain userId
  4. Call user/stores to query the accounts the user has permission for and obtain storeId
  5. Call user-login to obtain the user's openapiToken (interface permission must be applied for in advance)
  6. Assemble the Schema URL:superbrowser://OpenStrore?storeId={storeId}&openapiToken={token}&userId={userId}

If using complex authentication mode, after step 1 you must additionally call get_app_token to obtain appAuthToken.

Interface Summary Table

Group Interface Name Path Method
Authentication Obtain app token (complex authentication mode only) /auth/get_app_token POST
Enterprise Obtain company information /app/builtin/company GET
Employee ERP-Employee Query /superbrowser/rest/v1/erp/staff/list POST
Account ERP-Account List Query /superbrowser/rest/v1/erp/store/list POST
Account ERP-Query accounts the user has permission for /superbrowser/rest/v1/erp/user/stores POST
Login Obtain user login token /superbrowser/rest/v1/token/user-login POST

Common Response Structure

All interfaces return a two-layer nested structure; when parsing, you must first strip off the gateway layer before reading the business layer. Exception handling: when a request is abnormal, you must print out request_id, msg, and sub_msg to facilitate tracking and troubleshooting.

{
  "request_id": "全局请求追踪ID",
  "code": "0",        // ← 网关层：code="0" 表示请求到达业务层
  "msg": "SUCCESS",
  "sub_code": "",      // ← 业务返回码，成功时不返回
  "sub_msg": "",       // ← 业务返回码描述，成功时不返回
  "data": { ... }     // ← 业务层：各接口文档中的响应参数均在此内部
}

Environment Conventions

  • Base URL：https://sbappstoreapi.ziniao.com/openapi-router
  • Request encoding: UTF-8, Content-Type: application/json
  • Prerequisite: Create a "seller self-developed app" on the open platform, obtain the API Key, apply for the required permission points, and configure the IP whitelist
  • user-login The interface requires contacting Ziniao customer service to apply for permission (Boss verification required)

Deep Dive as Needed (Level 2 Routing Table)

Rule: Do not proactively load the following content. Only when you clearly need to understand a certain detail, read the corresponding reference/ file according to the routing table.

You need to understand Read File
Detailed parameters of the authentication interfaces (get_app_token + user-login) reference/account-auth.md
Detailed parameters of the enterprise information, employee query, and account query interfaces reference/account-crud.md
Detailed parameters of the Schema URL protocol (OpenStrore / CloseStrore / exit) reference/client-schema.md
API Usage Guide (base address, common Headers, common responses, curl examples) reference/api-guide.md