标题：“Shopify API 集成指南：2026 年构建自定义商务解决方案” 描述：“Shopify API 集成的综合指南，涵盖管理 API、店面 API、Webhooks、身份验证、速率限制和构建自定义应用程序。” 日期：“2026-03-05” 作者：《ECOSIRE研发团队》标签：[“shopify”、“api 集成”、“graphql”、“webhooks”、“自定义开发”]

Shopify API 集成指南：2026 年构建自定义商务解决方案

Shopify 为全球超过 400 万家在线商店提供支持，该平台的真正潜力通过其强大的 API 套件得以释放。无论您是将库存与 ERP 系统同步、构建无头店面，还是为 Shopify 应用商店创建公共应用程序，了解 API 环境都至关重要。本指南提供了 Shopify API 集成的全面技术概述，涵盖身份验证、速率限制、Webhook 架构以及 ECOSIRE 工程师在客户项目中应用的生产就绪模式。

要点

Shopify 提供四个主要 API——管理、店面、合作伙伴和支付应用程序——每个 API 都通过不同的身份验证模型提供不同的用例。
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 |支付提供商、替代结账方式 |

对于大多数自定义商务解决方案，管理 API 和店面 API 可以满足 90% 的要求。管理 API 是服务器端操作的主力，而店面 API 则为您需要产品数据、购物车管理或结帐启动的任何面向客户的体验提供支持。

如果您正在评估是否构建自定义 Shopify 集成，我们的团队可以帮助确定项目范围。详细了解我们的 Shopify 应用开发服务。

GraphQL 与 REST

Shopify 为 Admin API 维护 GraphQL 和 REST 端点，但发展轨迹很明确：GraphQL 是未来。自 2023 年以来，所有新的 Admin API 功能都是 GraphQL 独有的。

比较

|尺寸|休息 | GraphQL | |------------|------|---------| | 数据获取 |固定响应形状；过度获取常见|准确请求您需要的字段 | | 嵌套资源 |多次往返请求 |带有嵌套选择的单个查询 | | 速率限制 | 40 个请求/秒（漏桶）| 1,000 个成本点/秒（根据查询计算）| | 分页 |基于链接标题的光标分页 |使用 pageInfo | 的中继式光标分页 | 批量操作 |不可用 |通过 bulkOperationRunQuery 提供本机批量查询和突变支持 | | 新功能 |冷冻；没有新的端点|所有新功能首先登陆这里 | | 网络钩子 |支持 |通过 webhookSubscriptionCreate 突变的基于订阅的 webhooks |

何时使用哪个

当您进行简单的单一资源操作（例如检查单个订单状态）并且您的现有代码库已具有 REST 客户端基础架构时，请使用 REST。将 GraphQL 用于其他一切，尤其是当您需要嵌套数据（一次调用中包含订单项、产品和履行状态的订单）、批量导出或访问元对象和函数等较新的平台功能时。

迁移路径

如果您的集成当前依赖于 REST，请首先优先考虑迁移大容量端点。迁移到 GraphQL 后，批量数据导出、产品目录查询和订单列表操作可带来最大的性能提升。 Shopify 的 bulkOperationRunQuery 突变可以异步导出数百万条记录，取代原本需要数百次分页 REST 调用的记录。

身份验证和授权

Shopify 支持多种身份验证流程，具体取决于应用程序类型和部署模型。

OAuth 2.0（公共和自定义应用程序）

商家安装 Shopify 应用的标准流程：

商家从 Shopify 应用商店或直接安装链接启动安装。
您的应用程序将重定向到 https://{shop}.myshopify.com/admin/oauth/authorize 以及您的 client_id、请求的 scopes 和 redirect_uri。
商户批准所请求的范围。
Shopify 使用临时 code 重定向回来。
您的服务器通过 POST /admin/oauth/access_token 将代码交换为永久 access_token。

访问范围

请求所需的最小范围。 Shopify 会审核公共应用程序的范围请求，过多的范围请求是常见的拒绝原因。

|范围 |访问 | |--------|--------| | 代码0 / 代码1 |产品目录| | 代码0 / 代码1 |订单管理 | | 代码0 / 代码1 |客户记录| | 代码0 / 代码1 |库存水平和位置| | 代码0 / 代码1 |履行和跟踪|

会话令牌（嵌入式应用程序）

对于嵌入 Shopify 管理员中的应用程序，会话令牌会替换 cookie。 Shopify App Bridge 库会发出 JWT，您的后端会使用应用程序的 API 密钥进行验证。这消除了第三方 cookie 问题并简化了嵌入式体验的身份验证流程。

API 密钥身份验证（自定义/私人应用程序）

对于不需要 OAuth 的单商店集成，直接在 Shopify 管理员中创建的自定义应用程序会提供访问令牌，而无需重定向流。这是内部工具和私有集成的最简单路径。

Webhook 架构

轮询 API 进行更改既浪费又缓慢。 Shopify Webhook 近乎实时地将事件推送到您的应用程序。

