Shopify から Odoo への注文インポート: 完全な自動化ガイド

Odoo への手動再入力が必要なすべての Shopify 注文は、データ入力エラーの可能性、フルフィルメント処理の遅延、追加の注文ごとにさらに悪化するスタッフの時間の浪費など、責任を伴います。 1 日あたり 200 件の注文を処理する店舗の場合、手動による注文のインポートには毎日およそ 3 ～ 4 時間のスタッフの時間がかかり、在庫、出荷、会計に至るまでに 2 ～ 5% のエラー率が発生します。

ShopifyからOdooへの注文パイプラインを自動化することで、このボトルネックが完全に解消されます。注文は発注後数秒以内に Odoo に到着し、顧客レコードは自動的にマージされ、支払いステータスはリアルタイムで同期され、フルフィルメントの更新情報は追跡番号とともに Shopify に書き戻され、エラー状態はサイレントにドロップされるのではなく捕捉され、解決のためにキューに入れられます。

このガイドでは、プロセスを開始する Shopify Webhook から、ループを閉じるフルフィルメント ライトバックまで、完全な注文インポートの自動化について説明します。すべてのステップには、運用グレードの実装のために処理する必要がある特定のデータ マッピング、エッジ ケース、および障害モードが含まれています。

重要なポイント

• Shopify Webhook は、インポート パイプラインをトリガーするリアルタイムの注文イベント (注文/作成、注文/更新、注文/キャンセル) を提供します
• 顧客同期は電子メールを主一致キーとして使用し、新規顧客の自動作成と既存の顧客のフィールド結合を行います。
• 支払いステータスのマッピングにより、Shopify の支払い状態 (承認済み、支払い済み、一部支払い済み、返金済み) が Odoo 支払い記録に変換されます
• 製品マッチングは、SKU を主識別子として使用して Shopify ラインアイテムを Odoo 製品に接続します — バリアントレベルのマッチングが不可欠です
• フルフィルメント ライトバックにより、Odoo 配送確認が追跡番号、配送業者情報、品目ごとのフルフィルメント データとともに Shopify に返送されます
• 部分的なフルフィルメント（複数の倉庫からの分割出荷）には、注文レベルではなく品目レベルのフルフィルメント追跡が必要です
• エラー処理には、再試行キュー、デッドレター処理、アラートを含める必要があります - サイレントエラーが最も危険なエラーです
• 冪等キー (Shopify 注文 ID) により、Webhook の再試行による重複注文を防止します

---

アーキテクチャ: 注文インポート パイプライン

完全な注文インポート パイプラインには 6 つのステージがあり、それぞれに特定のデータ変換と障害モードがあります。

Stage 1: Webhook Reception
  Shopify → orders/create webhook → Integration endpoint

Stage 2: Customer Resolution
  Find or create Odoo customer from Shopify customer data

Stage 3: Product Matching
  Map Shopify line items to Odoo products by SKU/variant

Stage 4: Order Creation
  Create Odoo sale order with lines, taxes, shipping, discounts

Stage 5: Payment Recording
  Record payment status based on Shopify financial_status

Stage 6: Fulfillment Writeback
  Odoo delivery → Shopify fulfillment with tracking

各ステージは個別の操作であり、独立して失敗する可能性があります。堅牢な実装では、これらをチェックポイント機能を備えたパイプラインとして処理します。ステージ 4 が失敗した場合、ステージ 1 ～ 3 は再試行時に再実行されません。

---

ステージ 1: Shopify 注文 Webhook の受信

Shopify Webhook は、リアルタイムの注文インポートの基盤です。注文イベントが発生すると、Shopify は完全な注文ペイロードを含む HTTP POST リクエストを登録済みのエンドポイントに送信します。

必要な Webhook サブスクリプション

Webhook の検証

すべての受信 Webhook は、Shopify の HMAC-SHA256 署名を使用して検証する必要があります。 Webhook ペイロードはアプリの共有シークレットで署名されます。処理する前に署名を確認してください。未検証の Webhook は 401 応答で拒否される必要があります。

Webhook 配信保証の処理

