タイトル: 「Shopify API 統合ガイド: 2026 年のカスタムコマースソリューションの構築」説明: 「Admin API、Storefront API、Webhook、認証、レート制限、カスタムアプリの構築をカバーする Shopify API 統合の包括的なガイド。」日付: "2026-03-05" 著者: 「ECOSIRE 研究開発チーム」タグ: ["shopify"、"api-integration"、"graphql"、"webhooks"、"custom-development"]

Shopify API 統合ガイド: 2026 年のカスタムコマースソリューションの構築

Shopify は世界中で 400 万を超えるオンラインストアを支えており、その堅牢な API スイートを通じてプラットフォームの真の可能性が解き放たれます。在庫を ERP システムと同期する場合でも、ヘッドレスストアフロントを構築する場合でも、Shopify アプリストア用のパブリックアプリを作成する場合でも、API 環境を理解することが不可欠です。このガイドでは、認証、レート制限、Webhook アーキテクチャ、ECOSIRE エンジニアがクライアントプロジェクト全体に適用する運用対応パターンをカバーする、Shopify API 統合の包括的な技術概要を説明します。

重要なポイント

Shopify は 4 つの主要な API (Admin、Storefront、Partner、Payments アプリ) を提供しており、それぞれが異なる認証モデルで異なるユースケースに対応します。
GraphQL は戦略的な方向性です。 Shopify は REST エンドポイントを段階的に非推奨にしています。新機能は GraphQL のみです。それに応じて統合を計画してください。
Webhook アーキテクチャは、GDPR に準拠し、ポーリングせずに外部システムの同期を維持するために必須です。
レート制限は、REST の場合はリーキーバケットモデル、GraphQL の場合はコストベースのポイントシステムに従います。どちらも、意図的な再試行とバックオフ戦略が必要です。
すべての Webhook および OAuth コールバックでの HMAC 検証は交渉できません。署名の検証をスキップすると、アプリケーションがスプーフィングされたペイロードやデータ改ざんにさらされる可能性があります。

Shopify API のランドスケープ

Shopify は複数の API を公開しており、それぞれが特定の対象ユーザーと統合パターン向けに設計されています。

| API |目的 |認証モデル |典型的な消費者 | |-----|----------|----------|------| | 管理 API |完全な店舗管理 (商品、注文、顧客、フルフィルメント) | OAuth 2.0 / プライベートアプリの認証情報 |バックオフィス統合、ERP コネクタ、カスタム管理ツール | | ストアフロント API |顧客対応コマース (カート、チェックアウト、製品クエリ) |ストアフロントアクセストークン (パブリック) |ヘッドレスフロントエンド、モバイルアプリ、購入ボタン | | パートナー API |パートナーエコシステム全体にわたるアプリとストアの管理 |パートナー API トークン |代理店ダッシュボード、マルチストアツール | | 決済アプリ API |カスタム決済ゲートウェイの統合 |支払いスコープを備えたアプリレベルの OAuth |支払いプロバイダー、代替チェックアウト方法 |

ほとんどのカスタムコマースソリューションでは、Admin API と Storefront API で要件の 90% をカバーします。 Admin API はサーバー側の操作の主力であり、Storefront API は製品データ、カート管理、またはチェックアウトの開始が必要な顧客対応エクスペリエンスを強化します。

カスタムの Shopify 統合を構築するかどうかを評価している場合、私たちのチームがプロジェクトの範囲設定を支援できます。 [Shopify アプリ開発サービス] の詳細については、こちらをご覧ください(/services/shopify/app-development)。

GraphQL と REST の比較

Shopify は、Admin API の GraphQL エンドポイントと REST エンドポイントの両方を維持していますが、その軌跡は明らかです。GraphQL は未来です。 2023 年以降、新しい Admin API 機能はすべて GraphQL 専用になりました。

比較

