Skip to main content

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

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

1. ドキュメント情報

  • ドキュメント名:SERVICEMEシステム インターフェース標準ドキュメント
  • バージョン:v1.1
  • 公開日:2026-06-05
  • 適用範囲:企業向けインテリジェントシナリオに適用され、認証、ナレッジQ&A、プロセス自動化、データ分析、コンテンツ生成などをサポートします。インターフェースは標準RESTfulアーキテクチャを採用し、システム連携およびクロスプラットフォーム利用を容易にし、カスタマーサービス、マーケティング、財務、人事などの業務領域で広く利用され、協業効率とインテリジェントな意思決定を向上させます。

2. 改訂履歴

バージョン改訂日改訂内容
v1.02025-07-18初版
v1.12026-06-05クロスオリジンアクセス仕様(CORS)の説明を追加

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}(認証が必要な場合)。
  • リクエストパラメータ
    • Queryパラメータ(GET)、Bodyパラメータ(POST/PUT)。
    • 必須/任意フィールドの説明。

4.2 レスポンス仕様

  • レスポンス形式

    {
    "code": 200,
    "message": "成功",
    "data": {}
    }
  • HTTPステータスコード

    • 200:成功
    • 400:リクエストパラメータエラー
    • 401:未認証
    • 500:サーバー内部エラー

4.3 エラーコード表

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

4.4 クロスオリジンアクセス仕様(CORS)

4.4.1 背景

Cross-Origin Resource Sharing(CORS)はブラウザのセキュリティ機構であり、Webページが異なるドメインのサーバーへリクエストできるかを制御します。フロントエンドアプリとAPIサービスが異なるドメイン(またはポート)に配置されている場合、ブラウザは自動的にCORS検証を行います。

4.4.2 NEXTバージョンのデフォルト方針

SERVICEME NEXTバージョンでは、デフォルトでクロスオリジンアクセスを許可しません。つまり、ブラウザページからAPIへ直接リクエストした際、Originがサーバー側で許可設定されていない場合はリクエストが拒否されます。

4.4.3 LTSバージョンとの違い

比較項目LTSバージョンNEXTバージョン
クロスオリジン制限制限なし(クロスオリジンを未遮断)デフォルトで禁止
移行影響-LTSからNEXTへ移行後、従来ブラウザ側クロスオリジンAPI呼び出しに依存していた場合、リクエスト失敗が発生

移行時の注意:LTSからNEXTへアップグレードし、フロントエンドでクロスオリジンAPI呼び出しがある場合、アップグレード後はそのままでは動作しません。事前にクロスオリジン設定を申請してください。

4.4.4 対応方法

クロスオリジンアクセスを有効にする必要がある場合は、担当の導入デリバリーチームへ連絡して設定を依頼してください。業務シナリオに応じて許可Originドメインを設定します。

4.4.5 よくある現象

クロスオリジン問題が発生すると、ブラウザ開発者ツール(Console)に以下のようなエラーが表示されることがあります。

  • 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.

同様のエラーが表示される場合、当該リクエストはクロスオリジンポリシーにより制限されています。導入デリバリーチームへお問い合わせください。


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いいえワークスペースID
FullPathstringいいえアップロード先のフルパス
IsCoverbooleanいいえシステムアップロードかどうか
UserIdintegerいいえユーザーID(公開API用)
UserEmailstringいいえユーザーメール(公開API用)
OCRModestringいいえOCRモード
  • レスポンス例:
{
"success": true,
"msg": "string",
"data": [
{
"workspaceId": 0,
"fullName": "string",
"id": 0
}
]
}

5.6 インターフェース6:ナレッジベース一覧取得

  • インターフェースパス:GET /knowledge/v1/kb/me

  • リクエストパラメータ

    パラメータ名必須説明
    localeHeaderいいえ言語ロケール。デフォルトは en-US
  • リクエスト例

    GET /knowledge/v1/kb/me HTTP/1.1
    Authorization: Bearer abcdef123456
    locale: zh-CN
  • レスポンス例

    {
    "code": 200,
    "data": [
    {
    "id": "kb_001",
    "name": "製品ナレッジベース",
    "description": "製品説明、FAQ、操作マニュアルを保管するために使用",
    "mode": 1
    }
    ],
    "message": "success"
    }