Shopify は少なくとも 1 回の配信を保証します。つまり、ネットワーク タイムアウト後、Shopify の再試行サイクル中、またはインシデントの回復中に、同じ Webhook が複数回送信される可能性があります。エンドポイントは冪等である必要があります。同じ注文を受信したり Webhook を 2 回作成したりしても、2 つの Odoo 注文を作成してはなりません。

実装パターン: Shopify の注文 ID を冪等キーとして使用します。 Odoo 注文を作成する前に、その Shopify 参照を持つ注文がすでに存在するかどうかを確認してください。存在する場合は、作成をスキップして 200 レスポンスを返し、Shopify が再試行を停止します。

応答時間の要件

Shopify は 5 秒以内に 200 件の応答を期待しています。エンドポイントに時間がかかる場合、Shopify は配信を失敗としてマークし、再試行します。このため、Webhook エンドポイントはペイロードを受け入れ、HMAC 署名を検証し、非同期処理のために注文をキューに入れ、すぐに 200 を返す必要があります。実際の注文の作成はバックグラウンド ワーカーで行われます。

---

ステージ 2: お客様の解決策

Shopify のすべての注文には、電子メール、名前、電話番号、配送先住所、請求先住所などの顧客データが含まれます。統合では、Odoo の連絡先データベースに対してこれを解決する必要があります。

顧客マッチングアルゴリズム

推奨される一致ロジックは、次の優先順位に従います。

1. 電子メールの完全一致: Shopify 注文の電子メール アドレスを Odoo の連絡先で検索します。電子メールは最も信頼性の高い一意の識別子です。
2. 電話照合 (電子メールが一致しない場合): 一部の B2B 注文または POS 注文には電子メールが含まれていない場合があります。正規化 (スペース、ダッシュ、国コードの正規化の除去) を使用した電話番号照合にフォールバックします。
3. 新しい連絡先を作成: 一致するものが見つからない場合は、Shopify の注文から入手可能なすべてのデータを使用して新しい Odoo 連絡先を作成します。

既存顧客向けのフィールド統合

既存の Odoo 顧客が一致すると、統合により欠落しているフィールドが更新されます (上書きされません)。

If Odoo contact has no phone but Shopify order does → add phone
If Odoo contact has phone and Shopify order has different phone → keep Odoo (source of truth)
If Shopify order has new shipping address → add as child contact (delivery address)

アドレスの処理

B2B 顧客対応

B2B 注文 (Shopify Plus B2B 機能) の場合、統合では、個々の購入者を子連絡先として、Shopify 会社を Odoo 会社タイプの連絡先にマッピングする必要があります。これにより、B2B 業務でクレジット条件、ボリューム価格、アカウント管理に必要な企業と個人の関係が維持されます。

---

ステージ 3: 製品のマッチング

Shopify 注文の各品目は、Odoo の商品と一致する必要があります。 Shopify と Odoo では製品の表現方法が異なるため、多くの統合が失敗するのはこの一致です。

SKU ベースのマッチング

SKU が推奨される主一致キーです。 Odoo で製品を管理し、Shopify に同期する場合、Odoo 内部参照 (SKU) を Odoo 製品バリアントと Shopify バリアントの両方に設定する必要があります。この統合により、Shopify ラインアイテムの SKU が Odoo 製品バリアントの内部参照に一致します。

バリアント マッチングの複雑さ

Shopify バリアント (サイズ: 大、色: ブルー) は、同等の属性値を持つ Odoo 製品バリアントと一致する必要があります。これは、SKU が一貫している場合は簡単ですが、システム間で SKU が異なる場合、Shopify に Odoo に存在しないバリアントがある場合 (例: Shopify に追加された新しいバリアントが Odoo にまだ同期されていない場合)、または Shopify が事前定義されたバリアントを使用しているのに Odoo 製品が構成可能な属性を使用している場合は問題が発生します。

一致しない商品の処理: Shopify 広告申込情報が Odoo 製品と一致しない場合、統合はそれを黙ってスキップすべきではありません。代わりに、プレースホルダー製品ライン (例: 説明に Shopify バリアント タイトルを持つ包括的な「一致しない Shopify 製品」アイテム) を使用して注文を作成し、注文にレビュー用のフラグを立てて、運用チームに警告する必要があります。