事件驱动集成

为您的集成关心的事件注册 webhook。常见的订阅包括：

orders/create、orders/updated、orders/paid -- 触发履行工作流程、ERP 同步或通知管道。
products/update、products/delete -- 保持外部目录或搜索索引最新。
inventory_levels/update -- 跨渠道和仓库同步库存。
app/uninstalled -- 清理商家数据并撤销存储的凭据。

强制性 GDPR Webhook

Shopify 要求所有应用程序处理三个与 GDPR 相关的 Webhook：

customers/data_request -- 响应给定客户的所有存储数据。
customers/redact -- 删除给定客户的所有存储数据。
shop/redact -- 删除卸载您的应用程序的商店的所有存储数据。

未能实施这些端点将阻止您的应用程序获得 Shopify 应用商店批准。

交付保证和幂等性

Shopify 保证至少一次发货。您的 Webhook 处理程序必须是幂等的——处理相同的 Webhook 负载两次应该产生相同的结果。使用 X-Shopify-Webhook-Id 标头作为重复数据删除键。存储已处理的 Webhook ID 并跳过重复项。

如果您的终端节点返回非 2xx 状态代码，Shopify 会在最多 48 小时内以指数退避方式重试，然后再删除订阅。

速率限制和限制

了解速率限制可以防止您的集成在关键操作期间受到限制。

休息：漏桶

The REST Admin API uses a leaky bucket algorithm with a capacity of 40 requests and a leak rate of 2 requests per second.每个响应都包含 X-Shopify-Shop-Api-Call-Limit（例如 32/40），以便您可以实时监控存储桶填充水平。

GraphQL：基于成本的限制

GraphQL 查询会根据查询复杂性消耗“成本点”。您每秒收到 1,000 个点，存储桶最大值为 2,000。每个响应都包含一个 throttleStatus 扩展，其中包含 currentlyAvailable、maximumAvailable 和 restoreRate 字段。一个简单的单对象查询可能会花费 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 webhooks 以检测通过其他渠道或直接在 Shopify 后台所做的更改。

订单路由

对于拥有多个仓库或履行合作伙伴的商家，实施订单路由逻辑来评估库存可用性、运输邻近性和履行成本。 Shopify 的履行订单 API 提供了将履行责任分配给特定位置或第三方服务的原语。

客户数据同步

在 Shopify 和外部 CRM 或营销平台之间同步客户记录需要处理合并冲突、同意状态和数据格式差异。使用 customers/update webhook 作为触发器并实施冲突解决策略（例如，通过时间戳比较来确定最后写入获胜，或指定真实来源）。

构建自定义 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 webhooks 和边缘情况（例如部分履行的订单、退款）非常有价值。

开发商店

通过您的 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 并进行比较。还要验证 state 参数与您在 OAuth 流程开始时生成的随机数是否匹配，以防止 CSRF 攻击。

API 凭证轮换

定期轮换 API 凭据。对于自定义应用程序，通过 Shopify 管理员重新生成访问令牌。对于具有 OAuth 的公共应用程序，访问令牌是永久性的，但有范围 - 如果您怀疑令牌已被泄露，请通过卸载并重新安装应用程序来撤销它。

范围最小化

仅请求您的应用实际需要的访问范围。当 read 足够时，避免请求 write 访问。 Shopify 的应用程序审核团队会仔细审查范围请求，超出范围的应用程序将面临拒绝或额外的审核周期。

数据处理

切勿存储原始信用卡数据。 Shopify 处理结帐的 PCI 合规性，您的集成永远不需要直接访问支付卡号。对于客户 PII，加密静态数据、实施访问控制并及时满足 GDPR 数据删除请求。

常见问题

管理 API 和店面 API 之间有什么区别？

管理 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 以指数退避时间重试失败的 Webhook 交付，最长可达 48 小时。如果所有重试均失败，则 Webhook 订阅将自动删除。您的应用程序应定期验证其 Webhook 订阅是否处于活动状态，并重新注册任何已删除的订阅。实施健康检查，将注册的 Webhook 与预期订阅进行比较。

我是否需要 Shopify Plus 计划才能访问 API？

不需要。所有 Shopify 套餐（包括 Basic）都提供 API 访问。但是，某些功能（例如用于 SSO 的 Multipass API、一些结帐自定义功能以及更高的 API 速率限制）是 Shopify Plus 独有的。

构建您的 Shopify 与 ECOSIRE 集成

无论您需要轻量级 Webhook 集成、完整的 ERP 连接器还是 Shopify 应用商店的自定义公共应用程序，ECOSIRE 的工程团队都拥有提供生产级解决方案的专业知识。我们建立并维护了跨行业的 Shopify 集成，包括零售、制造和批发分销。

联系 ECOSIRE 讨论您的 Shopify 集成要求并获取详细的技术提案。

Shopify API 集成指南：2026 年连接您的系统