問い合わせ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	-	会社名
`inquirer_department`	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": "株式会社サンプル",
    "inquirer_department": "営業部"
  }'

レスポンス例（成功時）


{
  "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="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://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キーはサーバーサイドで管理し、クライアントに公開しないでください。