バンドルおよびキット製品

Shopify でバンドル (3 つの個別の製品として出荷される「スターター キット」など) を販売する場合、統合では、単一の Odoo 注文明細 (バンドル製品の場合) を作成するか、複数の明細行 (コンポーネント製品の場合) を作成するかを認識する必要があります。これは、Odoo の在庫設定、つまりバンドル製品を単一のアイテムとして追跡するか、個別のコンポーネントとして追跡するかによって異なります。

---

ステージ 4: Odoo での注文の作成

顧客が解決され、製品が一致すると、統合により Odoo 販売注文が作成されます。これは最もデータ集約的な段階であり、慎重なフィールド マッピングが必要です。

フィールド マッピング: Shopify から Odoo 販売注文へ

品目マッピング

割引の取り扱い

Shopify は、Odoo とは異なる割引を表します。 Shopify は、品目ごとの割引額と注文レベルでの全体的な割引コードを提供します。 Odoo は回線ごとの割引率を期待しています。

変換: discount_percentage = (shopify_discount_amount / (quantity * unit_price)) * 100

注文レベルの割引 (例: 「注文全体の 10% オフ」) の場合、割引は品目全体に比例して配分される必要があります。一部の実装では、注文レベルの割引に分配する代わりに、個別の負の金額の品目を追加します。どちらのアプローチも有効ですが、比例配分の方が品目ごとのマージン分析がより明確になります。

配送会社

Shopify の配送料は、別の注文明細の専用の Odoo 製品 (「Shopify Shipping」など) にマッピングする必要があります。これにより、レポートでは配送収入と製品収入が区別されます。

注文確認

下書き状態で販売注文を作成した後、統合により自動的にそれが確認され (action_confirm)、下流のワークフロー (配送注文の作成、製造注文 (MTO 製品の場合)、および発注書 (ドロップシップ製品の場合)) がトリガーされます。支払いステータスが「支払い済み」または「承認済み」の場合のみ自動的に確認されます。支払い状態が「保留中」の場合は下書き注文を保持します。

---

ステージ 5: 支払いの記録

Shopify の financial_status フィールドは、注文の支払い状態を示します。統合では、これを Odoo 支払い記録に変換する必要があります。

支払いステータスのマッピング

請求書の自動作成

「支払い済み」注文の場合、統合により Odoo 請求書が自動的に作成および検証され、それに対して支払いが登録される必要があります。これにより、売掛金がきれいに保たれます。全額支払われた Shopify 注文では、Odoo の AR 残高がゼロになるはずです。

「承認された」注文 (手動キャプチャが有効になっている場合の Shopify Payments で一般的) の場合、統合により販売注文は作成されますが、請求書は作成されません。後で支払いが取得されると (financial_status が「支払い済み」に変更されて注文/更新された Webhook がトリガーされる)、統合によって請求書が作成され、支払いが登録されます。

支払い方法の設定

Shopify 支払い専用の Odoo 支払い仕訳帳を作成します (例: 「銀行」タイプの「Shopify Payments」仕訳帳)。すべての自動支払い登録では、この仕訳帳を使用する必要があります。これにより、Shopify の支払い記録が他の支払い方法から分離され、銀行の照合が簡素化されます。

---

ステージ 6: フルフィルメント ライトバック

最終段階でループが終了します。Odoo で注文が履行される (配送注文が検証される) と、統合によってフルフィルメント データが Shopify に返送され、注文ステータスが更新され、顧客に追跡情報が提供されます。

ライトバックのトリガー

Odoo では、フルフィルメント イベントは配送注文の検証 (stock.picking) です。統合では、配送注文確認イベントをリッスンし、Shopify フルフィルメント API 呼び出しをトリガーする必要があります。

フルフィルメント データ マッピング

部分フルフィルメントの処理

分割発送の処理

Odoo が配送注文を複数の出荷に分割する場合 (バックオーダー シナリオ)、各出荷は個別の配送注文を生成します。統合では次のことを行う必要があります。

