インターフェース標準ドキュメント
インターフェース標準ドキュメント
1. ドキュメント情報
- ドキュメント名:SERVICEMEシステム インターフェース標準ドキュメント
- バージョン:v1.1
- 公開日:2026-06-05
- 適用範囲:企業向けインテリジェントシナリオに適用され、認証、ナレッジQ&A、プロセス自動化、データ分析、コンテンツ生成などをサポートします。インターフェースは標準RESTfulアーキテクチャを採用し、システム連携およびクロスプラットフォーム利用を容易にし、カスタマーサービス、マーケティング、財務、人事などの業務領域で広く利用され、協業効率とインテリジェントな意思決定を向上させます。
2. 改訂履歴
| バージョン | 改訂日 | 改訂内容 |
|---|---|---|
| v1.0 | 2025-07-18 | 初版 |
| v1.1 | 2026-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/jsonAuthorization: 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} -
リクエストパラメータ:
パラメータ名 型 必須 説明 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": "",
"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 | いいえ | ワークスペースID |
| 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
}
]
}
5.6 インターフェース6:ナレッジベース一覧取得
-
インターフェースパス:GET /knowledge/v1/kb/me
-
リクエストパラメータ:
パラメータ名 型 必須 説明 locale Header いいえ 言語ロケール。デフォルトは 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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 name array はい ナレッジベース名(多言語配列) description array はい ナレッジベース説明(多言語配列) sort integer いいえ 並び順 quota object いいえ ナレッジベース容量設定 parent_id string いいえ 親ナレッジベースID mode integer いいえ ナレッジベースモード。デフォルト 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_id Path はい ナレッジベースID locale Header いいえ 言語ロケール。デフォルトは 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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 workspaceId Query はい 所属ナレッジベースID name string はい フォルダー名 fullPath string はい フォルダーのフルパス -
リクエスト例:
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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 workspaceId integer はい 所属ナレッジベースID ignore_folder_ids array いいえ 無視するフォルダー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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 PageIndex integer いいえ ページ番号。デフォルト 1PageSize integer いいえ 1ページ件数。デフォルト 20OrderField string いいえ ソート項目。デフォルト modifiedOrderType string いいえ ソート順。デフォルト descConditions array いいえ 検索条件一覧 -
リクエスト例:
{
"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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 c Query はい コンテナ名 n Query はい ファイル名またはBlob名 u Query はい ユーザーID s Query いいえ ソースシステム。デフォルト ecmw Query いいえ 透かしユーザー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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 fileId integer はい ファイルID objectType integer はい オブジェクトタイプ -
リクエスト例:
{
"fileId": 7001,
"objectType": 1
} -
レスポンス例:
{
"downloadUrl": "https://example.com/download/7001",
"fileName": "製品紹介.pdf"
}
5.14 インターフェース14:Q&A作成
-
インターフェースパス:POST /knowledge/v1/qna
-
リクエストパラメータ:
パラメータ名 型 必須 説明 answer string はい 標準回答 enable boolean いいえ 有効化するか。デフォルト trueworkspaceId integer はい 所属ナレッジベースID questions array はい 質問一覧 metadataExpansion object いいえ 拡張メタデータ -
リクエスト例:
{
"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
-
リクエストパラメータ:
パラメータ名 型 必須 説明 PageIndex integer いいえ ページ番号。デフォルト 1PageSize integer いいえ 1ページ件数。デフォルト 20OrderField string いいえ ソート項目。デフォルト modifiedOrderType string いいえ ソート順。デフォルト descConditions array いいえ 検索条件一覧 -
リクエスト例:
{
"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レベルによる)。 内部システムAPI 100〜1000 回/分 サービス間呼び出しは緩和可能だが、単一サービスの過度なリソース占有は回避する。 ユーザー行動API 5〜60 回/分 ログイン・SMS送信などの機微操作は厳格に制限する(例:SMS認証APIは通常 1 回/60秒)。 データ照会API 100〜5000 回/分 高頻度照会APIは緩和可能だが、キャッシュ併用でDB負荷を下げる。 高同時実行のコアAPI 動的レート制御(例:トークンバケット) 例:フラッシュセールでは、サーキットブレーカーやオートスケールと組み合わせる。