尧图网页设计 
很多年前我做传统外贸独立站最烦的就是平台孤岛问题——网站、ERP、物流、支付各管各的订单来了靠人工录。后面转型做跨境电商接触了Shopify发现这套系统最有价值的地方不是模板多好看而是它给了你一套完整的开发对接能力。简单说你可以通过官方API把自己的业务系统、海外仓、ERP、支付渠道全部跟Shopify串起来订单自动同步、库存自动扣减、物流单自动回填。这篇文章我基于自己实际跑过的项目把Shopify开发对接的完整流程、关键决策点和踩坑记录都梳理一遍希望对正在做或准备做这类项目的朋友有参考价值。1. 接手Shopify项目之前先把“开发对接”这四个字拆明白很多朋友一上来就问“Shopify怎么二次开发”其实这个说法本身就把方向带偏了。Shopify是SaaS平台不是开源系统你几乎不太可能去改它底层代码。真正说的“开发对接”是围绕它的Admin API、Storefront API、Webhook、App Bridge和Liquid模板体系做两件事一是把自己的系统“接”进去二是把Shopify的数据“取”出来给你或者给你的业务方用。1.1 项目类型先分清当你是做集成不是做定制跨境电商场景里Shopify开发对接的项目大致分成三类第一类是前后端定制。比如做品牌官网需要定制首页交互、产品展示逻辑、落地页模板这类工作主要围绕Liquid模板和Theme App Extensions展开表面看是“做网站”本质还是前端开发只不过运行在Shopify的规则内。第二类是业务系统集成。这是最常见的比如把Shopify订单同步到自建ERP把海外仓库存回传到Shopify把定制支付方式或者快递对接进下单流程。这类工作全部走API和模板没关系。第三类是生态插件开发。开发一个独立的Shopify App上架到App Store给多个商家用。这时候你要考虑多租户、流量计费、安装授权、订阅计费等复杂度比前两类高一个量级。先确认你做的是哪一类直接决定了后续要不要创建Custom App要不要处理OAuth授权要不要考虑多店铺隔离。很多外包团队在项目开始时没确认清楚做到一半才发现客户要的是“类似竞品的App”结果架构重来进度全乱。1.2 为什么Shopify适合跨境电商业务底座以往做跨境独立站常见选择是Magento、OpenCart、WooCommerce再加一套自研。缺点很明显高性能部署要自己操心安全补丁要自己盯数据库优化要做还要应付各种恶意攻击。Shopify把所有底层都给你管了服务器、带宽、CDN、支付合规、SSL证书这些都不用碰。但这不是最关键的。Shopify真正强的是把“电商能力”做成了标准化的API服务商品、订单、客户、库存、物流、支付、折扣、营销、多语言、多币种每一个能力都有对应的REST或者GraphQL端点。对开发者来说这是一个极其稳定的基础设施——凌晨三点Shopify的订单写入不会挂。跨境电商最怕什么怕的是大促期间系统宕机怕的是数据对不上账。这两点Shopify本身就解决得比较好。另一个容易被忽视的点是App机制。Shopify生态有一整套开发者规范从权限申请到数据保护到UI交互都有明确要求。这意味着你对接的域名、接口甚至数据展示方式都是被限定的。初看是约束实际做久了会发现这是保障——至少对接方之间不会出现“各说各话”的混乱。1.3 对接前必须想清楚的四个问题在写第一行代码之前建议客户先坐下来把下面四个问题拍板系统边界哪些数据必须实时同步哪些允许定时批量同步比如库存是实时扣减订单明细可能一小时同步一次也行。数据归属客户数据是只留在Shopify还是要回流到你自己的CRM跨境电商涉及到欧盟GDPR这个问题不是拍脑袋决定的。支付与结算是直接用Shopify Payments还是用第三方支付还是需要自己对接当地支付渠道这决定了你是否需要写Payment App Extension。容错要求同步失败怎么办需要重试机制还是会话跟踪同步到一半断了要不要保证两端幂等这些问题不解决后面所有技术方案都是空谈。我有一个习惯开项目前先输出一份“对接需求确认单”把这些边界写成文字让客户确认签字。后续扯皮的事情能少掉一大半。2. 环境与账号准备没有一套干净的环境后面全是坑有些人刚拿到开发账号就急着去调用API结果授权报错、Scope不对、Webhook验签失败。大部分问题不是代码问题是环境没准备好。2.1 开发店铺与合作伙伴账号的搭建开发Shopify集成代开发环境主要是这三样Shopify Partners账号用于创建和管理开发应用一个开发店铺Development Store用来测试一个或多个认证域名取决于你要不要自定义店铺前端操作路径不复杂注册Partners账号后在“应用”里创建应用选择“开发店铺”作为安装环境。这里有一个细节Partners账号创建的应用可以安装到你名下所有的开发店铺方便做多店铺场景测试。如果你的项目需要仿真生产环境记得不要用试用版商店那里面不少功能锁着比如自定义应用安装名额、部分接口权限。还有一点容易被忽略Shopify的域名默认是“xxx.myshopify.com”但你做跨境电商为了品牌和信任最好提前配自定义域名。这个域名要装修SSL证书好在Shopify自带SSL。不过要注意如果你要测试“Shopify应用嵌入”里的App Bridge功能对域名是有要求的必须HTTPS且不能被ifr当前浏览器阻断。2.2 创建Custom App并拿到密钥对单体商家集成项目最简单的方式是直接在店铺后台创建Custom App。步骤是店铺后台 - 设置 - 应用和销售渠道 - 开发应用 - 创建应用。创建完成之后重点看三个东西API密钥、API密钥密码、Admin API访问令牌。注意区分API Key是公开的Secret是私密的Access Token是真正用于调接口的凭证。很多人第一次做时把API Key当成Token用结果一直401。Custom App的好处是权限可以自己配不需要经过Shopify应用审核。但缺点是它只针对单个商店升级成多商户应用会很麻烦。所以如果项目是“给一个品牌方做对接”Custom App就够了如果是“开发一个给很多商家用的插件”那必须走Public App路线需要提交审核。这里我建议做大客户私有化集成用Custom App做SaaS工具只能用Public App。两者代码逻辑99%一样区别在授权和审核环节。2.3 API版本与Scope权限配置Shopify升级版本的节奏比较快基本上一年有几次版本更新。写代码的时候一定要在API请求路径里声明版本号。当前比较成熟的是2024-01到2024-10这一代新项目建议直接使用最新稳定版但要研究一下Changelog里的破坏性变更。Scope配置是另一个容易踩坑的点。每次调用接口都需要对应的权限范围。如果你只想要读订单却申请了“写订单”权限Shopify在安装授权时会弹出一条明显的权限提示商家会困惑。权限范围最小化原则绝对要遵守写订单的Scope不别顺手勾上写客户免得后续安全审核被卡。操作上REST API的Scope是在Custom App后台的“Admin API权限”里勾选而GraphQL在底层用的是同一套权限模型。勾选Scope之后安装时把应用重新“安装”一次才会生效很多人改了Scope后发现没变化就是因为漏了重装。2.4 本地环境与工具链选择开发Shopify对接本地环境不复杂但有几个工具是必需品一个能调试OAuth流程的本地环境nginx反向代理都行但一定要HTTPS。Shopify App的回调地址必须HTTPS除非你把地址填成localhostShopify会把它当例外处理。真实线上回调的URL必须走HTTPS。API调试工具Postman或者Insomnia把Header中的X-Shopify-Access-Token和X-Shopify-Api-Version配好调试效率高很多。Webhook测试工具本地开发时建议用ngrok一类的隧道工具把内网暴露到公网这样Shopify能直接回调到你本地。注意这只是调试手段上线必须切换到正式的webhook端点。另外我强烈建议在项目里尽早加入环境变量管理SHOPIFY_API_KEY、SHOPIFY_API_SECRET、SCOPES、SHOP_DOMAIN这些全部走env别写死在代码里。因为这个项目一旦涉及多店铺你几乎肯定要重构到那时候环境变量能让你少改很多文件。3. 核心对接流程逐一拆解认证、鉴权、数据交互这一节是整个项目的主体也是大多数人理解的“对接”环节。我会按OAuth授权、API调用、Webhook、应用嵌入四个部分展开。3.1 OAuth授权流程与Token获取Shopify现在的授权方式是OAuth 2.0授权码模式流程大致是商家点击应用安装链接Shopify构建授权页面展示应用需要的权限商家同意后Shopify重定向回你的回调地址并带上临时授权码code你用这个code加App Secret请求token端点拿到正式Access Token后续所有请求都用这个Access Token这里有两个细节非常容易被坑到第一个是临时授权码只能用一次且过期极快。很多人会漏掉“在一次请求里保存code到数据库”结果是Shopify第二次回调时再拿同一个code去换token直接报错。回调接口必须幂等处理。第二个是验证回调的真实性。Shopify在重定向时会在URL参数里带一个hmac参数你要用App Secret对query字符串做HMAC-SHA256签名比对签名一致才认为是Shopify发的。这个步骤不是你上线后能偷懒不做的——因为你的回调URL如果被猜到攻击者完全可以伪造一次“安装”让自己的服务器拿到Access Token。换到Token之后还要把token存起来。存储位置要考虑多店铺场景通常是shop域名为主键一条记录一个token。如果做Public App要多存一个状态比如“已安装但欠费”和“已卸载”方面后续做自动清理。代码层面核心就是发一个POST请求import requests # 第一步回调拿到code后用code换取access_token def exchange_code_for_token(code, shop, api_key, api_secret): url fhttps://{shop}/admin/oauth/access_token payload { client_id: api_key, client_secret: api_secret, code: code } resp requests.post(url, jsonpayload) resp.raise_for_status() return resp.json().get(access_token)用token请求订单接口curl -X GET \ https://your-shop.myshopify.com/admin/api/2024-10/orders.json?statusanylimit50 \ -H X-Shopify-Access-Token: shpat_你的token \ -H Content-Type: application/json3.2 调用Admin APIREST与GraphQL怎么选Shopify同时提供REST和GraphQL两套接口很多新手不知道选哪个。我的建议是新功能尽量用GraphQL海外仓对接、库存同步这种追求效率和可维护性的场景优先选GraphQL。原因有几个。REST的历史包袱重比如拿一个订单默认返回的是简化字段你要拿到顾客的所有地址还要再发一次请求而GraphQL可以在一个请求里嵌套查询一次拿全。REST分页基于Offset订单量大时候会有漏数据风险GraphQL分页基于Cursor稳定得多。库存、订单这种高频数据场景GraphQL可以明显减少请求次数避免触发API限流。GraphQL请求示例query { orders(first: 50, query: created_at:2024-01-01) { edges { node { id name displayFinancialStatus customer { id email firstName lastName } lineItems(first: 10) { edges { node { title quantity sku } } } } cursor } pageInfo { hasNextPage endCursor } } }用GraphQL要注意一点Shopify GraphQL是一个统一的端点返回结构非常严格所有字段必须明确声明。好处是响应数据里不会有你不需要的字段坏处是写查询语句时要花点时间。接口调用过程中最头疼的是限流。REST是按Bucket计算GraphQL是按成本计算。简单说你每次GraphQL请求都有一个costShopify根据请求复杂度计算分值超过阈值就返回429。这时不要傻傻地无限重试要做指数退避并记录一下当前限流窗口的剩余量。3.3 Webhook订阅与HMAC验签同步数据最可靠的姿势是Webhook。比如订单创建、订单更新、发货完成、库存变更这些事件Shopify会在发生后立刻推送一个JSON结构到你的回调地址。你不用去轮询拉数据既省资源又及时。订阅Webhook的代码大致是这样curl -X POST \ https://your-shop.myshopify.com/admin/api/2024-10/webhooks.json \ -H X-Shopify-Access-Token: 你的token \ -H Content-Type: application/json \ -d { webhook: { topic: orders/create, address: https://yourapi.com/webhooks/orders/create, format: json } }Webhook回调处理有一个核心安全问题就是验签。Shopify会在每个POST请求的Header里带X-Shopify-Hmac-SHA256你需要用App Secret对请求体做HMAC-SHA256签名然后对比是否一致。签名不通过的直接丢掉不能进业务逻辑。验签逻辑参考import hmac import hashlib def verify_webhook(data, hmac_header, secret): digest hmac.new( secret.encode(utf-8), data, hashlib.sha256 ).hexdigest() return hmac.compare_digest(digest, hmac_header)这里有一个容易忽略的点Webhook签名验证只认原始请求体body必须原样验签不能先JSON解析再重新序列化再验签。因为JSON字段顺序变了签名就对不上了。另外一个常见问题是重复推送。Shopify的Webhook保证“至少一次”在某些异常场景下会重试。所以你的Webhook处理逻辑必须是幂等的——用订单ID或者事件唯一ID做去重比如在数据库里建一个webhook_received_log表同一ID只允许消费一次。否则你的ERP系统会出现重复订单客户那边会非常难受。3.4 前端与应用嵌入App Bridge与主题扩展有时候对接不单是后端API的事还要在Shopify店铺后台或者前端页面加一些UI。这就要用到App Bridge和Theme App Extension。App Bridge是Shopify提供的一套JS SDK用于让独立应用页面嵌入到店铺后台并能访问到店铺的基础信息、发起弹窗、跳转路由。要注意的是App Bridge需要提供一个“应用代理”或者“应用URL”这个地址必须支持HTTPS。如果应用页面需要读取Session Token而不是直接读之前拿到的Access Token因为后台页面里的前端请求无法直接携带Token需要通过App Bridge的Session Token验证方式换取。Liquid模板和Theme App Extension是另一些路子用于在店铺前台展示商品、购物车区块、横幅等。如果你要对店铺主题做深度定制最标准的方式是建一个Theme App Extension然后让商家在主题编辑器里启用。这样你的App卸载后主题里的代码块也会被移除不会给商家留下脏代码。这里提醒千万别为了省事直接把 Shopify开发对接实践：API、Webhook与跨境电商系统集成攻略
很多年前我做传统外贸独立站最烦的就是平台孤岛问题——网站、ERP、物流、支付各管各的订单来了靠人工录。后面转型做跨境电商接触了Shopify发现这套系统最有价值的地方不是模板多好看而是它给了你一套完整的开发对接能力。简单说你可以通过官方API把自己的业务系统、海外仓、ERP、支付渠道全部跟Shopify串起来订单自动同步、库存自动扣减、物流单自动回填。这篇文章我基于自己实际跑过的项目把Shopify开发对接的完整流程、关键决策点和踩坑记录都梳理一遍希望对正在做或准备做这类项目的朋友有参考价值。1. 接手Shopify项目之前先把“开发对接”这四个字拆明白很多朋友一上来就问“Shopify怎么二次开发”其实这个说法本身就把方向带偏了。Shopify是SaaS平台不是开源系统你几乎不太可能去改它底层代码。真正说的“开发对接”是围绕它的Admin API、Storefront API、Webhook、App Bridge和Liquid模板体系做两件事一是把自己的系统“接”进去二是把Shopify的数据“取”出来给你或者给你的业务方用。1.1 项目类型先分清当你是做集成不是做定制跨境电商场景里Shopify开发对接的项目大致分成三类第一类是前后端定制。比如做品牌官网需要定制首页交互、产品展示逻辑、落地页模板这类工作主要围绕Liquid模板和Theme App Extensions展开表面看是“做网站”本质还是前端开发只不过运行在Shopify的规则内。第二类是业务系统集成。这是最常见的比如把Shopify订单同步到自建ERP把海外仓库存回传到Shopify把定制支付方式或者快递对接进下单流程。这类工作全部走API和模板没关系。第三类是生态插件开发。开发一个独立的Shopify App上架到App Store给多个商家用。这时候你要考虑多租户、流量计费、安装授权、订阅计费等复杂度比前两类高一个量级。先确认你做的是哪一类直接决定了后续要不要创建Custom App要不要处理OAuth授权要不要考虑多店铺隔离。很多外包团队在项目开始时没确认清楚做到一半才发现客户要的是“类似竞品的App”结果架构重来进度全乱。1.2 为什么Shopify适合跨境电商业务底座以往做跨境独立站常见选择是Magento、OpenCart、WooCommerce再加一套自研。缺点很明显高性能部署要自己操心安全补丁要自己盯数据库优化要做还要应付各种恶意攻击。Shopify把所有底层都给你管了服务器、带宽、CDN、支付合规、SSL证书这些都不用碰。但这不是最关键的。Shopify真正强的是把“电商能力”做成了标准化的API服务商品、订单、客户、库存、物流、支付、折扣、营销、多语言、多币种每一个能力都有对应的REST或者GraphQL端点。对开发者来说这是一个极其稳定的基础设施——凌晨三点Shopify的订单写入不会挂。跨境电商最怕什么怕的是大促期间系统宕机怕的是数据对不上账。这两点Shopify本身就解决得比较好。另一个容易被忽视的点是App机制。Shopify生态有一整套开发者规范从权限申请到数据保护到UI交互都有明确要求。这意味着你对接的域名、接口甚至数据展示方式都是被限定的。初看是约束实际做久了会发现这是保障——至少对接方之间不会出现“各说各话”的混乱。1.3 对接前必须想清楚的四个问题在写第一行代码之前建议客户先坐下来把下面四个问题拍板系统边界哪些数据必须实时同步哪些允许定时批量同步比如库存是实时扣减订单明细可能一小时同步一次也行。数据归属客户数据是只留在Shopify还是要回流到你自己的CRM跨境电商涉及到欧盟GDPR这个问题不是拍脑袋决定的。支付与结算是直接用Shopify Payments还是用第三方支付还是需要自己对接当地支付渠道这决定了你是否需要写Payment App Extension。容错要求同步失败怎么办需要重试机制还是会话跟踪同步到一半断了要不要保证两端幂等这些问题不解决后面所有技术方案都是空谈。我有一个习惯开项目前先输出一份“对接需求确认单”把这些边界写成文字让客户确认签字。后续扯皮的事情能少掉一大半。2. 环境与账号准备没有一套干净的环境后面全是坑有些人刚拿到开发账号就急着去调用API结果授权报错、Scope不对、Webhook验签失败。大部分问题不是代码问题是环境没准备好。2.1 开发店铺与合作伙伴账号的搭建开发Shopify集成代开发环境主要是这三样Shopify Partners账号用于创建和管理开发应用一个开发店铺Development Store用来测试一个或多个认证域名取决于你要不要自定义店铺前端操作路径不复杂注册Partners账号后在“应用”里创建应用选择“开发店铺”作为安装环境。这里有一个细节Partners账号创建的应用可以安装到你名下所有的开发店铺方便做多店铺场景测试。如果你的项目需要仿真生产环境记得不要用试用版商店那里面不少功能锁着比如自定义应用安装名额、部分接口权限。还有一点容易被忽略Shopify的域名默认是“xxx.myshopify.com”但你做跨境电商为了品牌和信任最好提前配自定义域名。这个域名要装修SSL证书好在Shopify自带SSL。不过要注意如果你要测试“Shopify应用嵌入”里的App Bridge功能对域名是有要求的必须HTTPS且不能被ifr当前浏览器阻断。2.2 创建Custom App并拿到密钥对单体商家集成项目最简单的方式是直接在店铺后台创建Custom App。步骤是店铺后台 - 设置 - 应用和销售渠道 - 开发应用 - 创建应用。创建完成之后重点看三个东西API密钥、API密钥密码、Admin API访问令牌。注意区分API Key是公开的Secret是私密的Access Token是真正用于调接口的凭证。很多人第一次做时把API Key当成Token用结果一直401。Custom App的好处是权限可以自己配不需要经过Shopify应用审核。但缺点是它只针对单个商店升级成多商户应用会很麻烦。所以如果项目是“给一个品牌方做对接”Custom App就够了如果是“开发一个给很多商家用的插件”那必须走Public App路线需要提交审核。这里我建议做大客户私有化集成用Custom App做SaaS工具只能用Public App。两者代码逻辑99%一样区别在授权和审核环节。2.3 API版本与Scope权限配置Shopify升级版本的节奏比较快基本上一年有几次版本更新。写代码的时候一定要在API请求路径里声明版本号。当前比较成熟的是2024-01到2024-10这一代新项目建议直接使用最新稳定版但要研究一下Changelog里的破坏性变更。Scope配置是另一个容易踩坑的点。每次调用接口都需要对应的权限范围。如果你只想要读订单却申请了“写订单”权限Shopify在安装授权时会弹出一条明显的权限提示商家会困惑。权限范围最小化原则绝对要遵守写订单的Scope不别顺手勾上写客户免得后续安全审核被卡。操作上REST API的Scope是在Custom App后台的“Admin API权限”里勾选而GraphQL在底层用的是同一套权限模型。勾选Scope之后安装时把应用重新“安装”一次才会生效很多人改了Scope后发现没变化就是因为漏了重装。2.4 本地环境与工具链选择开发Shopify对接本地环境不复杂但有几个工具是必需品一个能调试OAuth流程的本地环境nginx反向代理都行但一定要HTTPS。Shopify App的回调地址必须HTTPS除非你把地址填成localhostShopify会把它当例外处理。真实线上回调的URL必须走HTTPS。API调试工具Postman或者Insomnia把Header中的X-Shopify-Access-Token和X-Shopify-Api-Version配好调试效率高很多。Webhook测试工具本地开发时建议用ngrok一类的隧道工具把内网暴露到公网这样Shopify能直接回调到你本地。注意这只是调试手段上线必须切换到正式的webhook端点。另外我强烈建议在项目里尽早加入环境变量管理SHOPIFY_API_KEY、SHOPIFY_API_SECRET、SCOPES、SHOP_DOMAIN这些全部走env别写死在代码里。因为这个项目一旦涉及多店铺你几乎肯定要重构到那时候环境变量能让你少改很多文件。3. 核心对接流程逐一拆解认证、鉴权、数据交互这一节是整个项目的主体也是大多数人理解的“对接”环节。我会按OAuth授权、API调用、Webhook、应用嵌入四个部分展开。3.1 OAuth授权流程与Token获取Shopify现在的授权方式是OAuth 2.0授权码模式流程大致是商家点击应用安装链接Shopify构建授权页面展示应用需要的权限商家同意后Shopify重定向回你的回调地址并带上临时授权码code你用这个code加App Secret请求token端点拿到正式Access Token后续所有请求都用这个Access Token这里有两个细节非常容易被坑到第一个是临时授权码只能用一次且过期极快。很多人会漏掉“在一次请求里保存code到数据库”结果是Shopify第二次回调时再拿同一个code去换token直接报错。回调接口必须幂等处理。第二个是验证回调的真实性。Shopify在重定向时会在URL参数里带一个hmac参数你要用App Secret对query字符串做HMAC-SHA256签名比对签名一致才认为是Shopify发的。这个步骤不是你上线后能偷懒不做的——因为你的回调URL如果被猜到攻击者完全可以伪造一次“安装”让自己的服务器拿到Access Token。换到Token之后还要把token存起来。存储位置要考虑多店铺场景通常是shop域名为主键一条记录一个token。如果做Public App要多存一个状态比如“已安装但欠费”和“已卸载”方面后续做自动清理。代码层面核心就是发一个POST请求import requests # 第一步回调拿到code后用code换取access_token def exchange_code_for_token(code, shop, api_key, api_secret): url fhttps://{shop}/admin/oauth/access_token payload { client_id: api_key, client_secret: api_secret, code: code } resp requests.post(url, jsonpayload) resp.raise_for_status() return resp.json().get(access_token)用token请求订单接口curl -X GET \ https://your-shop.myshopify.com/admin/api/2024-10/orders.json?statusanylimit50 \ -H X-Shopify-Access-Token: shpat_你的token \ -H Content-Type: application/json3.2 调用Admin APIREST与GraphQL怎么选Shopify同时提供REST和GraphQL两套接口很多新手不知道选哪个。我的建议是新功能尽量用GraphQL海外仓对接、库存同步这种追求效率和可维护性的场景优先选GraphQL。原因有几个。REST的历史包袱重比如拿一个订单默认返回的是简化字段你要拿到顾客的所有地址还要再发一次请求而GraphQL可以在一个请求里嵌套查询一次拿全。REST分页基于Offset订单量大时候会有漏数据风险GraphQL分页基于Cursor稳定得多。库存、订单这种高频数据场景GraphQL可以明显减少请求次数避免触发API限流。GraphQL请求示例query { orders(first: 50, query: created_at:2024-01-01) { edges { node { id name displayFinancialStatus customer { id email firstName lastName } lineItems(first: 10) { edges { node { title quantity sku } } } } cursor } pageInfo { hasNextPage endCursor } } }用GraphQL要注意一点Shopify GraphQL是一个统一的端点返回结构非常严格所有字段必须明确声明。好处是响应数据里不会有你不需要的字段坏处是写查询语句时要花点时间。接口调用过程中最头疼的是限流。REST是按Bucket计算GraphQL是按成本计算。简单说你每次GraphQL请求都有一个costShopify根据请求复杂度计算分值超过阈值就返回429。这时不要傻傻地无限重试要做指数退避并记录一下当前限流窗口的剩余量。3.3 Webhook订阅与HMAC验签同步数据最可靠的姿势是Webhook。比如订单创建、订单更新、发货完成、库存变更这些事件Shopify会在发生后立刻推送一个JSON结构到你的回调地址。你不用去轮询拉数据既省资源又及时。订阅Webhook的代码大致是这样curl -X POST \ https://your-shop.myshopify.com/admin/api/2024-10/webhooks.json \ -H X-Shopify-Access-Token: 你的token \ -H Content-Type: application/json \ -d { webhook: { topic: orders/create, address: https://yourapi.com/webhooks/orders/create, format: json } }Webhook回调处理有一个核心安全问题就是验签。Shopify会在每个POST请求的Header里带X-Shopify-Hmac-SHA256你需要用App Secret对请求体做HMAC-SHA256签名然后对比是否一致。签名不通过的直接丢掉不能进业务逻辑。验签逻辑参考import hmac import hashlib def verify_webhook(data, hmac_header, secret): digest hmac.new( secret.encode(utf-8), data, hashlib.sha256 ).hexdigest() return hmac.compare_digest(digest, hmac_header)这里有一个容易忽略的点Webhook签名验证只认原始请求体body必须原样验签不能先JSON解析再重新序列化再验签。因为JSON字段顺序变了签名就对不上了。另外一个常见问题是重复推送。Shopify的Webhook保证“至少一次”在某些异常场景下会重试。所以你的Webhook处理逻辑必须是幂等的——用订单ID或者事件唯一ID做去重比如在数据库里建一个webhook_received_log表同一ID只允许消费一次。否则你的ERP系统会出现重复订单客户那边会非常难受。3.4 前端与应用嵌入App Bridge与主题扩展有时候对接不单是后端API的事还要在Shopify店铺后台或者前端页面加一些UI。这就要用到App Bridge和Theme App Extension。App Bridge是Shopify提供的一套JS SDK用于让独立应用页面嵌入到店铺后台并能访问到店铺的基础信息、发起弹窗、跳转路由。要注意的是App Bridge需要提供一个“应用代理”或者“应用URL”这个地址必须支持HTTPS。如果应用页面需要读取Session Token而不是直接读之前拿到的Access Token因为后台页面里的前端请求无法直接携带Token需要通过App Bridge的Session Token验证方式换取。Liquid模板和Theme App Extension是另一些路子用于在店铺前台展示商品、购物车区块、横幅等。如果你要对店铺主题做深度定制最标准的方式是建一个Theme App Extension然后让商家在主题编辑器里启用。这样你的App卸载后主题里的代码块也会被移除不会给商家留下脏代码。这里提醒千万别为了省事直接把