Interface Standard Document

Interface Standard Document

1. Document Information

• Document Name: SERVICEME System Interface Standard Document
• Version: v1.0
• Release Date: 2025-07-18
• Scope: Applicable to enterprise intelligent scenarios, supporting functions such as identity authentication, knowledge Q&A, process automation, data analysis, and content generation. The interface adopts a standard RESTful architecture, facilitating system integration and cross-platform applications. It is widely used in business modules such as customer service, marketing, finance, and human resources, enhancing collaboration efficiency and intelligent decision-making capabilities.

---

2. Revision History

Version	Revision Date	Revision Content
v1.0	2025-07-18	Initial draft

---

3. Overview

3.1 Document Purpose

The purpose of this document is, for example:

This document defines the interface specifications of the SERVICEME system, including request format, response format, error codes, etc., for reference by callers.

3.2 Terms and Abbreviations

• API: Application Programming Interface
• HTTP: Hypertext Transfer Protocol
• JSON: JavaScript Object Notation
• RESTful: An API design style

3.3 Interface Design Principles

• Follow RESTful style (where applicable).
• Use HTTPS protocol to ensure security.
• Data format unified as JSON.
• Interface version management (e.g., /v1/xxx).

---

4. General Specifications

4.1 Request Specifications

• Request Methods: GET/POST/PUT/DELETE, etc.
• Request Headers:
  • Content-Type: application/json
  • Authorization: Bearer {token} (if authentication is required).
• Request Parameters:
  • Query parameters (GET), Body parameters (POST/PUT).
  • Explanation of required/optional fields.

4.2 Response Specifications

• Response Format:

  {
    "code": 200,       // status code
    "message": "success",  // description message
    "data": {}         // returned data (optional)
  }

• HTTP Status Codes:

  • 200: Success
  • 400: Bad Request Parameters
  • 401: Unauthorized
  • 500: Internal Server Error

4.3 Error Code Table

Error Code	Meaning	Suggested Solution
200	Success	-
422	Parameter Error	-
40001	Missing Parameter	Check required fields
50001	Internal Server Error	Contact administrator

---

5. Interface Details

5.1 Interface 1: Get User Information

• Interface Path: GET /lite_api/v1/iam/user/{user_id}

• Request Parameters:

  Parameter Name	Type	Required	Description
  userId	Path	Yes	User ID

• Request Example:

  GET /v1/iam/user/293456 HTTP/1.1
  Authorization: Bearer abcdef123456

• Response Example:

  {
      "code": 200,
      "data": {
          "username": "string",
          "email": "string",
          "real_name": "",
          "nickname": "",
          "is_superuser": false,
          "avatar": "",
          "enable": true,
          "id": "string",
          "is_aad": false,
          "serial_number": "string",
          "created_at": "2019-08-24T14:15:22.123Z",
          "updated_at": "2019-08-24T14:15:22.123Z",
          "last_login": "2019-08-24T14:15:22.123Z",
          "roles": [],
          "user_roles": [],
          "organizations": [],
          "gender": 0,
          "birthday": "2019-08-24T14:15:22.123Z",
          "wechat": "string",
          "region": "string",
          "time_difference": 0,
          "join_time": "2019-08-24T14:15:22.123Z",
          "office_phone": "string",
          "mobile_phone": "string",
          "description": "string"
      },
      "message": "success"
  }

5.2 Interface 2: Create User

• Interface Path: POST /lite_api/v1/iam/user/

• Request Parameters:

  Parameter Name	Type	Required	Description
  username	string	Yes	Username
  email	string	Yes	Email
  real_name	string	Yes	Real Name

• Request Example:

  {
      "username": "string",
      "email": "",
      "real_name": "",
  }

• Response Example:

  {
      "username": "string",
      "email": "string",
      "real_name": "",
  }

5.3 Interface 3: Create Assistant

• Interface Path: POST /lite_api/v1/robots/

