常见问题

FAQ 分类

API 调用

了解如何正确调用 Shoplazza API。

授权

了解如何配置 OAuth 和私有应用 token。

应用管理

管理和配置 Shoplazza 生态中的应用。

账号管理

了解用户账号和权限管理指南。

Webhook

设置并配置用于实时通知的 Webhook。

应用商店

通过 Shoplazza 应用商店中的应用增强店铺功能。

主题扩展

使用主题扩展自定义主题区块和 POD 功能。

API 调用

问：API 调用中推荐如何实现分页？

问题描述：

部分 API 同时支持基于 cursor（token）的分页和基于 page 的分页。但是，开发者有时会在高效获取元数据时遇到困难。

原因：

基于 page 的分页更简单，但在大数据量场景下效率较低。基于 cursor（token）的分页在获取分页数据时性能和准确性更好，因为它会直接关联到下一批数据。

解决方案：

• 建议： API 调用优先使用基于 cursor（token）的分页。仅在不支持 token 分页时使用基于 page 的分页。
• 使用方式： 请参考 Cursor Pagination 文档了解实现细节。

---

问：图片无法正常展示时应该怎么办？

问题描述：

站点部分位置的图片没有正常展示。

原因：

如果图片没有在主题设置中正确配置，就可能出现该问题。

解决方案：

1. 进入 主题装修 → 全局设置 → 图片设计。
2. 按设置要求添加或配置所需图片。

---

问：为什么必填字段传空值时，API 仍允许创建商品？

问题描述：

部分客户发现，即使必填字段传入空值，创建商品仍会成功。这是因为部分 API 会在内部处理默认值。

原因：

某些 API 会为必填字段设置默认值。如果必填字段传入空值，API 会使用预设默认值进行初始化，而不是返回错误。

解决方案：

• 检查参数要求： 调用 API 前，请仔细查看 API 文档中的必填参数及其预期值。
• 联系我们确认： 如果必填字段的行为不清晰，或不符合你的使用场景，请联系支持团队进一步确认。

问：在 PHP 中，日志显示 200 状态正常时，如何获取正确响应？

问题描述：

使用 PHP 调用 API 时，日志显示 200 状态码正常，但响应体为空或内容不正确。

解决方案：

如果你使用兼容 PSR-7 的 HTTP 客户端（例如 Guzzle），可以使用以下代码获取响应内容：

$response->getBody()->getContents();

---

问：订单与运单号的规则是什么？

目前，订单不能拆分或合并。多个订单可以共用同一个运单号。同时，一个订单可以包含多个包裹，每个包裹有各自的运单号。

---

问：total_price 字段的计算逻辑是什么？

税费： total_price 表示顾客最终支付的金额，如适用则包含税费。

额外费用： total_price 包含 additional_total、total_shipping、total_tax、shipping_tax_total 等附加费用，以及小费（total_tip_received）。

计算公式：

📘 字段说明

sub_total：商品总价。

total_shipping：运费总额。

additional_total：附加费用。

total_tax：商品税总额。

shipping_tax_total：运费税总额。

total_tip_received：收到的小费总额。

total_discount：优惠总额（例如商品优惠和优惠码优惠）。

当 sub_total 为不含税（order.config.product_tax_included == false）时：

total_price = (sub_total + total_shipping + additional_total + total_tax + shipping_tax_total + total_tip_received) - total_discount

当 sub_total 为含税（order.config.product_tax_included == true）时：

total_price = (sub_total + total_shipping + additional_total + shipping_tax_total + total_tip_received) - total_discount

PayPal 支付： total_price 反映顾客支付的金额，不包含任何 PayPal 交易手续费，该手续费由平台单独处理。

---

问：buyer_accepts_marketing 字段的用途是什么？

buyer_accepts_marketing 字段表示顾客是否同意接收营销推广：

• 已同意： 商家可以发送促销邮件或优惠信息。
• 未同意： 顾客不会被纳入营销活动。

