お問い合わせAPIの共通仕様¶
AWS版と自前サーバー版は、入力検証、Turnstileの検証、送信枠の確保、SMTP送信、結果判定に同じ処理を使う。バックエンドは配置時に選び、ブラウザーから選択するパラメーターは設けない。
接続先と要求¶
内部の受付パスは両方式ともPOST /contactである。AWS版はAPI Gatewayの出力URL、自前版は公開プロキシのhttps://www.tectas.co.jp/api/contactなどを、サイトのPUBLIC_CONTACT_API_URLに設定する。公開パスが異なっても要求・応答の形式は変えない。
Content-Type: application/jsonと、許可したサイトのOriginを必要とする。本文の上限はUTF-8で32 KiB。未知の項目を含む要求は拒否する。Cookieや投稿者のログイン認証は使わず、Turnstileと件数制限を併用する。
{
"requestId": "a6d3e034-1dd7-49c8-83d0-20b5d05363be",
"turnstileToken": "ブラウザーで取得したトークン",
"category": "その他",
"company": "",
"name": "テスト 太郎",
"email": "visitor@example.com",
"phone": "",
"message": "問い合わせ本文",
"consent": true
}
入力項目の文字数と必須条件は仕様書に従う。requestIdはUUID v4、turnstileTokenは1〜2048文字、consentは真偽値のtrueに限定する。文字数はUTF-16コード単位で数える。宛先・送信元はサーバーの設定で固定し、入力されたメールアドレスはReply-Toだけに使用する。
自前版のローカル検証に限り、サーバー設定TURNSTILE_ENABLED=falseでトークン検証を省略できる。この場合はturnstileTokenを空文字または省略として受け付ける。無効化を要求本文から指定することはできない。フロント側の設定と復帰手順は自前版セットアップを参照する。AWS版は常にトークンを必要とする。
応答¶
APIの処理結果はJSONで返し、Cache-Control: no-storeを付ける。receiptIdは要求ごとに発行するログ照合用IDであり、重複判定用のrequestIdとは異なる。
{ "code": "sent", "receiptId": "ログ照合用のUUID" }
| HTTPステータス | code | 意味 |
|---|---|---|
| 200 | sent |
SMTPの受付と成功記録を確認済み。受信箱への配送完了を保証するものではない |
| 400 | invalid_input |
JSONまたは入力項目が不正。項目を特定できる場合はerrorsに項目名とメッセージを返す |
| 403 | origin_rejected / verification_failed |
Origin不一致/Turnstile検証失敗 |
| 405 | method_not_allowed |
POST以外の送信操作 |
| 409 | processing |
同じ要求が処理中、または処理中に停止した記録あり |
| 409 | request_conflict / delivery_unknown |
同じIDで入力が異なる/送信結果が不明 |
| 413 / 415 | payload_too_large / unsupported_media_type |
本文サイズ超過/JSON以外 |
| 429 | rate_limited |
時間・日単位の送信枠を超過 |
| 502 | delivery_failed |
SMTPの明確な拒否など、送信失敗を確認 |
| 503 | dependency_error / delivery_unknown |
停止設定、依存先障害、処理数超過/送信結果や記録を確定できない |
API Gateway・nginx・ネットワーク機器が先に拒否した場合は、上のJSON形式にならないことがある。画面は応答形式の異常や通信断を成功と扱わず、同じIDで結果を確認する。CORSの事前要求はAPI Gatewayまたは自前版のHTTPサーバーが扱い、許可したOriginにPOSTとContent-Typeの利用を認める。
件数制限と再試行¶
Toの固定宛先は1件以上とし、サーバーのMAIL_TO(AWSのMailTo)にカンマ区切りで設定する。メールは1回のSMTP送信で全宛先に指定し、Cc・Bccは使わない。受信者にはTo一覧が見える。宛先数によらず、新規問い合わせ1件で送信枠を1件消費する。
sentは設定した全宛先のSMTP受付を確認し、成功を記録できた場合だけ返す。一部の宛先だけ受け付けられた場合はUNKNOWNを記録し、503・delivery_unknownを返す。全員への再送は受信済みの相手へ重複するため行わず、管理者がSMTP側・各受信先で確認する。全宛先への明確な拒否は従来どおりdelivery_failedとして扱う。SMTP受付後の受信箱への到達までは保証しない。Nodemailerの複数宛先の扱い
全体上限の初期値はJSTの毎時10件・1日30件、IP別上限は毎時3件・1日10件である。新規IDの予約と全体・IP別の4カウンターの加算を同じトランザクションで行い、失敗時はSMTP送信に進まない。送信枠の確保後にSMTPが失敗しても件数を戻さない。IPは信頼するプロキシまたはAPI Gatewayの接続情報から取得し、HMAC化した値をカウンターのキーに使う。生のIPはDB・アプリログへ保存しない。設定と残る制約は受付制限と停止攻撃への対策を参照する。
同じIDと入力に成功記録があれば、再送せずsentを返す。照合には秘密鍵付きHMACを使い、氏名・メールアドレス・本文はDBに保存しない。記録の保持期間は7日。AWS版はDynamoDBのTTL、自前版は起動時と1時間ごとの削除処理で期限切れデータを整理する。削除完了までは既存記録を参照する。
処理状態はPENDING、SENT、FAILED、UNKNOWNの4つとする。PENDINGやUNKNOWNを時間経過だけで再送可能に変更しない。成否不明時は受信側・ログで確認し、二重送信を避ける。FAILEDの場合のみ、利用者の次の手動操作で新しいIDを使う。
バックエンドの選択と切り替え¶
| 選択 | 起動入口 | 保存先 | 秘密情報 | 構築手順 |
|---|---|---|---|---|
| AWS | Lambdaのsrc/index.handler |
DynamoDB | Secrets Manager | AWSセットアップ |
| 自前サーバー | Node.jsのsrc/server.mjs |
SQLite | 非公開のJSONファイル | 自前サーバーのセットアップ |
フロントは接続先URLを設定し直して再ビルド・配置する。同じ公開URLを維持する場合はプロキシの転送先で切り替えられるが、接続先の検証は必要になる。Turnstileは許可ホスト名が変わらなければ同じキーを使える。
両DBの記録は自動同期・自動移行しない。切り替える際は旧APIの新規送信を止め、開始済みの処理を確認してから接続先を変更する。別DBで運用を始めるとカウンターと重複判定が引き継がれないため、当日の上限を残数に合わせるなどの調整を行う。成否不明の投稿は新しいAPIで再送せず、管理者が個別に確認する。記録を移す場合はHMAC秘密鍵も一致させ、専用の移行手順を用意する。