1. 新しい配送注文がバックオーダー（同じ販売注文に関連する）であることを検出します。
2. この出荷に含まれる品目を特定する
3. これらのアイテムのみについて Shopify で部分的なフルフィルメントを作成する
4. この特定の荷物の正しい追跡番号を含めてください

ドロップシップ注文のフルフィルメント ライトバック

ドロップシップ フルフィルメント (サプライヤーが顧客に直接出荷する場合) の場合、追跡情報は倉庫配送注文ではなく、注文書の受領書から取得されます。この統合では、ドロップシップ注文の購入受領確認を監視し、Shopify フルフィルメントにサプライヤーの追跡番号を使用する必要があります。

---

エラー処理と回復

注文インポート パイプラインのエラーは 3 つのカテゴリに分類され、それぞれに異なる回復戦略が必要です。

一時的なエラー (自動的に再試行)

ネットワークのタイムアウト、API レート制限、一時的なサービスの利用不能など、これらは自動的に解決されます。統合では、指数バックオフ再試行を実装する必要があります。最初の再試行は 30 秒後、2 回目は 2 分後、3 回目は 10 分後に、構成可能な最大再試行回数 (通常は 5 ～ 10) まで行われます。

データ エラー (レビューのための隔離)

一致しない製品、無効な住所、必須フィールドの欠落 - これらには人間の介入が必要です。統合では、何が失敗したかを明確に説明したレビューキューで注文を隔離し、Odoo アクティビティまたは運用チームへの通知を作成し、データの問題が修正された後にワンクリックの再試行メカニズムを提供する必要があります。

システムエラー (即時に警告)

認証の失敗、API 権限の変更、コネクタ構成エラー - これらは 1 つの注文だけでなく、すべての注文に影響します。統合ではパターン (例: 5 回連続の失敗) を検出し、電子メールとダッシュボード アラートを介して直ちにエスカレーションする必要があります。

デッドレターキュー

すべての再試行に失敗した注文は、処理不能な注文の永続的な記録である配信不能キューに移動します。このキューは毎日監視する必要があります。一般的なデッドレターの理由には、Shopify に存在するが Odoo に同期されていない製品、Odoo が拒否した無効な文字を含む顧客データ、Odoo 検証に失敗したゼロ価格商品の注文、Odoo で新しい Shopify 通貨が設定されていない場合の通貨の不一致などが含まれます。

---

注文インポートパイプラインのテスト

ライブにする前に、パイプラインを通るすべてのパスをテストします。

機能テストのシナリオ

負荷テスト

ストアが大量 (1 日あたり 500 以上の注文) を処理する場合は、運用環境と同様のデータ量でインポート パイプラインの負荷テストを行ってください。パイプラインがバースト トラフィック (フラッシュ セール) を処理していること、データベース ロックがボトルネックを作成していないこと、および Shopify および Odoo API のレート制限が遵守されていることを確認します。

---

パフォーマンスの最適化

履歴インポートのバッチ処理

最初に統合を設定するとき、または過去の注文をインポートするときは、各注文を個別に処理するのではなく、Shopify の REST API を使用して 250 (最大ページ サイズ) のバッチで注文を取得します。値のリストを含む ORM create メソッドを使用して、Odoo レコードをバッチで作成します。

製品と顧客の検索のキャッシュ

製品照合 (ステージ 3) と顧客解決 (ステージ 2) には、すべての注文のデータベース検索が含まれます。頻繁にアクセスされる製品と顧客をキャッシュして、Odoo API 呼び出しを減らします。製品または顧客が更新されたときにキャッシュを無効にします。

Webhook 処理の同時実行性

大容量ストアの場合は、Webhook を同時に処理します。つまり、複数のワーカーがメッセージ キューから同時にプルします。冪等性キー チェックでデータベース レベルのロックを使用して、2 人のワーカーが同時に同じ注文を作成することを防ぐことで、同時実行の安全性を確保します。

---

よくある質問

Webhook ベースの自動化により、Shopify の注文はどれくらい早く Odoo に表示されますか?

Webhook ベースの統合が適切に設定されている場合、Shopify の注文は注文後 2 ～ 10 秒以内に Odoo に表示されます。これには、Webhook 配信、HMAC 検証、顧客解決、製品照合、販売注文の作成が含まれます。 Cron ベースの代替手段では、ポーリング間隔に応じて 5 ～ 60 分の遅延が追加されます。

