Skip to main content

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

1. ドキュメント情報​

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

2. 改訂履歴​

バージョン改訂日改訂内容
v1.02025-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}

  • リクエストパラメータ：

    パラメータ名型必須説明
    userIdPathはいユーザー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/

  • リクエストパラメータ：

    パラメータ名型必須説明
    usernamestringはいユーザー名
    emailstringいいえメールアドレス
    real_namestringいいえ本名

  • リクエスト例：

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

  • レスポンス例：

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

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

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

  • リクエストパラメータ：

    パラメータ名型必須説明
    infoobjectはいアシスタント情報と名称
    masksarrayいいえアシスタントマスク
    knowledge_basesarrayいいえナレッジベース
    skillsarrayいいえスキル
    mcpsarrayいいえデータモデル
    data_sourcesarrayいいえデータソース
    keywords_filterobjectいいえキーワードフィルター
    feedback_accountsarrayいいえフィードバックアカウント

    リクエスト例：

    {
        "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_idstringはいアシスタントID
internal_usebooleanいいえ内部利用かどうか

  • リクエスト例：

    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

  • リクエストパラメータ：

パラメータ名型必須説明
Filesarrayいいえ今回アップロードするファイル
WorkspaceIdstringいいえstring
FullPathstringいいえファイルをアップロードするフルパス
IsCoverbooleanいいえシステムアップロードかどうか
UserIdintegerいいえユーザーID（公開API用）
UserEmailstringいいえユーザーメール（公開API用）
OCRModestringいいえOCRモード
  • レスポンス例：
{
    "success": true,
    "msg": "string",
    "data": [
        {
            "workspaceId": 0,
            "fullName": "string",
            "id": 0
        }
    ]
}

6. セキュリティ規約​

  • 認証方式：OAuth2.0/JWT/API Key。

  • データ暗号化：パスワードなどの機密フィールドは暗号化して送信する必要があります。

  • レートリミット戦略：インターフェース呼び出し頻度の制限は下表を参照。

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