🚀 API概要
AIカスタマーサービスAPIは、RESTfulな設計に基づいたHTTP APIです。
JSON形式でのデータ交換により、既存システムとの簡単な連携を実現します。
ベースURL: https://api.acs.example.com/v1
プロトコル: HTTPS必須
データ形式: JSON
文字エンコード: UTF-8
主な機能
- 💬 問い合わせに対するAI応答生成
- 🛡️ NGパターンによる不適切回答の防止
- 🌍 10言語の自動言語検出・対応
- 📊 応答パフォーマンス分析
- ⚡ 5秒以内の高速応答保証
🔐 認証
APIアクセスには、企業登録時に発行されるAPI Keyを使用します。
すべてのリクエストで、Authorization ヘッダーにBearer tokenとして含める必要があります。
Authorization: Bearer YOUR_API_KEY
⚠️ セキュリティについて
API Keyは機密情報です。クライアントサイドのコードに直接埋め込まず、
サーバーサイドでの実装を推奨します。
🔗 エンドポイント一覧
POST
/inquiries
問い合わせ処理
顧客からの問い合わせに対してAI応答を生成します。
GET
/inquiries
問い合わせ履歴取得
過去の問い合わせ履歴を取得します。
GET
/ng-patterns
NGパターン一覧
登録されているNGパターンの一覧を取得します。
POST
/ng-patterns
NGパターン追加
新しいNGパターンを追加します。
GET
/analytics
分析データ取得
利用統計や応答パフォーマンスのデータを取得します。
💬 問い合わせAPI
POST /inquiries
顧客からの問い合わせに対してAI応答を生成します。
リクエストパラメータ
| パラメータ |
型 |
必須 |
説明 |
inquiry |
string |
必須 |
問い合わせ内容（最大2000文字） |
customer_id |
string |
任意 |
顧客識別子 |
language |
string |
任意 |
言語コード（自動検出される場合は省略可） |
context |
object |
任意 |
追加のコンテキスト情報 |
リクエスト例
curl -X POST https://api.acs.example.com/v1/inquiries \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inquiry": "製品の返品方法を教えてください",
"customer_id": "customer_12345",
"language": "ja"
}'
成功レスポンス（200 OK）
{
"status": "success",
"data": {
"id": "inq_789abc123def",
"response": "返品につきましては、購入から30日以内であれば承っております。...",
"response_type": "ai_generated",
"detected_language": "ja",
"processing_time_ms": 1250,
"confidence_score": 0.95,
"ng_pattern_matched": false
}
}
NGパターン検出レスポンス（200 OK）
{
"status": "ng_detected",
"data": {
"id": "inq_789abc123def",
"response": null,
"response_type": "ng_detected",
"detected_language": "ja",
"processing_time_ms": 450,
"ng_pattern_matched": true,
"matched_pattern": "個人情報を教えてください",
"confidence_score": 0.92,
"escalation_reason": "機密情報に関する問い合わせのため、人間のオペレーターへエスカレーションします。"
}
}
🛡️ NGパターンAPI
GET /ng-patterns
登録されているNGパターンの一覧を取得します。
curl -X GET https://api.acs.example.com/v1/ng-patterns \
-H "Authorization: Bearer YOUR_API_KEY"
POST /ng-patterns
新しいNGパターンを追加します。
curl -X POST https://api.acs.example.com/v1/ng-patterns \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pattern_text": "個人情報を教えてください",
"category": "個人情報要求",
"language_code": "ja",
"confidence_threshold": 0.9
}'
📊 分析API
GET /analytics
利用統計や応答パフォーマンスのデータを取得します。
curl -X GET "https://api.acs.example.com/v1/analytics?period=7d" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"status": "success",
"data": {
"period": "7d",
"total_inquiries": 1250,
"ai_responses": 1100,
"ng_detections": 45,
"escalations": 105,
"avg_response_time_ms": 1450,
"languages_detected": {
"ja": 800,
"en": 300,
"zh": 100,
"ko": 50
}
}
}
⚠️ エラーハンドリング
HTTPステータスコード
| ステータス |
説明 |
200 |
成功 |
400 |
不正なリクエスト |
401 |
認証エラー |
403 |
権限不足 |
429 |
レート制限超過 |
500 |
サーバーエラー |
エラーレスポンス例
{
"status": "error",
"error": {
"code": "INVALID_API_KEY",
"message": "提供されたAPI Keyが無効です",
"details": "API Keyを確認してください"
}
}
💻 実装例
JavaScript (Node.js)
const axios = require('axios');
async function askAI(inquiry, customerId = null) {
try {
const response = await axios.post('https://api.acs.example.com/v1/inquiries', {
inquiry: inquiry,
customer_id: customerId
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
return response.data;
} catch (error) {
console.error('API Error:', error.response.data);
throw error;
}
}
// 使用例
askAI('製品の使い方を教えてください', 'customer_123')
.then(result => console.log(result))
.catch(error => console.error(error));
Python
import requests
import json
class ACSClient:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = "https://api.acs.example.com/v1"
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
def ask_ai(self, inquiry, customer_id=None, language=None):
payload = {"inquiry": inquiry}
if customer_id:
payload["customer_id"] = customer_id
if language:
payload["language"] = language
response = requests.post(
f"{self.base_url}/inquiries",
headers=self.headers,
json=payload
)
return response.json()
# 使用例
client = ACSClient("YOUR_API_KEY")
result = client.ask_ai("サポートが必要です", "customer_123")
print(result)
📦 SDK・ライブラリ
開発効率向上のため、主要な言語向けのSDKを提供予定です。
提供予定のSDK:
• JavaScript/Node.js SDK
• Python SDK
• PHP SDK
• Java SDK
• .NET SDK
SDKリリースまでは、上記の実装例を参考にHTTP APIを直接ご利用ください。