询价会进入 Shopify 后台的 Sectionly B2B 应用 → Inquiries。草稿订单随后异步创建,并显示在 Shopify 订单 → 草稿订单;创建失败时,询价仍保留,商家可在详情中查看错误并重试。
一 开始前准备
- Shopify 店铺已安装正式版 Sectionly B2B Wholesale,商家能够正常打开应用。
- 在 Quote Settings 配置 B2B 商品或模板规则、最低起订量 MOQ,以及必填表单字段。
- 准备自建店面正式域名和真实商品及变体 ID;变体必须属于该店铺的对应商品。
二 从后台创建公钥
进入 Shopify 后台 → 应用 → Sectionly B2B Wholesale → Headless。在 Create API key 表单创建店面密钥。
图 1 B2B Headless 公钥创建表单
- Key name:输入用途名称,例如 Headless Browser Production。
- Key type:选择 Public — browser storefront。
- Allowed origins:每行填写一个真实店面 Origin,例如
https://shop.example.com。需要 www 子域时再另起一行填写。 - Expires in days:填写 1 到 365 天。建议测试时使用 1 天;正式密钥按团队轮换周期设置,并记录到期时间。
- Permissions:Read form settings 对应 config:read,Read B2B product rules 对应 products:read,Submit inquiries 对应 inquiries:write。完整询价组件需要三项权限;只读展示无需勾选 Submit inquiries。
- 点击 Create key,立即复制完整的 sb2b_pk_ 公钥。密钥完整值只显示一次,之后列表只显示前缀。
https://shop.example.com 和 https://www.shop.example.com 是两个 Origin。本地可使用 http://localhost:端口 或 http://127.0.0.1:端口,正式环境使用 HTTPS。
三 创建服务端私钥
如果使用服务端 SSR 或后端代提交,再新建一把密钥,将 Key type 改为 Private — server only。填写用途名称、有效期和所需权限;私钥不需要浏览器允许域名。
图 2 将类型改为 Private 后创建服务端密钥
四 选用一种接入方式
API 基础地址为
https://b2b.sectionly.ai/api/storefront/v1。B2B 密钥与 Reviews 密钥独立,前缀和请求头不同,不能混用。
五 嵌入现成 JS 询价表单
把以下内容放到商品页。替换公钥、店铺域名,以及商品和变体数据;它们应从你的店面数据源读取,而不是在所有商品页复用同一个 ID。调整样式
在 embed.css 加载后引入你自己的样式,并将覆盖规则限定在 .sectionly-b2b-form 容器。需要完全改造字段布局、按钮或交互时,选择 API 自定义界面最灵活。有严格 CSP 时,允许从应用域名加载脚本、样式和发起请求,配置脚本使用站点自己的 nonce。六 API 配合自己的界面和样式
下面三个浏览器示例应按顺序放在同一个前端 ES 模块文件,或同一个<script type="module"> 中:生成访客标识、读取配置与商品规则、定义提交函数。把 submitInquiry 绑定到你自己的表单事件,并给页面添加加载、成功和错误状态。
为访客生成稳定标识
浏览器请求需要 X-Sectionly-Visitor。为当前访客生成随机的 16 到 80 字符标识,不要把所有用户写成同一个值。以下示例在当前标签页内保留标识;存储被禁用时回退为当前页面内的随机标识。先读取表单配置和商品规则
提交询价并支持安全重试
下面示例中的 18 仅为数量示例。实际必须达到你的商家 MOQ,customFields 必须包含 /form-config 返回的全部必填字段;例如商家还要求 Estimated Quantity 时,提交中也应包含它。七 服务端接入和 SSR
服务端可以先读取 /form-config 和 /b2b-products,直接渲染首屏表单,再通过你自己的后端提交。Hydrogen 和 Next.js 可以调用下面的通用辅助函数;密钥从各自服务端环境读取,不返回给浏览器。八 在后台验收一次完整询价
- 打开真实商品页,检查 B2B 展示规则和表单必填项。先测试低于 MOQ 的数量,应有清楚提示。
- 使用可收信的测试邮箱,填写带明显测试标记的姓名和公司,按实际 MOQ 选择数量并提交一次。
- 到应用 Inquiries 查看同一条询价的商品、变体和数量,核对 Shopify 草稿订单是否创建;失败时查看错误后使用后台重试。
- 确认买家收到或邮件服务已接受确认回执,核对商家通知配置。邮件服务接受不等于保证进入每个收件箱。
- 首页 Needs attention 应只显示一次该询价。打开详情后返回首页,未报价时仍应显示 Awaiting quote。
- 在桌面和手机检查长商品名、长公司名、SKU 弹窗、选择数量、清空及重复点击;测试完成后按团队要求保留样例或清理。
九 错误和限流排查
当前额度:每位访客读 120 次每分钟、写 20 次每小时;公钥还按 IP 限制读 600 次每分钟、写 100 次每小时。私钥 SSR 不按一个共用服务端 IP 计整站总量,但仍必须正确区分访客。禁止使用一个固定访客 ID 代表所有人。
十 密钥轮换和正式上线
- 在旧密钥到期前创建新密钥,保持相同的必要权限与真实允许域名。
- 更新浏览器或服务端配置并部署,验证读取配置和询价提交成功。
- 回 Headless 的 API keys 列表,对旧密钥点击 Revoke;在确认对话框中核对名称,再点击 Revoke key。确认状态变为 Revoked。
- 应用卸载后密钥会被撤销,重装后需要重新创建并更新店面配置。