该字段不会直接影响订单列表或其信息。

---

问：customer.orders_count 字段是否包含已取消或未付款的订单？

orders_count 包含顾客在当前店铺创建的所有订单，无论其状态如何（例如已取消或未付款）。

---

问：同一店铺中，顾客可以使用不同币种支付吗？

可以，店铺支持多币种支付。为保持一致性，所有支付都会换算为店铺的主市场币种。

---

问：我通过 API 创建了订单，但为什么在店铺后台看不到？

这通常是因为订单缺少收货地址。后台会过滤掉因缺少地址信息而被判定为"无效"的订单，不予展示。但这些订单仍可通过 API 查询到。

---

问：为什么订单响应中 line item 的 id 在多次 API 调用之间会变化？

未付款（未完成）订单的 line item id 可能不是持久的。一旦订单成功付款，line item ID 就会稳定下来，并在后续 API 查询中保持不变。

---

问：为什么 create order API 返回 record not found？

当 create order API 返回该错误时，请按以下步骤排查：

• 确认 Product ID、Variant ID 及其他相关参数是否正确。
• 如果所有 ID 都确认无误但请求仍然失败，请检查店铺是否至少配置了一个支付渠道。
• 店铺必须至少启用一种支付方式，否则创建订单会失败并返回 “record not found” 错误。

---

问：通过 Product Image API 创建图片后，为什么图片显示加载中状态？

当图片不是托管在 Shoplazza 原生存储上时，会出现加载中状态。系统会对外部图片发起一个转存流程，期间会显示加载指示。这是临时状态，转存完成后会自动消失。

---

问：如何获取图片资源的 CDN 域名？

获取图片 CDN 域名的方式：

1. 查看 API 响应头中的 IMAGE-DOMAIN header。
2. 如果 IMAGE-DOMAIN header 的值不存在或为空，系统会自动回退到默认域名：img.staticdj.com。

注意：IMAGE-DOMAIN header 提供当前生效的图片资源 CDN 地址。实现时请始终加入回退逻辑，以应对该 header 可能缺失的情况。

---

问：如何只更新某个商品的单个 variant，而不影响同一商品下的其他 variant？

请使用专门的 Update Variant API。重要： 如果使用 "Update Product" API，它会用请求体中提供的 variant 列表替换整个商品的 variant 列表，请求中未包含的现有 variant 都会被删除。为避免这种情况，请使用 variant 专用接口，或确保你的 "Update Product" 请求包含所有需要保留的 variant。

授权

问：API 请求返回 403 错误，提示缺少权限。

问题描述：

由于私有应用权限不足，API 请求返回 403 错误。

原因：

该问题通常是因为店铺设置中没有为私有应用授予所需权限。

解决方案：

1. 检查权限： 确认私有应用已配置必要权限：

   • 进入店铺后台首页。
   • 进入 Manage Private App。
   • 按需更新私有应用的权限设置。

2. 当前限制：

   • 目前私有应用暂不支持 write shop 权限。
   • 该权限将在后续版本中开放。

应用管理

问：如何提升应用评分？

用户界面优化：

• 确保按钮、导航栏和表单易用且功能正常。
• 提供清晰的设置说明和交互功能。
• 为用户操作增加实时反馈。

性能优化（Lighthouse 分数）：

• 关注 FCP、LCP 和 TTI 等指标。
• 优化大文件，使用图片懒加载，并提升服务器响应速度。

应用可用性：

• 确保应用无明显缺陷，并能适配不同设备。

问：如何在店铺中安装未发布应用进行生产测试？

如果要测试尚未发布到应用市场的应用，可以使用以下 URL 格式：

https://{{storeDomain}}/admin/oauth/redirect_from_partner_center?client_id={{app_client_id}}

替换以下参数：

• storeDomain → 你的店铺域名
• app_client_id → 需要测试的应用 Client ID

