常见问题

FAQ 分类

API 调用 了解如何正确调用 Shoplazza API。 授权 了解如何配置 OAuth 和私有应用 token。 应用管理 管理和配置 Shoplazza 生态中的应用。 账号管理 了解用户账号和权限管理指南。 Webhook 设置并配置用于实时通知的 Webhook。 开发者工具使用 了解应用开发和测试相关工具。 数据安全 了解保护商家和顾客数据的安全措施。 应用商店 通过 Shoplazza 应用商店中的应用增强店铺功能。

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 状态正常时，如何获取正确响应？

问题描述：

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

解决方案：

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

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

授权

问：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 应用，是否需要再次付费？

当前行为：

需要。因为卸载应用后，订阅关系会结束。

建议：

请注意在有效账单周期内卸载应用的影响。如果对该策略有疑问，请联系支持团队。

应用商店

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

当前行为：

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

原因：

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

建议：

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

---

主题扩展

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

原因：

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

---

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

原因：

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

---