Shopify の注文が入ったときに Odoo がダウンしたらどうなりますか?

統合のメッセージ キューは、Odoo が利用可能になるまで注文 Webhook ペイロードを保持します。 Odoo がオンラインに戻ると、キューはすべての保留中の注文を順番に処理します。また、Shopify は失敗した Webhook 配信を最大 48 時間再試行し、二次的なセーフティ ネットを提供します。統合で永続メッセージキューを使用する場合、注文が失われることはありません。

複数の Shopify ストアから 1 つの Odoo インスタンスに注文をインポートできますか?

はい。各 Shopify ストアは、独自の API 認証情報と Webhook サブスクリプションのセットを介して接続します。統合により、各注文にソース ストアがタグ付けされるため (カスタム フィールドまたは Odoo 営業チームを使用)、ストアごとにレポートできるようになります。カタログ戦略に応じて、製品を店舗間で共有したり、店舗ごとに共有したりできます。

統合では Shopify 下書き注文はどのように処理されますか?

下書き注文 (電話注文または B2B 見積のために販売者によって作成される) は、下書きとして作成されたときではなく、注文が完了した (支払われた) ときにインポートする必要があります。ドラフト注文が実際の注文に変換されるときに起動される、orders/create webhook をサブスクライブします。または、draft_orders/update をサブスクライブし、ステータスが「完了」に変わった場合にのみインポートします。

Shopify POS の注文はどうなりますか?同じパイプラインに従いますか?

Shopify POS 注文は、オンライン注文と同じ注文/Webhook を作成します。統合ではそれらを同様に処理できますが、POS 注文に別の Odoo 営業チームまたはレポートのソースをタグ付けすることもできます。 POS 注文には、現金または外部端末による支払い方法が含まれる場合もあります。これらには、異なる Odoo 支払いジャーナル構成が必要です。

インポート後の注文の編集（販売者が Shopify で注文を編集するなど）はどのように処理すればよいですか?

Shopify は、注文が編集されると、注文/更新された Webhook を起動します。統合では、更新された注文を既存の Odoo 販売注文と比較し、追加された品目、削除された品目、数量の変更、または価格調整などの差異を適用する必要があります。これは統合の最も複雑な部分の 1 つであり、一部の実装では Odoo SO をキャンセルして再作成することでこれを処理します。これは簡単ですが、より多くの会計エントリが作成されます。

オートメーションは Shopify サブスクリプション アプリからのサブスクリプション注文を処理できますか?

サブスクリプション注文 (リチャージ、ボールド サブスクリプション、または Shopify ネイティブ サブスクリプションから) は、標準注文をトリガーし、定期的な請求ごとに Webhook を作成します。統合では、他の注文と同様にそれらをインポートします。定期的な注文を Odoo サブスクリプション レコードにリンクするには、アプリのメタフィールドのサブスクリプション ID を参照として使用し、関連するすべての Odoo 販売注文を 1 つの Odoo サブスクリプションに関連付けます。

---

ECOSIRE による実装

プロダクショングレードのShopify-to-Odoo注文インポートパイプラインを構築するには、部分的な支払い、デジタルアイテムと物理的なアイテムの両方を含む注文、複雑な税務管轄区域、複数の倉庫ルーティング、ベンダーのドロップシップフルフィルメントなど、本番環境で遭遇するまで明らかではない数十のエッジケースを処理する必要があります。

ECOSIRE は、数百の Shopify 加盟店にこのパイプラインを実装しました。当社の Shopify 統合サービス には、このガイドで説明されている完全なパイプラインによる完全な注文の自動化、すべての一般的なエッジ ケースに対する事前構築された処理、リアルタイムの監視とアラート、API の進化に伴う継続的なメンテナンスが含まれます。

財務面の自動化も検討している企業の場合は、Shopify + Odoo 会計統合 のガイドを参照するか、Shopify-Odoo コネクタの比較 でオプションを比較してください。

相談をスケジュールして、Shopify の注文自動化要件について統合チームと話し合ってください。