5.7 インターフェース7:ナレッジベース作成

  • インターフェースパス:POST /knowledge/v1/kb/knowledge-base

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

    パラメータ名必須説明
    namearrayはいナレッジベース名(多言語配列)
    descriptionarrayはいナレッジベース説明(多言語配列)
    sortintegerいいえ並び順
    quotaobjectいいえナレッジベース容量設定
    parent_idstringいいえ親ナレッジベースID
    modeintegerいいえナレッジベースモード。デフォルト 1
  • リクエスト例

    {
    "name": [
    {
    "locale": "zh-CN",
    "content": "カスタマーサービス ナレッジベース"
    }
    ],
    "description": [
    {
    "locale": "zh-CN",
    "content": "カスタマーサポートQ&Aと業務文書の管理に使用"
    }
    ],
    "sort": 0,
    "mode": 1
    }
  • レスポンス例

    {
    "code": 200,
    "data": {
    "id": "kb_001",
    "name": "カスタマーサービス ナレッジベース"
    },
    "message": "success"
    }

5.8 インターフェース8:ナレッジベース詳細取得

  • インターフェースパス:GET /knowledge/v1/kb/knowledge-base/{kb_id}

  • リクエストパラメータ

    パラメータ名必須説明
    kb_idPathはいナレッジベースID
    localeHeaderいいえ言語ロケール。デフォルトは en-US
  • リクエスト例

    GET /knowledge/v1/kb/knowledge-base/kb_001 HTTP/1.1
    Authorization: Bearer abcdef123456
    locale: zh-CN
  • レスポンス例

    {
    "code": 200,
    "data": {
    "id": "kb_001",
    "name": "カスタマーサービス ナレッジベース",
    "description": "カスタマーサポートQ&Aと業務文書の管理に使用",
    "mode": 1,
    "sort": 0
    },
    "message": "success"
    }

5.9 インターフェース9:ナレッジベースフォルダー作成

  • インターフェースパス:POST /knowledge/v1/file/ekb-folder

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

    パラメータ名必須説明
    workspaceIdQueryはい所属ナレッジベースID
    namestringはいフォルダー名
    fullPathstringはいフォルダーのフルパス
  • リクエスト例

    POST /knowledge/v1/file/ekb-folder?workspaceId=1001 HTTP/1.1
    Authorization: Bearer abcdef123456
    Content-Type: application/json

    {
    "name": "製品マニュアル",
    "fullPath": "/顧客資料/製品マニュアル"
    }
  • レスポンス例

    {
    "code": 200,
    "data": {
    "id": 501,
    "name": "製品マニュアル",
    "fullPath": "/顧客資料/製品マニュアル"
    },
    "message": "success"
    }

5.10 インターフェース10:ナレッジベースディレクトリツリー取得

  • インターフェースパス:POST /knowledge/v1/file/ekb-folder-tree

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

    パラメータ名必須説明
    workspaceIdintegerはい所属ナレッジベースID
    ignore_folder_idsarrayいいえ無視するフォルダーID一覧
  • リクエスト例

    {
    "workspaceId": 1001,
    "ignore_folder_ids": [
    999
    ]
    }
  • レスポンス例

    {
    "code": 200,
    "data": [
    {
    "id": 501,
    "name": "顧客資料",
    "children": [
    {
    "id": 502,
    "name": "製品マニュアル"
    }
    ]
    }
    ],
    "message": "success"
    }

5.11 インターフェース11:ナレッジベースファイル一覧取得

  • インターフェースパス:POST /knowledge/v1/file/ekb-pagelist

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

    パラメータ名必須説明
    PageIndexintegerいいえページ番号。デフォルト 1
    PageSizeintegerいいえ1ページ件数。デフォルト 20
    OrderFieldstringいいえソート項目。デフォルト modified
    OrderTypestringいいえソート順。デフォルト desc
    Conditionsarrayいいえ検索条件一覧
  • リクエスト例

    {
    "PageIndex": 1,
    "PageSize": 20,
    "OrderField": "modified",
    "OrderType": "desc",
    "Conditions": [
    {
    "fieldName": "workspaceId",
    "fieldValue": "1001"
    }
    ]
    }
  • レスポンス例

    {
    "code": 200,
    "data": {
    "items": [
    {
    "id": 7001,
    "name": "製品紹介.pdf",
    "objectType": 1,
    "modified": "2026-05-17T10:00:00Z"
    }
    ],
    "total": 1
    },
    "message": "success"
    }

