問い合わせAPI
外部のWebサイトからTWPの問い合わせ管理システムに問い合わせを作成するAPIです。
ユースケース
- コーポレートサイトのお問い合わせフォーム
- ランディングページからのリード獲得
- 外部システムからの問い合わせ連携
エンドポイント一覧
| メソッド | パス | 説明 |
|---|---|---|
| POST | /v1/inquiries | 問い合わせ作成 |
| GET | /v1/inquiries/categories | カテゴリ一覧取得 |
問い合わせ作成
POST /v1/inquiries新しい問い合わせを作成します。
必要な権限
APIキーに inquiry:create 権限が必要です。
リクエストボディ
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
category_code | string | ○ | 問い合わせカテゴリコード |
title | string | ○ | 件名 |
content | string | ○ | 問い合わせ内容 |
priority | number | - | 優先度(1: 低、2: 中、3: 高) |
inquirer_name | string | ○ | お問い合わせ者名 |
inquirer_email | string | ○ | メールアドレス |
inquirer_phone | string | - | 電話番号 |
inquirer_company | string | - | 会社名 |
リクエスト例
curl -X POST "https://your-tenant.api.tocca.systems/v1/inquiries" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"category_code": "general",
"title": "サービスについてのお問い合わせ",
"content": "御社のサービスについて詳しく教えてください。",
"inquirer_name": "山田太郎",
"inquirer_email": "yamada@example.com",
"inquirer_company": "株式会社サンプル"
}'レスポンス例(成功時)
{
"id": "inq-550e8400-e29b-41d4-a716-446655440000",
"category_code": "general",
"title": "サービスについてのお問い合わせ",
"status": "open",
"created_at": "2024-01-15T10:00:00Z",
"message": "Inquiry created successfully"
}バリデーションエラー
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{
"field": "inquirer_email",
"message": "メールアドレスの形式が正しくありません"
}
]
}
}カテゴリ一覧取得
GET /v1/inquiries/categories問い合わせカテゴリの一覧を取得します。フォームのカテゴリ選択肢の表示に使用できます。
必要な権限
APIキーに inquiry:create 権限が必要です。
レスポンス例
{
"categories": [
{
"code": "general",
"name": "一般的なお問い合わせ",
"description": "サービス全般に関するお問い合わせ"
},
{
"code": "support",
"name": "技術サポート",
"description": "技術的な問題に関するお問い合わせ"
},
{
"code": "sales",
"name": "お見積り・ご契約",
"description": "料金やご契約に関するお問い合わせ"
}
]
}実装例
HTMLフォーム + JavaScript
<form id="inquiry-form">
<select name="category_code" required>
<option value="">カテゴリを選択</option>
<!-- カテゴリ一覧APIから動的に生成 -->
</select>
<input type="text" name="inquirer_name" placeholder="お名前" required />
<input type="email" name="inquirer_email" placeholder="メールアドレス" required />
<input type="text" name="inquirer_company" placeholder="会社名" />
<input type="text" name="title" placeholder="件名" required />
<textarea name="content" placeholder="お問い合わせ内容" required></textarea>
<button type="submit">送信</button>
</form>
<script>
document.getElementById('inquiry-form').addEventListener('submit', async (e) => {
e.preventDefault();
const formData = new FormData(e.target);
const data = Object.fromEntries(formData);
// APIキーはサーバーサイドで管理することを推奨
const response = await fetch('/api/inquiry', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
if (response.ok) {
alert('お問い合わせを受け付けました');
} else {
alert('送信に失敗しました');
}
});
</script>サーバーサイド(Node.js / Express)
const express = require('express');
const app = express();
const TWP_API_KEY = process.env.TWP_API_KEY;
const TWP_API_URL = 'https://your-tenant.api.tocca.systems';
app.post('/api/inquiry', async (req, res) => {
try {
const response = await fetch(`${TWP_API_URL}/v1/inquiries`, {
method: 'POST',
headers: {
'X-API-Key': TWP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(req.body),
});
const data = await response.json();
if (response.ok) {
res.json({ success: true, id: data.id });
} else {
res.status(response.status).json(data);
}
} catch (error) {
res.status(500).json({ error: 'Internal server error' });
}
});セキュリティ上の注意
スパム対策
問い合わせフォームにはスパム対策を実装してください。
- reCAPTCHA等のCAPTCHA
- ハニーポットフィールド
- レート制限
入力値の検証
APIに送信する前に、クライアント側でも入力値を検証してください。
APIキーの保護
APIキーはサーバーサイドで管理し、クライアントに公開しないでください。