# Formchan フォーム連携仕様書

この仕様書と、Formchanの管理画面で取得した専用の送信先URLを開発AIに渡してください。
Formchanはフォームの送信を受け付け、管理画面への保存、AIによる仕分け、通知を行うサービスです。
この仕様書はWebサイト側のフォーム連携を対象とします。

## 開発AIへの指示

1. ユーザーから渡された専用の送信先URLを `FORM_ACTION_URL` に使用してください。`YOUR_FORM_KEY` などの仮の値を作って本番に使用しないでください。URLが未提供なら確認してください。
2. 既存のサイトの構成・フォームのデザイン・必須項目・アクセシビリティを確認し、送信先の接続に必要な変更を行ってください。
3. フォームがなければ、サイトのデザインに合わせて作成してください。
4. ブラウザから直接POSTできます。Formchanへの連携だけを目的とした独自の送信サーバーやAPIキーは不要です。
5. 送信中表示、二重送信の防止、成功・エラー表示を実装してください。エラー時は入力内容を保持し、再送できるようにしてください。
6. 実際のサイトからテスト送信し、受信箱で確認できるところまで検証してください。料金プランや通知設定の変更は、この連携作業に含めないでください。

## 送信先とリクエスト

- メソッド：`POST`
- URL：管理画面で取得した専用の送信先URL（例：`https://YOUR_FORMCHAN_HOST/f/YOUR_FORM_KEY`）
- 認証：専用URLへのフォーム送信には、ログインや認証ヘッダーは不要
- 形式：HTMLフォームのURLエンコード、`FormData`、JSONオブジェクト
- JavaScriptで送信結果を受け取る場合：`Accept: application/json`
- `FormData`を使う場合、`Content-Type`は手動で設定しない（ブラウザがboundaryを設定する）
- JSONの場合：`Content-Type: application/json` と `JSON.stringify({...})`
- ファイル添付は非対応。送信項目には文字列を使用する

## 入力項目

| name属性 | 用途 |
| --- | --- |
| `name` | 送信者の名前 |
| `email` | 返信先のメールアドレス |
| `message` | 問い合わせ本文 |
| 任意の名前（例：`company`、`subject`） | 追加項目。受信箱と通知メールに表示 |
| `_gotcha` | ボット対策用の非表示項目。通常の利用者は空欄のまま送信 |
| `_next` | HTML送信後の移動先URL。指定は任意 |

`email`の別名として`mail`、`_replyto`など、`name`の別名として`fullname`なども認識します。新しく作成するフォームでは`name`、`email`、`message`を推奨します。
すべての項目が空の場合はエラーです。返信先が必要なフォームでは、サイト側で`email`を必須にしてください。

送信サイズは64KB以内、項目数は50以内、各項目の値は5,000文字以内にしてください。51個目以降の項目や5,000文字を超えた部分は保存されません。

## 最小のHTMLフォーム

`FORM_ACTION_URL`をユーザーの専用URLに置き換えてください。

```html
<form id="contact-form" action="FORM_ACTION_URL" method="POST">
  <label>お名前 <input name="name" autocomplete="name"></label>
  <label>メールアドレス <input name="email" type="email" autocomplete="email" required></label>
  <label>お問い合わせ内容 <textarea name="message" maxlength="5000" required></textarea></label>
  <input name="_gotcha" style="display:none" tabindex="-1" autocomplete="off" aria-hidden="true">
  <button type="submit">送信する</button>
</form>
<p id="form-status" role="status" aria-live="polite"></p>
```

HTMLで通常送信した場合はFormchanの送信完了ページを表示します。JavaScriptを併用しない場合でも送信できます。

## ページ内で完了表示するJavaScriptの例

```js
const form = document.getElementById('contact-form');
const status = document.getElementById('form-status');
let sending = false;

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  if (sending) return;
  sending = true;
  const button = form.querySelector('button[type="submit"]');
  button.disabled = true;
  status.textContent = '送信しています…';
  try {
    const response = await fetch(form.action, {
      method: 'POST',
      headers: { Accept: 'application/json' },
      body: new FormData(form),
    });
    const data = await response.json();
    if (!response.ok || data.ok !== true) throw new Error(data.error || 'send_failed');
    status.textContent = '送信しました。お問い合わせありがとうございます。';
    form.reset();
  } catch {
    status.textContent = '送信できませんでした。時間をおいて再度お試しください。';
  } finally {
    sending = false;
    button.disabled = false;
  }
});
```

Reactなどを使う場合も同じリクエスト仕様で実装できます。ネイティブのform検証と、フレームワークの既存の状態管理を利用してください。

## JSON応答

成功時：HTTP 200、`{"ok":true}`。
失敗時：`{"ok":false,"error":"エラーコード"}`。

| HTTP | error | 内容 |
| --- | --- | --- |
| 404 | `not_found` | フォームが存在しない、またはアーカイブ済み |
| 403 | `origin` | 送信元サイトが許可されていない |
| 429 | `rate` | 短時間の送信回数が制限に達した |
| 400 | `body` | データを読み取れない、または送信サイズが上限を超えた |
| 400 | `empty` | 送信内容がすべて空 |

成功応答は受付完了を意味します。AI判定や通知は応答後に行うため、フロントエンドでAI処理を待つ必要はありません。応答に要約・タグ・重要度は含まれません。

## 送信後のページ

HTML送信で自分の完了ページに移動させる場合は、次の項目を追加します。

```html
<input type="hidden" name="_next" value="https://YOUR_SITE/thanks">
```

`_next`はHTTPまたはHTTPSのURLを指定します。フォームで送信許可サイトを設定している場合は、許可サイト内のURLにしてください。JavaScriptでJSON応答を取得する場合は、`_next`による移動は行われません。必要な画面遷移はフロントエンドで実装してください。

## 送信元の許可とスパム対策

- フォーム設定で送信を許可するサイトを指定できます。設定後は、それ以外のOriginやOriginのないリクエストは拒否されます。
- 開発用Origin（例：`http://localhost:5173`）と本番のOrigin（例：`https://YOUR_SITE`）を必要に応じて登録してください。
- ブラウザからのCORS送信とOPTIONSに対応しています。フロントエンドからのリクエストに認証情報や独自のヘッダーを追加する必要はありません。
- `_gotcha`に値が入った送信は、成功応答を返しますが問い合わせとして保存しません。テスト送信では空欄にしてください。

## 連携先別の注意

- HTML：actionを専用URL、methodをPOSTに設定。
- WordPress：カスタムHTMLブロックで利用可能。既存のフォームプラグインは独自の送信処理があるため、送信先変更や別途の連携が可能か確認。
- Webflow：フォームのActionに専用URL、MethodにPOSTを設定。
- React / Next.jsなど：上記のfetchとFormData、またはJSON送信を使用。フォーム送信のためだけに新しいバックエンドを作る必要はない。

## 検証チェックリスト

- 専用URLのプレースホルダーがすべて実際のURLに置き換わっている。
- 各入力欄にlabelがあり、キーボードで操作できる。
- emailの検証と必須項目の検証が働く。
- 送信中に二重送信できない。
- 成功表示とエラー表示があり、エラー時に入力内容が消えない。
- 実際のサイトから送信して、Formchanの受信箱に届く。
- 開発環境と本番環境の送信元が許可されている。
- 通知先を設定・認証済みの場合は、通知も確認する。テスト用の連続送信や実在しない宛先への通知は避ける。