API Standard Document
API Standard Document
1. Document Information
- Document Name: SERVICEME System API Standard Document
- Version: v1.1
- Release Date: 2026-06-05
- Scope: Applicable to enterprise intelligent scenarios, supporting identity authentication, knowledge Q&A, process automation, data analysis, and content generation. The APIs follow a standard RESTful architecture for easy system integration and cross-platform usage, and are widely used in business modules such as customer service, marketing, finance, and human resources to improve collaboration efficiency and intelligent decision-making.
2. Revision History
| Version | Revision Date | Revision Details |
|---|---|---|
| v1.0 | 2025-07-18 | Initial draft |
| v1.1 | 2026-06-05 | Added Cross-Origin Resource Sharing (CORS) guidelines |
3. Overview
3.1 Purpose
This section explains the objective of the document, for example:
This document defines the API specifications of the SERVICEME system, including request formats, response formats, error codes, and more, for integrators and 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 API Design Principles
- Follow RESTful conventions (where applicable).
- Use HTTPS to ensure security.
- Use JSON as the unified data format.
- Manage API versions (for example,
/v1/xxx).
4. General Standards
4.1 Request Standards
- Request Methods: GET/POST/PUT/DELETE, etc.
- Request Headers:
Content-Type: application/jsonAuthorization: Bearer {token}(when authentication is required).
- Request Parameters:
- Query parameters (GET), Body parameters (POST/PUT).
- Required/optional field definitions.
4.2 Response Standards
-
Response Format:
{
"code": 200,
"message": "Success",
"data": {}
} -
HTTP Status Codes:
- 200: Success
- 400: Invalid request parameters
- 401: Unauthorized
- 500: Internal server error
4.3 Error Code Table
| Error Code | Meaning | Recommended Action |
|---|---|---|
| 200 | Success | - |
| 422 | Invalid parameter | - |
| 40001 | Missing parameter | Check required fields |
| 50001 | Internal server error | Contact administrator |
4.4 Cross-Origin Access Standards (CORS)
4.4.1 Background
Cross-Origin Resource Sharing (CORS) is a browser security mechanism used to control whether web pages are allowed to send requests to servers on different domains. When a front-end application and API service are deployed on different domains (or ports), browsers automatically perform CORS validation.
4.4.2 Default Policy in NEXT Version
By default, SERVICEME NEXT does not allow cross-origin access. In other words, if a browser page sends API requests directly and the request origin is not explicitly allowed by server-side configuration, the request will be rejected.
4.4.3 Differences from LTS Version
| Item | LTS Version | NEXT Version |
|---|---|---|
| Cross-origin restriction | No restriction (no cross-origin interception) | Cross-origin access is denied by default |
| Migration impact | - | After migrating from LTS to NEXT, browser-based cross-origin API calls used previously may fail |
Migration note: If your system is upgraded from LTS to NEXT and your front end relies on cross-origin API calls, those requests will fail after the upgrade unless cross-origin configuration is applied in advance.
4.4.4 Solution
If cross-origin access is required, contact your assigned delivery team for configuration. The delivery team will configure the allowed origin domains based on your business scenario.
4.4.5 Common Symptoms
When a cross-origin issue occurs, browser developer tools (Console) usually show errors like:
Access to XMLHttpRequest at 'https://api.xxx.com/...' from origin 'https://your-app.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
If you see similar errors in the browser console, the request is being blocked by cross-origin policy. Please contact the delivery team.
5. API Details
5.1 API 1: Get User Information
-
Path: GET /webapi/lite_api/v1/iam/user/
{user_id} -
Request Parameters:
Parameter Type Required Description userId Path Yes User ID -
Request Example:
GET /webapi/lite_api/v1/iam/user/234567 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"
}