|寸法 |休憩 |グラフQL | |----------|------|----------| | データの取得 |応答形状を修正。オーバーフェッチが一般的 |必要なフィールドを正確にリクエストします | | ネストされたリソース |複数の往復リクエスト |ネストされた選択を含む単一のクエリ | | レート制限 | 40 リクエスト/秒 (リーキーバケット) | 1,000 コストポイント/秒 (クエリごとに計算) | | ページネーション |リンクヘッダーベースのカーソルページネーション | pageInfo を使用したリレースタイルのカーソルページネーション | | 一括操作 |利用できません | bulkOperationRunQuery によるネイティブの一括クエリとミューテーションのサポート | | 新機能 |凍った;新しいエンドポイントはありません |すべての新機能が最初にここに到着します | | Webhook |サポートされている | webhookSubscriptionCreate 変異によるサブスクリプションベースの Webhook |

いつどれを使用するか

Use REST when you have a simple, single-resource operation -- checking a single order status, for example -- and your existing codebase already has REST client infrastructure.それ以外のすべてには GraphQL を使用します。特に、ネストされたデータ (品目、製品、履行ステータスを 1 回の呼び出しで含む注文)、一括エクスポート、またはメタオブジェクトや関数などの新しいプラットフォーム機能へのアクセスが必要な場合に使用します。

移行パス

現在統合が REST に依存している場合は、まず大容量エンドポイントの移行を優先してください。 GraphQL に移行すると、一括データエクスポート、製品カタログクエリ、および注文リストの操作で最大のパフォーマンス向上が得られます。 Shopify の bulkOperationRunQuery ミューテーションは、何百万ものレコードを非同期にエクスポートでき、通常なら何百ものページ分割された REST 呼び出しが必要となるものを置き換えます。

認証と認可

Shopify は、アプリの種類と展開モデルに応じて複数の認証フローをサポートします。

OAuth 2.0 (パブリックアプリとカスタムアプリ)

販売者がインストールする Shopify アプリの標準的なフロー:

販売者は、Shopify App Store または直接インストールリンクからインストールを開始します。
アプリは、client_id、要求された scopes、および redirect_uri を使用して https://{shop}.myshopify.com/admin/oauth/authorize にリダイレクトします。
販売者は、要求されたスコープを承認します。
Shopify は一時的な code を使用してリダイレクトを返します。
サーバーは、コードを POST /admin/oauth/access_token 経由で永続的な access_token に交換します。

アクセス範囲

必要な最小限のスコープをリクエストします。 Shopify はパブリックアプリのスコープリクエストをレビューしますが、過剰なスコープリクエストは一般的な拒否理由です。

|範囲 |アクセス | |------|----------| | read_products / write_products |製品カタログ | | read_orders / write_orders |注文管理 | | read_customers / write_customers |顧客記録 | | read_inventory / write_inventory |在庫レベルと場所 | | read_fulfillments / write_fulfillments |フルフィルメントと追跡 |

セッショントークン (埋め込みアプリ)

Shopify Admin に埋め込まれたアプリの場合、セッショントークンが Cookie を置き換えます。 Shopify App Bridge ライブラリは、バックエンドがアプリの API シークレットを使用して検証する JWT を発行します。これにより、サードパーティ Cookie の問題が排除され、埋め込みエクスペリエンスの認証フローが簡素化されます。

API キー認証 (カスタム/プライベートアプリ)

OAuth を必要としない単一ストア統合の場合、Shopify Admin で直接作成されたカスタムアプリは、リダイレクトフローなしでアクセストークンを提供します。これは、内部ツールとプライベート統合の最も簡単なパスです。

Webhook アーキテクチャ

変更のために API をポーリングするのは無駄が多く、時間がかかります。 Shopify Webhook は、ほぼリアルタイムでイベントをアプリケーションにプッシュします。

イベント駆動型の統合

統合が対象とするイベントの Webhook を登録します。一般的なサブスクリプションには次のものがあります。

orders/create、orders/updated、orders/paid -- フルフィルメントワークフロー、ERP 同期、または通知パイプラインをトリガーします。
products/update、products/delete -- 外部カタログまたは検索インデックスを最新の状態に保ちます。
inventory_levels/update -- チャネルと倉庫間で在庫を同期します。
app/uninstalled -- 販売者データをクリーンアップし、保存されている認証情報を取り消します。