该链接允许店铺直接安装未发布应用，用于详细业务测试。

---

问：漏洞扫描常见问题

问 1：漏洞扫描通常什么时候开始？

答： 漏洞扫描通常会在系统发生重要变更后，或常规安全审计期间启动。

问 2：单次扫描是否会提供报告和修复建议？

答： 会。每次扫描都会提供详细报告，并针对发现的问题给出建议修复方案。

问 3：如果我认为某些漏洞是误报，应该如何处理？

答： 如果低风险漏洞不影响服务，可以忽略。对于中高风险项目，请提交复核申请并提供相关证据。

问 4：漏洞扫描如何工作，是否需要额外资源？

答： 扫描会使用自动化工具检测已知问题。通常不需要额外资源。

问 5：如何确认漏洞已经修复？

答： 修复后重新运行扫描，确认问题已解决。

问 6：创建或重启扫描任务失败时应该怎么办？

答： 请确认所有必填参数均正确。如果问题仍然存在，请联系支持团队。

问 7：生成扫描报告需要多久？

答： 耗时取决于扫描复杂度。如果长时间未生成报告，请联系支持团队。

---

问：开发者能否在账号下切换店铺？

当前状态：

目前暂不支持该功能。

后续计划：

我们计划在未来版本中支持同一账号下的店铺切换。

账号管理

问：开发者如何删除开发者账号？

当前状态：

目前暂不提供开发者账号删除功能。

解决方案：

如果你需要删除开发者账号，请联系支持团队协助处理。

后续计划：

我们正在评估未来开发开发者账号删除功能的可行性。

---

问：开发者能否在账号下切换店铺？

当前状态：

目前暂不支持该功能。

后续计划：

我们计划在未来版本中支持开发者在同一账号下切换店铺。请关注后续公告。

Webhook

问：Shoplazza 如何处理 Webhook 投递失败？

问题描述：

当 Webhook 投递失败时（即你的 endpoint 返回非 2xx HTTP 状态码），Shoplazza 会在两天内使用指数退避策略多次重试投递。

解决方案：

1. 重试机制： Shoplazza 会在两天内最多尝试投递 Webhook 19 次。
2. Webhook 删除： 如果所有尝试都失败，该 Webhook 会被删除，你需要重新创建。

---

问：收不到 Webhook 事件时应该怎么办？

问题描述：

Webhook 事件可能因 IP 限制或 endpoint 配置错误而无法到达你的服务器。

解决方案：

1. 将 Shoplazza IP 加入白名单： 允许来自 Shoplazza 外部 IP 的请求，例如 34.210.253.121。
2. 检查 endpoint 配置： 确保你的 endpoint 能正确处理 POST 请求。
3. 查看日志： 检查服务器日志，确认是否存在错误或请求被拦截。

---

应用商店

问：商家在同一个账单周期内卸载并重新安装 WhatsApp & Chat Buttons 应用，是否需要再次付费？

当前行为：

需要。应用卸载后，订阅会被终止，重新安装时必须重新发起订阅。

原因：

应用卸载后，订阅关系即结束。因此即使在同一个账单周期内重新安装，也需要创建新的订阅。

建议：

商家应注意在有效账单周期内卸载应用的影响，因为重新安装会触发新的付款。如果对该策略有疑问，请联系支持团队确认。

---

主题扩展

问：如何使用主题扩展自定义主题区块和 POD 功能？

原因：

Shoplazza 提供用于主题自定义和 POD 实现的 CLI 能力。请联系技术团队，我们会提供相关文档和高级定制功能指导。

---

问：为什么 CLI 命令返回 403 错误，应该如何解决？

原因：

当你的应用 Client ID 没有加入 CLI 访问白名单时，会出现 403 错误。请通过技术支持邮箱联系我们，将应用 Client ID 加入白名单。这是使用 CLI 工具前必须完成的安全措施。

---