WooCommerceの注文をERPへ連携するなら、Webhookを受け取る処理と、ERPへ登録する処理を分ける設計をおすすめします。署名の検証、消えない処理キューへの保存、重複を防ぐ登録、定期照合を組み合わせます。通知を受信できても、ERPへの登録が完了したとは限りません。
この記事は連携を依頼するEC担当者と実装担当者向けの設計チェックリストです。以下のキューや照合は推奨する実装方針であり、WooCommerceの標準設定だけで自動的に用意される機能ではありません。
1. 注文を「いつ」「何のために」連携するか決める
注文の作成と入金確認、出荷指示は別の業務です。注文が作られた時点で無条件に出荷データを登録せず、決済方法と運用に合う注文ステータスを決めます。キャンセル・一部返金・住所変更を受けた後にERPで何を更新するかも整理してください。
- 注文の識別：店舗を識別する値とWooCommerce注文ID。
- 商品の対応：SKU、バリエーション、ERPの商品コード、数量単位。
- 金額の対応：通貨、税、送料、値引き、端数処理。
- 業務の境界：仮受注、引当、出荷指示、返金を開始する条件と担当者。
最初の対象を「条件を満たす注文の仮受注登録」に絞ると、出荷や返金まで同時に自動化するより検証範囲を整理しやすくなります。
2. Webhookを設定し、受信経路を確認する
管理画面の WooCommerce → Settings → Advanced → Webhooks で通知を追加し、Topic、HTTPSのDelivery URL、Secretを設定します。最初にActiveで保存するとpingが送られるため、接続確認と実際の注文データの受信を分けて確認します。項目の詳細はWooCommerce公式のWebhook設定ガイドを参照してください。
受信側では、JSONを変換する前のリクエスト本文で署名を検証します。標準実装の署名はHMAC-SHA256の結果をBase64化したものです。共有Secretをサーバー側で管理し、受信した署名と安全に比較します。独自フィルターを使う環境では送信側の仕様も確認してください。根拠：公式WC_Webhookコードリファレンスのgenerate_signature。
3. 受信とERP処理を分ける
- 受信：署名、対象店舗、イベント、本文形式を検証する。
- 保存：必要なデータと処理状態を、再起動しても消えないキューまたはデータベースへ保存する。
- 応答：保存の成功を確認してから2xxを返す。保存できなかった場合に成功と返さない。
- 実行：別の処理でERPを更新し、成功・再試行待ち・要確認の状態を記録する。
- 照合：WooCommerceとERPを定期的に比較して、通知の欠落や登録漏れを探す。
2xxはこの設計では「受け付けて保存した」という意味です。運用画面では「受付済み」と「ERP反映済み」を分け、未処理件数と最も古い待機時間を確認できるようにします。
4. 重複登録と古い更新の上書きを防ぐ
ERP側の注文を一意にするキーは、例えば店舗IDとWooCommerce注文IDの組み合わせです。ERPが対応していれば、この外部キーで既存注文を検索・更新するか、冪等な登録APIを使います。冪等とは、同じ要求を繰り返しても業務上の結果が増えない性質です。
ただし、「同じ注文IDはすべて無視する」という実装では、その後の正当な更新まで失います。注文を識別するキーと通知の処理履歴を分けて管理してください。同一注文の処理を直列化し、必要に応じてWooCommerceの最新状態を取得してからERPへ反映する方法もあります。古い通知が後から来た場合と、処理中に新しい更新が来た場合の両方をテストします。
ERP登録後に通信が切れた場合は、失敗か成功か判断できないことがあります。すぐに新規登録を繰り返さず、外部キーでERP側を確認するか、「結果不明」として照合・担当者確認へ回します。
5. エラーの種類で対応を変える
- 一時的な接続障害、429、5xx：APIの仕様に従って待機時間を増やしながら再試行する。Retry-Afterがあれば考慮し、回数と期限に上限を設ける。
- 認証・権限・項目の不備：設定やデータを修正してから再開する。同じ不正な要求を送り続けない。
- 登録結果が不明：ERPの既存レコードを照合し、二重登録を避ける。
- 上限超過：通常の処理から隔離し、担当者が原因と再実行対象を確認できる状態にする。
これらは受信後の連携システムに実装する方針です。WooCommerce側が失敗した通知を必ず再送してくれるとは想定しません。継続した配信失敗でWebhookが無効になる場合があるため、設定状態と配信ログも監視します。ログは WooCommerce → Status → Logs の webhooks-delivery から確認できます。公式の配信失敗・ログ説明。
6. 定期照合で通知の取りこぼしを見つける
注文一覧APIで更新された注文を取得し、ERPへの登録状態と比較します。REST API v3には modified_after、modified_before、page、per_page などのパラメーターがあります。利用バージョンと時刻の扱いは公式Orders APIリファレンスで確認できます。
実装では、最後に照合を完了した時刻を保存し、次回は少し重なる範囲から読み直して重複を除外する方法が有効です。全ページを処理する前に完了時刻を進めないこと、処理中の注文更新を次回拾えることを確認します。削除済み注文など通常の一覧で拾えない対象は、削除通知や別の監査処理も含めて方針を決めます。
公開前の受け入れテスト
- 同じ通知を2回受けても、ERPの注文が増えない。
- 古い通知が遅れて届いても、新しい状態を壊さない。
- 署名が不正な通知は業務処理に進まない。
- キューの保存失敗を受付成功と表示しない。
- ERP停止後も受付済みデータが残り、復旧後に確認して再開できる。
- 登録直後のタイムアウトでも、再実行で二重登録しない。
- 未入金・キャンセル・一部返金の業務判断が決めた条件に従う。
- 通知を受けられなかった注文を定期照合で検出できる。
ログには注文ID、処理段階、時刻、エラー分類、ERPの外部キーを残し、必要に応じて配信IDも調査の手掛かりにします。SecretやAPIキーを記録せず、氏名・住所などの個人情報も必要以上にログへ複製しない設計にします。
よくある質問
Webhookだけで連携は完成しますか？
通知を受け取る入口は作れますが、ERP項目への変換、重複防止、失敗処理、照合は別途設計が必要です。使用する連携製品がどこまで対応するか確認してください。
注文IDだけで重複を防いでもよいですか？
複数店舗では店舗の識別も必要です。また、同じ注文の更新を受け付ける必要があるため、注文の一意性と通知の処理済み判定を分けます。
ERPに外部キーや検索APIがない場合は？
登録結果の確認方法を先に決めます。対応表を連携側で管理するだけでは、ERP登録後の通信断で結果不明になる問題が残ります。連携範囲を狭める、ERP側を拡張する、担当者の確認を挟むなどを比較します。
WooCommerceとERPの連携を相談する
ご相談時には、利用中のWooCommerceとERP、連携したい項目、対象の注文状態、現在困っている処理をお知らせください。項目表や個人情報を除いたサンプルがあると、実装範囲を整理しやすくなります。
API・システム連携の支援内容とERP開発サービスをご覧いただけます。全体の進め方はECのAI自動化ガイドも参考にしてください。
技術資料確認：2026年9月25日。環境や拡張機能によって挙動が異なるため、利用中の構成で検証してください。