• Request Parameters:

  Parameter Name	Type	Required	Description
  info	object	Yes	Assistant info and name
  masks	array	No	Assistant masks
  knowledge_bases	array	No	Knowledge bases
  skills	array	No	Skills
  mcps	array	No	Data models
  data_sources	array	No	Data sources
  keywords_filter	object	No	Keywords filter
  feedback_accounts	array	No	Feedback accounts

  Request Example:

  {
      "info": {
          "name": "string",
          "weight": 0,
          "avatar_url": "string",
          "description": "",
          "prompt": "string",
          "prologue": "string",
          "robot_type": "",
          "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
          "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
          "product_position": "chat-x",
          "chat_rounds": 0,
          "user_id": "string",
          "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
          "split_type": "string",
          "load_type": "string",
          "spliter_json": "string",
          "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
          "user_skill_auths": [
              null
          ],
          "need_summary": true,
          "force_execute": true,
          "open_filter": true,
          "record_chat": true,
          "is_published": true,
          "category_ids": [
              "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "recommend_question": false,
          "feedback": false,
          "knowledge_config": {
              "search_mode": "hybrid",
              "k": 5,
              "doc_score": 0.7,
              "qa_score": 0.8,
              "metadata": "none",
              "show_reference": false
          },
          "editable": true,
          "question_guide": false,
          "operator_execute": false,
          "bi_config": {
              "query_rewrite": false,
              "divide_think": false
          }
      },
      "masks": [
          {
              "mask_set_id": "d0bee2ed-0859-4bb6-8598-f64d47a5a28b"
          }
      ],
      "knowledge_bases": [
          {
              "classification_id": "string",
              "classification_name": "string",
              "classification_icon": "string",
              "workspaces": []
          }
      ],
      "skills": [
          {
              "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
          }
      ],
      "mcps": [],
      "data_sources": [
          {
              "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
          }
      ],
      "keywords_filter": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
          "key_words": [
              "string"
          ],
          "review_input": true,
          "preset_reply_input": "string",
          "review_output": true,
          "preset_reply_output": "string"
      },
      "feedback_accounts": []
  }

  Response Example

  {
      "code": 200,
      "data": null,
      "message": "success"
  }

5.4 Interface 4: Get Assistant

• Interface Path: POST /lite_api/v1/robots/{robot_id}

• Request Parameters:

Parameter Name	Type	Required	Description
robot_id	string	Yes	Assistant ID
internal_use	boolean	No	Internal use or not

• Request Example:

  GET /lite_api/v1/robots/00001 HTTP/1.1
  Authorization: Bearer abcdef123456

• Response Example:

{
    "code": 200,
    "data": {
        "info": {
            "name": "string",
            "weight": 0,
            "avatar_url": "string",
            "description": "",
            "prompt": "string",
            "prologue": "string",
            "robot_type": "",
            "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
            "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
            "product_position": "chat-x",
            "chat_rounds": 0,
            "user_id": "string",
            "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
            "split_type": "string",
            "load_type": "string",
            "spliter_json": "string",
            "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
            "user_skill_auths": [
                null
            ],
            "need_summary": true,
            "force_execute": true,
            "open_filter": true,
            "record_chat": true,
            "is_published": true,
            "category_ids": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ],
            "recommend_question": false,
            "feedback": false,
            "knowledge_config": {
                "search_mode": "hybrid",
                "k": 5,
                "doc_score": 0.7,
                "qa_score": 0.8,
                "metadata": "none",
                "show_reference": false
            },
            "editable": true,
            "question_guide": false,
            "operator_execute": false,
            "bi_config": {
                "query_rewrite": false,
                "divide_think": false
            },
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "manageable": false
        },
        "masks": [],
        "knowledge_bases": [],
        "skills": [],
        "mcps": [],
        "data_sources": [],
        "keywords_filter": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
            "key_words": [
                "string"
            ],
            "review_input": true,
            "preset_reply_input": "string",
            "review_output": true,
            "preset_reply_output": "string"
        },
        "feedback_accounts": []
    },
    "message": "success"
}

5.5 Interface 5: Upload File

• Interface Path: POST /Api/Workspace/File/UploadFiles

• Request Parameters:

Parameter Name	Type	Required	Description
Files	array	No	Files to upload this time
WorkspaceId	string	No	string
FullPath	string	No	Full path to upload the file to
IsCover	boolean	No	Whether system upload
UserId	integer	No	User id (for public API)
UserEmail	string	No	User email (for public API)
OCRMode	string	No	OCR mode

• Response Example:

{
    "success": true,
    "msg": "string",
    "data": [
        {
            "workspaceId": 0,
            "fullName": "string",
            "id": 0
        }
    ]
}

---

6. Security Specifications

• Authentication Methods: OAuth2.0/JWT/API Key.

• Data Encryption: Sensitive fields must be transmitted encrypted (e.g., passwords).

• Rate Limiting Policy: Interface call frequency limits refer to the table below.

  Scenario	Common Limits	Description
  Open API (e.g., third-party calls)	10~100 times/minute	For example, WeChat Pay, Alipay open APIs usually limit 50~200 times/minute (depending on interface level).
  Internal System API	100~1000 times/minute	Internal service calls can be relaxed but should avoid excessive resource occupation by a single service.
  User Behavior Interface	5~60 times/minute	For sensitive operations such as login, SMS sending, strict limits are required (e.g., SMS verification code interface usually limits 1 time/60 seconds).
  Data Query Interface	100~5000 times/minute	High-frequency query interfaces can be relaxed appropriately but should cooperate with caching to reduce database pressure.
  High Concurrency Core Interface	Dynamic rate limiting (e.g., token bucket algorithm)	For example, e-commerce flash sale interfaces may combine circuit breaker mechanisms and elastic scaling.