5.12 インターフェース12:ナレッジベースファイルプレビュー

  • インターフェースパス:GET /knowledge/v1/file/ekb-preview

  • リクエストパラメータ

    パラメータ名必須説明
    cQueryはいコンテナ名
    nQueryはいファイル名またはBlob名
    uQueryはいユーザーID
    sQueryいいえソースシステム。デフォルト ecm
    wQueryいいえ透かしユーザーID
  • リクエスト例

    GET /knowledge/v1/file/ekb-preview?c=docs&n=abc123%2F製品紹介.pdf&u=10001&s=ecm HTTP/1.1
    Authorization: Bearer abcdef123456
  • レスポンス例

    {
    "previewUrl": "https://example.com/preview/abc123",
    "expireAt": "2026-05-17T12:00:00Z"
    }

5.13 インターフェース13:ナレッジベースファイルダウンロード

  • インターフェースパス:POST /knowledge/v1/file/download

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

    パラメータ名必須説明
    fileIdintegerはいファイルID
    objectTypeintegerはいオブジェクトタイプ
  • リクエスト例

    {
    "fileId": 7001,
    "objectType": 1
    }
  • レスポンス例

    {
    "downloadUrl": "https://example.com/download/7001",
    "fileName": "製品紹介.pdf"
    }

5.14 インターフェース14:Q&A作成

  • インターフェースパス:POST /knowledge/v1/qna

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

    パラメータ名必須説明
    answerstringはい標準回答
    enablebooleanいいえ有効化するか。デフォルト true
    workspaceIdintegerはい所属ナレッジベースID
    questionsarrayはい質問一覧
    metadataExpansionobjectいいえ拡張メタデータ
  • リクエスト例

    {
    "answer": "システムにログイン後、『私の申請』で承認進捗を確認してください。",
    "enable": true,
    "workspaceId": 1001,
    "questions": [
    {
    "content": "申請の進捗はどうやって確認できますか?",
    "sort": 0
    }
    ]
    }
  • レスポンス例

    {
    "code": 200,
    "data": {
    "id": 9001,
    "workspaceId": 1001,
    "enable": true
    },
    "message": "success"
    }

5.15 インターフェース15:Q&A一覧取得

  • インターフェースパス:POST /knowledge/v1/qna/pagelist

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

    パラメータ名必須説明
    PageIndexintegerいいえページ番号。デフォルト 1
    PageSizeintegerいいえ1ページ件数。デフォルト 20
    OrderFieldstringいいえソート項目。デフォルト modified
    OrderTypestringいいえソート順。デフォルト desc
    Conditionsarrayいいえ検索条件一覧
  • リクエスト例

    {
    "PageIndex": 1,
    "PageSize": 20,
    "OrderField": "modified",
    "OrderType": "desc",
    "Conditions": [
    {
    "fieldName": "workspaceId",
    "fieldValue": "1001"
    }
    ]
    }
  • レスポンス例

    {
    "code": 200,
    "data": {
    "items": [
    {
    "id": 9001,
    "question": "申請の進捗はどうやって確認できますか?",
    "answer": "システムにログイン後、『私の申請』で承認進捗を確認してください。",
    "enable": true
    }
    ],
    "total": 1
    },
    "message": "success"
    }

6. セキュリティ仕様

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

  • データ暗号化:機密フィールドは暗号化して送信すること(例:パスワード)。

  • レート制限:インターフェース呼び出し頻度の目安は次表を参照してください。

    シナリオ一般的な制限説明
    公開API(第三者呼び出し)10〜100 回/分例:WeChat Pay・Alipay の公開APIは通常 50〜200 回/分(具体値はAPIレベルによる)。
    内部システムAPI100〜1000 回/分サービス間呼び出しは緩和可能だが、単一サービスの過度なリソース占有は回避する。
    ユーザー行動API5〜60 回/分ログイン・SMS送信などの機微操作は厳格に制限する(例:SMS認証APIは通常 1 回/60秒)。
    データ照会API100〜5000 回/分高頻度照会APIは緩和可能だが、キャッシュ併用でDB負荷を下げる。
    高同時実行のコアAPI動的レート制御(例:トークンバケット)例:フラッシュセールでは、サーキットブレーカーやオートスケールと組み合わせる。