必須の GDPR Webhook

Shopify では、すべてのアプリが 3 つの GDPR 関連の Webhook を処理する必要があります。

customers/data_request -- 特定の顧客について保存されているすべてのデータで応答します。
customers/redact -- 特定の顧客の保存データをすべて削除します。
shop/redact -- アプリをアンインストールしたショップの保存データをすべて削除します。

これらのエンドポイントを実装しないと、アプリは Shopify App Store の承認からブロックされます。

配信保証と冪等性

Shopify は少なくとも 1 回の配信を保証します。 Webhook ハンドラーは冪等である必要があります。同じ Webhook ペイロードを 2 回処理すると、同じ結果が生成されます。 X-Shopify-Webhook-Id ヘッダーを重複排除キーとして使用します。処理された Webhook ID を保存し、重複をスキップします。

エンドポイントが 2xx 以外のステータスコードを返した場合、Shopify はサブスクリプションを削除する前に、最大 48 時間の指数バックオフで再試行します。

レート制限とスロットリング

レート制限を理解すると、重要な操作中に統合が抑制されるのを防ぐことができます。

残り: 漏れのあるバケツ

REST Admin API は、40 リクエストの容量と 1 秒あたり 2 リクエストのリークレートのリーキーバケットアルゴリズムを使用します。各応答には X-Shopify-Shop-Api-Call-Limit (例: 32/40) が含まれるため、バケットの充填レベルをリアルタイムで監視できます。

GraphQL: コストベースのスロットル

GraphQL クエリは、クエリの複雑さに基づいて「コストポイント」を消費します。 1 秒あたり 1,000 ポイントを受け取り、バケットの最大値は 2,000 です。各応答には、currentlyAvailable、maximumAvailable、および restoreRate フィールドを含む throttleStatus 拡張機能が含まれます。単純な単一オブジェクトのクエリには 1 ～ 2 ポイントのコストがかかる場合があります。ネストされた接続を持つ 250 項目を要求するページ分割されたリストクエリには、500 ポイント以上のコストがかかる可能性があります。

再試行戦略

429 Too Many Requests (REST) または THROTTLED エラー (GraphQL) を受け取ったときに、ジッターを伴う指数バックオフを実装します。おすすめのパターン：

スロットル応答で、base_delay * 2^attempt + random_jitter 待ちます。
500ms のベース遅延から開始します。
最大再試行遅延の上限は 30 秒です。
5 回連続して失敗した場合は、エラーをログに記録し、運用チームに警告します。

一括データ操作の場合は、ページ分割されたクエリよりも常に GraphQL 一括操作を優先します。これらは Shopify のインフラストラクチャ上で非同期的に実行され、同じレート制限の対象にはなりません。

一般的な統合パターン

ERP の同期

最も頻繁に行われるエンタープライズ統合では、Shopify を Odoo などの ERP システムに接続し、双方向のデータフローを実現します。 Shopify で作成された注文はフルフィルメント処理のために ERP に伝達され、ERP の在庫更新はほぼリアルタイムで Shopify に反映されます。

ECOSIRE はまさにこのパターンを専門としています。当社の Odoo 統合サービスには、注文同期、在庫管理、顧客データマッピング、財務調整を処理する Shopify 用の事前構築済みコネクタが含まれています。

在庫管理

複数の場所の在庫には慎重な調整が必要です。 inventorySetQuantities GraphQL ミューテーション (非推奨の REST 在庫調整エンドポイントを置き換える) を使用して、在庫レベルを更新します。 inventory_levels/update Webhook をサブスクライブして、他のチャネルを通じて、または Shopify Admin で直接行われた変更を検出します。

注文のルーティング

複数の倉庫またはフルフィルメントパートナーを持つ販売者の場合は、在庫の可用性、配送の近さ、フルフィルメントコストを評価する注文ルーティングロジックを実装します。 Shopify のフルフィルメント注文 API は、フルフィルメント責任を特定の場所またはサードパーティサービスに割り当てるためのプリミティブを提供します。

