CONTENT
ここから
第33章では、Square APIとNext.jsで作ったECの仕組みを、物販だけでなく、チケット販売、相談予約、講座販売、イベント参加費、デジタルコンテンツ販売へ応用する方法を学びました。
この章では、これまで作ってきたECシステム全体を、完成アーキテクチャとして整理します。
アーキテクチャとは、システム全体の設計図のことです。
フロントエンド
API
DB
Square
Webhook
管理画面
メール通知
デプロイ
運用
それぞれの部品がどのようにつながっているかを理解すると、トラブルが起きたときにも原因を探しやすくなります。
攻略本風に言えば、第34章は**「これまで集めた装備を、最終パーティ編成として整理するステージ」**です。
34.1 全体構成図
まず、ECシステム全体の構成を見ます。
この本で作ってきたECは、次のような構成です。
購入者
↓
Next.js フロントエンド
↓
Next.js API Route / Route Handler
↓
DB
↓
Square API
↓
Square決済画面
↓
Webhook
↓
注文確定処理
↓
メール通知
↓
管理画面
もう少し分かりやすく書くと、次のようになります。
[購入者]
|
v
[ECサイト]
|
v
[API]
| \
v v
[DB] [Square]
^ |
| v
[Webhook受信]
|
v
[注文更新・在庫更新・メール送信]
|
v
[管理画面]
役割を分けると、次の通りです。
フロントエンド：
購入者が見る画面
API：
購入や注文処理を受け付ける入口
DB：
商品、注文、在庫、顧客情報を保存する場所
Square：
決済を安全に処理する場所
Webhook：
Squareから決済結果を受け取る仕組み
管理画面：
店舗側が注文や商品を管理する画面
メール通知：
購入者と店舗へ状況を知らせる仕組み
この構成で大切なのは、決済完了をフロントエンドだけで判断しないことです。
購入者が完了ページに戻った
↓
注文確定
ではなく
SquareからWebhookが届いた
↓
注文確定
全体の基本方針は、次の通りです。
画面は分かりやすく
決済はSquareに任せる
注文確定はWebhookで判断する
DBに正しい状態を残す
管理画面で人が確認できる
ECシステムは、見た目だけではありません。
裏側のデータ、決済、通知、運用まで含めて完成です。
34.2 フロントエンド構成
フロントエンドは、購入者が直接見る部分です。
Next.jsでは、商品一覧、商品詳細、カート、注文完了ページなどを作ります。
トップページ
商品一覧ページ
商品詳細ページ
カートページ
注文確認ページ
注文完了ページ
FAQページ
法務ページ
フロントエンドの役割は、購入者を迷わせず、購入まで案内することです。
商品を見つける
↓
商品の内容を理解する
↓
カートに入れる
↓
決済へ進む
↓
注文完了を確認する
ページ構成の例です。
app/
page.tsx
products/
page.tsx
[slug]/
page.tsx
cart/
page.tsx
checkout/
page.tsx
thanks/
page.tsx
faq/
page.tsx
legal/
tokushoho/
page.tsx
privacy/
page.tsx
商品ページでは、購入者に必要な情報を表示します。
・商品名
・価格
・写真
・説明
・在庫状況
・送料
・配送目安
・購入ボタン
・FAQ
フロントエンドで注意すべきことは、重要な判断をブラウザだけで行わないことです。
ブラウザでやってよい：
画面表示
入力補助
カート表示
購入ボタン表示
ブラウザだけでやってはいけない：
最終金額の確定
在庫確定
注文確定
決済完了判断
金額や在庫は、サーバー側で再計算します。
ブラウザ：
商品IDと数量を送る
サーバー：
DBから価格と在庫を確認
合計金額を計算
Squareへ送る
フロントエンドは、お客様にとっての売り場です。
見やすく、速く、不安なく購入できることを優先します。
34.3 API構成
APIは、フロントエンドとDB、Squareをつなぐ窓口です。
Next.jsでは、Route Handlerを使ってAPIを作れます。
画面
↓
API
↓
DB / Square / メール
ECで必要なAPIは、主に次の通りです。
・商品取得API
・カート金額計算API
・決済リンク作成API
・Webhook受信API
・注文取得API
・注文更新API
・管理画面用API
・メール送信API
API構成の例です。
app/api/
products/
route.ts
checkout/
create-payment-link/
route.ts
webhooks/
square/
route.ts
admin/
orders/
route.ts
products/
route.ts
emails/
send-order-confirmation/
route.ts
決済リンク作成APIの役割です。
カート内容を受け取る
↓
DBで商品価格を確認
↓
在庫を確認
↓
注文をpendingで作成
↓
Square決済リンクを作成
↓
購入者をSquareへ案内
APIでは、入力値を信用しすぎてはいけません。
購入者から送られてきた価格：
信用しない
DBに保存されている価格：
正として使う
悪い例です。
ブラウザから送られた合計金額をそのままSquareへ送る
よい例です。
商品IDと数量だけ受け取る
↓
サーバー側で価格を取得
↓
合計金額を計算
APIの基本方針は、次の通りです。
入力を検証する
DBを正とする
秘密情報はサーバー側だけで使う
重要処理はログを残す
エラー時に追跡できるようにする
APIは、ECシステムの関所です。
不正な値や危険な処理を、ここで止めます。
34.4 DB構成
DBは、ECシステムの記録係です。
商品、注文、在庫、顧客、配送、クーポンなどを保存します。
商品情報
注文情報
注文明細
在庫
顧客情報
配送情報
クーポン
Webhookログ
基本的なテーブル構成です。
products：
商品マスター
product_variants：
商品バリエーション
orders：
注文
order_items：
注文商品
customers：
顧客
inventory：
在庫
shipments：
配送
coupons：
クーポン
webhook_events：
Webhook処理履歴
注文まわりの関係です。
orders
↓
order_items
↓
products
イメージです。
orders：
注文番号、購入者、合計金額、ステータス
order_items：
どの商品を何個買ったか
products：
商品名、価格、説明
注文ステータスの例です。
pending：
決済待ち
paid：
決済完了
preparing：
発送準備中
shipped：
発送済み
cancelled：
キャンセル
manual_review：
手動確認
DB設計で大切なのは、状態を追えることです。
いつ注文されたか
いくらだったか
何を買ったか
決済済みか
発送済みか
メールを送ったか
特に、注文にはその時点の価格を保存します。
商品価格は後から変わることがあるからです。
商品マスター：
現在価格
注文明細：
購入時点の価格
たとえば、商品価格が変更されても、過去注文の金額は変えてはいけません。
7月1日購入：
5,400円
7月10日価格変更：
6,000円
過去注文：
5,400円のまま残す
DBは、現在の販売だけでなく、過去の取引を正しく残す場所です。
34.5 Square連携構成
Square連携では、決済処理をSquareに任せます。
自社ECでは、カード番号などの決済情報を直接持ちません。
自社EC：
商品、注文、在庫、画面を管理
Square：
決済を処理
Square連携の基本フローです。
購入者が購入ボタンを押す
↓
自社APIで注文をpending作成
↓
Square決済リンクを作成
↓
購入者がSquare画面で決済
↓
Squareが決済処理
↓
Webhookで結果通知
↓
自社DBの注文をpaidへ更新
保存しておくべきSquare関連情報です。
・Square Payment ID
・Square Order ID
・Square Checkout URL
・Square Customer ID
・Square Subscription ID
・Square Webhook Event ID
自社DBの注文テーブルに、Square側のIDを保存しておくと追跡しやすくなります。
orders:
id
order_number
status
total_amount
square_payment_id
square_order_id
created_at
Square連携で重要なのは、環境を混ぜないことです。
Sandbox：
テスト環境
Production：
本番環境
本番ではProduction Access Token、本番Location ID、本番Webhook URLを使います。
SQUARE_ENVIRONMENT=production
SQUARE_ACCESS_TOKEN=本番用
SQUARE_LOCATION_ID=本番用
Square連携の基本方針です。
カード情報は持たない
決済処理はSquareに任せる
注文情報は自社DBに残す
決済結果はWebhookで確定する
Square側IDを保存して追跡できるようにする
Squareは決済の専門担当です。
自社ECは、商品、注文、顧客体験、運用を担当します。
34.6 Webhook構成
Webhookは、Squareから自社ECへイベントを知らせる仕組みです。
決済完了、支払い更新、注文更新などが発生したときに、Squareが指定URLへ通知します。
Squareで決済完了
↓
Webhook通知
↓
自社APIが受信
↓
注文ステータス更新
Webhook構成です。
Square
↓
/api/webhooks/square
↓
署名検証
↓
イベント種別確認
↓
重複チェック
↓
注文更新
↓
在庫更新
↓
メール送信
Webhook受信APIの基本フローです。
1. リクエストを受け取る
2. 署名を検証する
3. event_idを確認する
4. 処理済みイベントならスキップ
5. イベント種別を確認する
6. 注文を取得する
7. 注文ステータスを更新する
8. 在庫を減らす
9. メールを送る
10. webhook_eventsに記録する
Webhookでは、同じイベントが複数回来る可能性を考えます。
そのため、event_idを保存します。
webhook_events:
event_id
event_type
processed_at
status
すでに処理済みのevent_idなら、二重処理しません。
同じWebhookが再送される
↓
event_idを確認
↓
処理済みならスキップ
Webhookで絶対に避けたいのは、二重処理です。
1回の決済
↓
在庫を2回減らす
↓
メールを2回送る
そのため、Webhook処理は冪等にします。
冪等とは、同じ処理を何度実行しても、結果が変わらないようにする考え方です。
1回実行しても
2回実行しても
注文はpaidのまま
在庫は1回分だけ減る
Webhookは、ECの裏側の心臓です。
購入完了ページよりも、Webhookを信頼して注文確定します。
34.7 管理画面構成
管理画面は、店舗スタッフがECを運用するための画面です。
購入者向けの画面とは別に、注文、商品、在庫、配送、顧客対応を管理します。
購入者向け：
商品を見る、購入する
管理者向け：
注文を見る、発送する、商品を更新する
管理画面に必要な機能です。
・ログイン
・注文一覧
・注文詳細
・ステータス変更
・商品管理
・在庫管理
・配送管理
・顧客メモ
・CSV出力
・Webhookログ確認
管理画面の構成例です。
admin/
login/
orders/
orders/[id]/
products/
inventory/
shipments/
customers/
coupons/
settings/
注文一覧では、対応すべき注文を見つけやすくします。
・未対応
・決済済み
・発送準備中
・発送済み
・キャンセル
・手動確認
注文詳細で表示する情報です。
・注文番号
・注文日時
・購入者情報
・商品明細
・合計金額
・決済ステータス
・配送先
・配送ステータス
・管理メモ
・メール送信履歴
管理画面で大切なのは、誤操作を防ぐことです。
危険な操作：
キャンセル
返金
在庫変更
発送済み変更
対策：
確認ダイアログ
操作履歴
権限管理
たとえば、発送済みに変更するときは確認を入れます。
この注文を発送済みに変更します。
追跡番号は入力済みですか？
[キャンセル]
[発送済みにする]
管理画面は、ただの裏側ではありません。
店舗の司令室です。
今、何を発送するか
どの注文が止まっているか
どの商品が足りないか
どの問い合わせに対応するか
これが分かる画面を作ります。
34.8 メール通知構成
メール通知は、購入者と店舗の両方に必要です。
購入者には安心を届けます。
店舗には作業指示を届けます。
購入者向け：
注文完了メール
発送完了メール
キャンセルメール
店舗向け：
新規注文通知
決済失敗通知
手動確認通知
メール通知の基本フローです。
注文がpaidになる
↓
購入者へ注文完了メール
↓
店舗へ新規注文通知
発送完了時の流れです。
管理画面で発送済みにする
↓
追跡番号を保存
↓
購入者へ発送完了メール
メールの種類です。
・注文完了メール
・発送完了メール
・キャンセル完了メール
・決済失敗メール
・管理者通知メール
・問い合わせ返信メール
・定期購入通知メール
メール送信履歴もDBに残すと安心です。
email_logs:
id
order_id
to
template
status
sent_at
error_message
メール送信で重要なのは、メール失敗と注文失敗を分けることです。
注文は成功
↓
メール送信に失敗
この場合：
注文はpaidのまま
メールだけ再送対象
悪い設計です。
メール送信に失敗
↓
注文も失敗扱いにする
よい設計です。
注文確定
↓
メール送信
↓
失敗したらemail_logsに記録
↓
管理者が再送
メール通知は、購入者の不安を減らすための重要な接点です。
注文できたか
いつ届くか
問い合わせ先はどこか
これが分かるメールにします。
34.9 デプロイ構成
デプロイとは、作ったECサイトを本番環境に公開することです。
この本では、Next.jsをVercelへデプロイする構成を想定します。
ローカル開発
↓
GitHub
↓
Vercel
↓
本番公開
デプロイ構成です。
開発者
↓ git push
GitHub
↓ 自動連携
Vercel
↓
Production環境
↓
独自ドメイン
環境は、開発用と本番用を分けます。
Development：
ローカル開発
Preview：
確認用
Production：
本番公開
環境ごとに設定する値も分けます。
ローカル：
Sandbox Square
開発DB
テストメール
本番：
Production Square
本番DB
本番メール
本番環境変数の例です。
NEXT_PUBLIC_APP_URL=
DATABASE_URL=
SQUARE_ENVIRONMENT=
SQUARE_ACCESS_TOKEN=
SQUARE_LOCATION_ID=
SQUARE_WEBHOOK_SIGNATURE_KEY=
RESEND_API_KEY=
ADMIN_NOTIFICATION_EMAIL=
デプロイ前チェックです。
・ビルドが成功する
・TypeScriptエラーがない
・環境変数が設定されている
・本番DBにつながる
・Square Production設定になっている
・Webhook URLが本番URLになっている
・独自ドメインが有効
・HTTPSで開ける
デプロイ後にも確認します。
・トップページが表示される
・商品ページが表示される
・カートに入れられる
・決済リンクが作成される
・Webhookが届く
・注文がpaidになる
・メールが届く
・管理画面で確認できる
デプロイは、公開ボタンを押すだけではありません。
公開
＋
決済確認
＋
Webhook確認
＋
メール確認
＋
管理画面確認
ここまで確認して、本番運用に入ります。
34.10 運用フロー
最後に、完成したECの運用フローを整理します。
ECは作って終わりではありません。
毎日の運用が必要です。
注文確認
在庫確認
発送準備
問い合わせ対応
売上確認
商品更新
キャンペーン管理
通常注文の運用フローです。
購入者が注文
↓
Squareで決済
↓
Webhookでpaidへ更新
↓
注文完了メール送信
↓
管理者通知
↓
店舗が注文確認
↓
発送準備
↓
発送済みに変更
↓
発送完了メール送信
管理者の毎日の確認項目です。
・新規注文はあるか
・manual_reviewはあるか
・決済失敗はあるか
・未発送注文はあるか
・在庫切れ商品はあるか
・問い合わせはあるか
週次で見る項目です。
・売上
・注文数
・人気商品
・在庫不足商品
・カート離脱
・問い合わせ傾向
・キャンペーン効果
月次で見る項目です。
・月間売上
・利益
・リピート率
・平均注文単価
・SEO流入
・商品別売上
・改善施策の結果
トラブル時の運用も決めておきます。
決済済みだが注文がpaidにならない
↓
Square Dashboardを確認
↓
Webhookログを確認
↓
注文をmanual_reviewへ
↓
管理者が手動対応
在庫不足時の流れです。
注文発生
↓
在庫不足が判明
↓
発送可否を確認
↓
購入者へ連絡
↓
代替・遅延・キャンセルを案内
運用で大切なのは、例外を見つけられることです。
通常注文：
自動で進む
例外注文：
管理者が見つけて対応する
完成アーキテクチャの目的は、自動化だけではありません。
人が安全に運用できる状態を作ることです。
自動化できるところは自動化する
人が確認すべきところは見える化する
例外はmanual_reviewに集める
これが、実務で使えるECシステムの運用フローです。
第34章のまとめ
この章では、Square APIとNext.jsで作るECシステムの完成アーキテクチャを整理しました。
フロントエンド、API、DB、Square、Webhook、管理画面、メール通知、デプロイ、運用がつながって、1つのECシステムになります。
この章で覚えておきたいポイントは、次の通りです。
1. ECシステムは、画面だけでなくAPI、DB、決済、管理画面、運用まで含めて完成である
2. フロントエンドは購入者が迷わず購入できる売り場である
3. APIは、フロントエンド、DB、Squareをつなぐ関所である
4. DBは、商品、注文、在庫、顧客、履歴を記録する場所である
5. Squareには決済処理を任せ、自社ECは注文と運用を管理する
6. Webhookで決済結果を受け取り、注文ステータスを確定する
7. 管理画面は、店舗スタッフが注文、商品、在庫、配送を管理する司令室である
8. メール通知は、購入者の安心と店舗作業を支える
9. デプロイでは、開発環境と本番環境を分ける
10. 運用では、自動処理と手動確認の役割を分ける
完成アーキテクチャの基本は、次の一言にまとめられます。
ECは、売る画面ではなく、注文から運用までをつなぐ仕組みである。
商品が見られる。
購入できる。
決済できる。
注文が記録される。
メールが届く。
店舗が発送できる。
トラブル時に確認できる。
ここまでつながって、実務で使えるECシステムになります。
第35章では、この完成したECシステムを、制作案件としてどう提案し、どのように収益化していくかを整理していきます。