問い合わせAPI
外部のWebサイトからTWPの問い合わせ管理システムに問い合わせを作成するAPIです。
ユースケース
- コーポレートサイトのお問い合わせフォーム
- ランディングページからのリード獲得
- 外部システムからの問い合わせ連携
エンドポイント一覧
| メソッド | パス | 説明 |
|---|---|---|
| POST | /v1/inquiries | 問い合わせ作成 |
| GET | /v1/inquiries/categories | カテゴリ一覧取得 |
問い合わせ作成
POST /v1/inquiries新しい問い合わせを作成します。
必要な権限
テナントAPIキーに inquiry:create 権限が必要です。
このAPIは外部システム連携用のため、テナントAPIキー(X-API-Key)でのみ利用できます。MCP接続(OAuth)や個人用APIキーには inquiry:create 権限を付与できず、これらの資格情報でリクエストすると 403 が返ります。
リクエストボディ
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
category_code | string | ○ | 問い合わせカテゴリコード |
title | string | ○ | 件名 |
content | string | ○ | 問い合わせ内容 |
priority | number | - | 優先度(1: 高、2: 中、3: 低)。省略時は 2(中) |
inquirer_name | string | ○ | お問い合わせ者名 |
inquirer_email | string | ○ | メールアドレス |
inquirer_phone | string | - | 電話番号 |
inquirer_company | string | - | 会社名 |
inquirer_department | string | - | 部署名 |
source | string | - | 流入元コード。どのフォーム・どのサイトから送られたかを表す識別子。英数字・ハイフン・アンダースコアのみ、50文字以内。省略可(省略すると問い合わせ一覧では「未設定」になります) |
流入元(source)の決め方
フォーム・サイトごとに固定のコードを決めて送ってください。問い合わせ一覧ではこのコードで絞り込めます。
- 送信経路が増えるたびに新しいコードを足すだけで、TWP側の設定は不要です(届いたコードがそのまま絞り込みの選択肢になります)
- 件名に流入元を書き込む運用は避けてください。書式が揺れると絞り込みに使えません
- 経路ごとに同じ綴りのコードを送り続けることが重要です(
contact_formとcontactformは別の流入元として集計されます)
例: corporate_contact(コーポレートサイトの問い合わせフォーム)、ai_assessment(診断ツールからの送信)、solution_site(別サイトからの送信)
リクエスト例
curl -X POST "https://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": "株式会社サンプル",
"inquirer_department": "営業部",
"source": "corporate_contact"
}'レスポンス例(成功時)
{
"id": "inq-550e8400-e29b-41d4-a716-446655440000",
"category_code": "general",
"title": "サービスについてのお問い合わせ",
"status": "new",
"source": "corporate_contact",
"created_at": "2024-01-15T10:00:00Z",
"message": "問い合わせを受け付けました。"
}HTTPステータスは 201 です。source には記録された流入元コードがそのまま返ります(省略した場合は null)。流入元が確かに記録されたかは、この値で確認できます。
バリデーションエラー
{
"error": {
"code": "VALIDATION_ERROR",
"message": "入力内容に誤りがあります。",
"details": [
{
"field": "inquirer_email",
"message": "メールアドレスの形式が正しくありません"
}
]
}
}カテゴリ一覧取得
GET /v1/inquiries/categories問い合わせカテゴリの一覧を取得します。フォームのカテゴリ選択肢の表示に使用できます。
必要な権限
テナントAPIキーに inquiry:create 権限が必要です。
このAPIは外部システム連携用のため、テナントAPIキー(X-API-Key)でのみ利用できます。MCP接続(OAuth)や個人用APIキーには inquiry:create 権限を付与できず、これらの資格情報でリクエストすると 403 が返ります。
レスポンス例
{
"categories": [
{
"category_code": "general",
"title": "一般的なお問い合わせ",
"description": "サービス全般に関するお問い合わせ"
},
{
"category_code": "support",
"title": "技術サポート",
"description": "技術的な問題に関するお問い合わせ"
},
{
"category_code": "sales",
"title": "お見積り・ご契約",
"description": "料金やご契約に関するお問い合わせ"
}
]
}返るのは有効なカテゴリだけです。問い合わせ作成時の category_code には、ここで返った category_code を指定してください。存在しない・無効なカテゴリを指定すると 422 VALIDATION_ERROR になります。
実装例
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="inquirer_department" 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://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キーはサーバーサイドで管理し、クライアントに公開しないでください。