顧客データの同期

Shopify と外部 CRM またはマーケティングプラットフォームの間で顧客レコードを同期するには、マージの競合、同意ステータス、データ形式の違いを処理する必要があります。 Use the customers/update webhook as the trigger and implement a conflict resolution strategy (e.g., last-write-wins with timestamp comparison, or source-of-truth designation).

カスタム Shopify アプリの構築

パブリックアプリとカスタムアプリ

|属性 |パブリックアプリ |カスタムアプリ | |----------|-----------|---------------| | 配布 | Shopify アプリストア |単一ストアまたは Shopify Plus 組織 | | レビュープロセス |必須のShopifyレビュー |なし | | OAuth フロー |必須 |オプション (直接トークン) | | 請求 | Shopify 請求 API |直接請求 | | GDPR Webhook |必須 |必須 |

アプリ拡張機能

Shopify の拡張機能のみのアプリアーキテクチャ (2024 年に導入され、現在は標準) では、Shopify 管理、チェックアウト、ストアフロント内で直接レンダリングされる UI 拡張機能の構築が推奨されています。拡張機能は Shopify の UI コンポーネントライブラリを使用して構築され、アプリの一部としてデプロイされます。

主な拡張面には次のものがあります。

Shopify 管理内のカスタムワークフローの 管理アクションとブロック拡張機能。
チェックアウト UI 拡張機能。チェックアウト時にカスタムフィールド、アップセル、またはロイヤルティプログラムの統合を追加します。
テーマアプリ拡張機能 により、コードを変更せずにオンラインストアテーマにアプリの機能を埋め込むことができます。
Shopify のインフラストラクチャ上で実行されるサーバー側ロジック (割引、配送料、支払いのカスタマイズ) の 機能拡張。

Shopify CLI

Shopify CLI (@shopify/cli) は、アプリのスキャフォールディング、ローカル開発、およびデプロイのための標準開発ツールです。 shopify app dev を実行して、ホットリロード、自動 ngrok トンネリング、OAuth が自動的に処理されるローカル開発サーバーを起動します。 Remix (デフォルトのアプリフレームワーク)、Node.js、PHP、および Ruby バックエンドをサポートします。

Shopify 開発を始めたチーム向けのストアセットアップサービスには、開発環境の構成とアーキテクチャの計画が含まれています。

テストとデバッグ

Shopify CLI を使用したローカル開発

shopify app dev はアプリをローカルで起動し、安全なトンネルを作成します。 OAuth リダイレクトは自動的に処理されるため、手動の ngrok 構成を行わずに、開発ストアに対して完全なインストールフローをテストできます。

Webhook テスト

shopify app webhook trigger を使用して、テスト Webhook ペイロードをローカルエンドポイントに送信します。これは、実際のトランザクションを作成せずに GDPR Webhook やエッジケース (部分的に履行された注文、返金など) をテストする場合に非常に役立ちます。

開発ストア

Shopify パートナーアカウントを通じて無制限の開発ストアを作成します。これらのストアは、テストのためにすべての Shopify 機能 (Plus 機能を含む) にアクセスできます。 Shopify CLI の shopify populate コマンドまたは Faker ベースのシードスクリプトを使用してテストデータを入力します。

GraphQL エクスプローラー

Shopify Admin GraphQL Explorer (Admin API ドキュメントからアクセス可能) を使用すると、実際のストアに対して対話的にクエリを構築およびテストできます。コードにクエリを実装する前に、クエリのプロトタイプを作成するために使用します。

ロギングと可観測性

運用環境では、エラーまたは予期しないステータスコードを返すすべての API 応答をログに記録します。すべての応答のレート制限ヘッダーを追跡し、監視システムのメトリクスとして公開します。継続的なスロットルに対するアラートを設定します。これは、統合に最適化が必要であることを示します。

セキュリティのベストプラクティス

HMAC の検証

Shopify からのすべての Webhook ペイロードには X-Shopify-Hmac-SHA256 ヘッダーが含まれています。アプリの API シークレットを使用して生のリクエスト本文の HMAC-SHA256 を計算し、タイミングセーフな比較関数を使用してそれをヘッダー値と比較します。開発中であっても、このステップを決してスキップしないでください。

