インターフェース標準ドキュメント

1. ドキュメント情報

ドキュメント名：SERVICEMEシステムインターフェース標準ドキュメント
バージョン番号：v1.0
公開日：2025-07-18
適用範囲：企業のスマート化シナリオに適用され、認証、知識問答、プロセス自動化、データ分析およびコンテンツ生成などの機能をサポートします。インターフェースは標準のRESTfulアーキテクチャを採用し、システム統合およびクロスプラットフォームアプリケーションを容易にし、カスタマーサービス、マーケティング、財務、人事などの業務モジュールで広く利用され、協調効率とインテリジェントな意思決定能力を向上させます。

2. 改訂履歴

バージョン番号	改訂日	改訂内容
v1.0	2025-07-18	初稿

3. 概要

3.1 ドキュメント目的

ドキュメントの目的を説明します。例えば：

本ドキュメントはSERVICEMEシステムのインターフェース仕様を定義し、リクエスト形式、レスポンス形式、エラーコードなどを含み、呼び出し側の参考用とします。

3.2 用語と略語

API：アプリケーションプログラミングインターフェース
HTTP：ハイパーテキストトランスファープロトコル
JSON：JavaScriptオブジェクト表記法
RESTful：API設計スタイルの一種

3.3 インターフェース設計原則

RESTfulスタイルに準拠（該当する場合）。
HTTPSプロトコルを使用してセキュリティを確保。
データ形式は統一してJSON。
インターフェースのバージョン管理（例：/v1/xxx）。

4. 共通規範

4.1 リクエスト規範

リクエストメソッド：GET/POST/PUT/DELETEなど。
リクエストヘッダー（Headers）：
- Content-Type: application/json
- Authorization: Bearer {token}（認証が必要な場合）。
リクエストパラメータ：
- クエリパラメータ（GET）、ボディパラメータ（POST/PUT）。
- 必須/任意フィールドの説明。

4.2 レスポンス規範

レスポンス形式：

{
  "code": 200,       // ステータスコード
  "message": "成功",  // 説明メッセージ
  "data": {}         // 返却データ（任意）
}

HTTPステータスコード：
- 200：成功
- 400：リクエストパラメータエラー
- 401：未認証
- 500：サーバ内部エラー

4.3 エラーコード表

エラーコード	意味	解決策の提案
200	成功	-
422	パラメータエラー	-
40001	パラメータ不足	必須フィールドを確認
50001	サーバ内部エラー	管理者に連絡

5. インターフェース詳細

5.1 インターフェース1：ユーザー情報取得

インターフェースパス：GET /lite_api/v1/iam/user/{user_id}
リクエストパラメータ：

パラメータ名タイプ必須説明
userId Path はいユーザーID

パラメータ名	タイプ	必須	説明
userId	Path	はい	ユーザーID

リクエスト例：

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

レスポンス例：

{
    "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 インターフェース2：ユーザー作成

インターフェースパス：POST /lite_api/v1/iam/user/
リクエストパラメータ：

パラメータ名タイプ必須説明
username string はいユーザー名
email string はいメール
real_name string はい本名

パラメータ名	タイプ	必須	説明
username	string	はい	ユーザー名
email	string	はい	メール
real_name	string	はい	本名

リクエスト例：

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

レスポンス例：

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

5.3 インターフェース3：アシスタント作成

インターフェースパス：POST /lite_api/v1/robots/

リクエストパラメータ：

パラメータ名	タイプ	必須	説明
info	object	はい	アシスタント情報および名称
masks	array	いいえ	アシスタントマスク
knowledge_bases	array	いいえ	ナレッジベース
skills	array	いいえ	スキル
mcps	array	いいえ	データモデル
data_sources	array	いいえ	データソース
keywords_filter	object	いいえ	キーワードフィルター
feedback_accounts	array	いいえ	フィードバックアカウント

リクエスト例：

{
    "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": []
}

レスポンス例

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

5.4 インターフェース4：アシスタント取得

インターフェースパス：POST /lite_api/v1/robots/{robot_id}
リクエストパラメータ：

パラメータ名	タイプ	必須	説明
robot_id	string	はい	アシスタントID
internal_use	boolean	いいえ	内部使用かどうか

リクエスト例：

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

レスポンス例：

{
    "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 インターフェース5：ファイルアップロード

インターフェースパス：POST /Api/Workspace/File/UploadFiles
リクエストパラメータ：

パラメータ名	タイプ	必須	説明
Files	array	いいえ	今回アップロードするファイル
WorkspaceId	string	いいえ	string
FullPath	string	いいえ	ファイルをアップロードする完全パス
IsCover	boolean	いいえ	システムアップロードかどうか
UserId	integer	いいえ	ユーザーID（公開API用）
UserEmail	string	いいえ	ユーザーメール（公開API用）
OCRMode	string	いいえ	OCRモード

レスポンス例：

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

6. セキュリティ規範

認証方式：OAuth2.0/JWT/APIキー。
データ暗号化：パスワードなどの機密フィールドは暗号化して送信すること。

レート制限ポリシー：インターフェース呼び出し頻度の制限は以下の表を参照。

シナリオ	一般的な制限	説明
公開API（例：サードパーティ呼び出し）	10~100 回/分	例：WeChat Pay、Alipay公開APIは通常50~200回/分の制限（インターフェースレベルによる）。
内部システムAPI	100~1000 回/分	内部サービス間呼び出しは緩和可能だが、単一サービスの過剰リソース占有は避ける。
ユーザー操作インターフェース	5~60 回/分	例：ログイン、SMS送信などの敏感操作は厳格に制限（SMS認証コードインターフェースは通常1回/60秒）。
データクエリインターフェース	100~5000 回/分	高頻度クエリは緩和可能だが、キャッシュと連携してDB負荷を軽減する必要あり。
高並列コアインターフェース	動的レート制限（例：トークンバケットアルゴリズム）	例：EC秒殺インターフェースは回路遮断機構や弾性スケーリングと組み合わせることがある。

インターフェース標準ドキュメント

1. ドキュメント情報​

2. 改訂履歴​

3. 概要​

3.1 ドキュメント目的​

3.2 用語と略語​

3.3 インターフェース設計原則​

4. 共通規範​

4.1 リクエスト規範​

4.2 レスポンス規範​

4.3 エラーコード表​

5. インターフェース詳細​

5.1 インターフェース1：ユーザー情報取得​

5.2 インターフェース2：ユーザー作成​

5.3 インターフェース3：アシスタント作成​

5.4 インターフェース4：アシスタント取得​

5.5 インターフェース5：ファイルアップロード​

6. セキュリティ規範​

1. ドキュメント情報

2. 改訂履歴

3. 概要

3.1 ドキュメント目的

3.2 用語と略語

3.3 インターフェース設計原則

4. 共通規範

4.1 リクエスト規範

4.2 レスポンス規範

4.3 エラーコード表

5. インターフェース詳細

5.1 インターフェース1：ユーザー情報取得

5.2 インターフェース2：ユーザー作成

5.3 インターフェース3：アシスタント作成

5.4 インターフェース4：アシスタント取得

5.5 インターフェース5：ファイルアップロード

6. セキュリティ規範