OAuth コールバック検証

OAuth コールバックの hmac クエリパラメーターを確認します。クエリ文字列 (hmac パラメーターを除く) を再構築し、HMAC を計算して比較します。また、CSRF 攻撃を防ぐために、state パラメーターが OAuth フローの開始時に生成した nonce と一致することを検証します。

API 認証情報のローテーション

API 認証情報を定期的にローテーションします。カスタムアプリの場合は、Shopify 管理者を通じてアクセストークンを再生成します。 OAuth を使用するパブリックアプリの場合、アクセストークンは永続的ですが範囲が限定されています。トークンが侵害された疑いがある場合は、アプリをアンインストールして再インストールしてトークンを取り消してください。

スコープの最小化

アプリが実際に必要とするアクセススコープのみをリクエストします。 read で十分な場合は、write アクセスを要求しないでください。 Shopify のアプリレビューチームは範囲リクエストを精査し、範囲を超えたアプリは拒否または追加のレビューサイクルに直面します。

データの処理

クレジットカードの生のデータは決して保存しないでください。 Shopify はチェックアウトに関する PCI 準拠を処理するため、統合では支払いカード番号に直接アクセスする必要はありません。顧客の PII については、保存データを暗号化し、アクセス制御を実装し、GDPR データ削除リクエストを迅速に受け入れます。

よくある質問

Admin API と Storefront API の違いは何ですか?

Admin API は、ストアデータ (製品、注文、顧客、フルフィルメント) への完全なバックオフィスアクセスを提供し、特定のスコープでの認証されたアクセスを必要とします。 Storefront API は顧客向けエクスペリエンス向けに設計されており、クライアント側のコードに安全に含めることができるパブリックアクセストークンを使用して、制限された読み取り負荷の高いデータセット (製品、コレクション、カート、チェックアウト) を公開します。

同じ統合で REST と GraphQL の両方を使用できますか?

はい。多くの実稼働統合では、特に移行中に両方が使用されます。ただし、REST と GraphQL のレート制限は個別に追跡され、一部の操作 (一括エクスポートなど) は GraphQL 経由でのみ利用できることに注意してください。長期的な保守性を実現するために、GraphQL に統合することを計画します。

Shopify API のバージョン管理はどのように処理すればよいですか?

Shopify は新しい API バージョンを四半期ごとにリリースします (例: 2026-01、2026-04)。各バージョンは約 12 か月間サポートされます。統合を API URL (/admin/api/2026-01/graphql.json など) の特定のバージョンに固定し、四半期ごとのレビューをスケジュールして、古いバージョンが非推奨になる前に新しいバージョンを採用します。

Webhook エンドポイントがダウンした場合はどうなりますか?

Shopify は、最大 48 時間、指数バックオフを使用して失敗した Webhook 配信を再試行します。すべての再試行が失敗した場合、Webhook サブスクリプションは自動的に削除されます。アプリでは、Webhook サブスクリプションがアクティブであることを定期的に確認し、削除されたサブスクリプションを再登録する必要があります。登録された Webhook を予想されるサブスクリプションと比較するヘルスチェックを実装します。

API アクセスには Shopify Plus プランが必要ですか?

いいえ。すべての Shopify プラン (ベーシックを含む) は API アクセスを提供します。ただし、SSO 用のマルチパス API、一部のチェックアウトのカスタマイズ機能、より高い API レート制限などの特定の機能は Shopify Plus 専用です。

ECOSIRE と Shopify の統合を構築する

軽量の Webhook 統合、完全な ERP コネクタ、または Shopify App Store 用のカスタムパブリックアプリが必要な場合でも、ECOSIRE のエンジニアリングチームは実稼働グレードのソリューションを提供する専門知識を持っています。当社は、小売、製造、卸売流通などの業界全体で Shopify の統合を構築し、維持してきました。

ECOSIRE に連絡して、Shopify 統合要件について話し合い、詳細な技術提案を入手してください。