bagisto-api-shop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build a storefront on the Bagisto Shop API

基于Bagisto Shop API构建店面

Implement any customer-facing storefront — catalog, cart, checkout, account, wishlist, compare — on the Bagisto Shop API (

/api/shop/*

REST +

POST /api/graphql

). This skill is a router: it tells you the flow and points you at the reference page for each feature; the reference pages carry the architecture, UI/UX, endpoints, and a checklist.

基于Bagisto Shop API（

/api/shop/*

REST接口 +

POST /api/graphql

GraphQL接口）实现任意面向客户的店面功能——商品目录、购物车、结账、账户、心愿单、商品对比。本技能是一个路由指引：它会告知你开发流程，并为每个功能指向对应的参考页面；参考页面包含架构、UI/UX、接口端点以及检查清单。

⚠️ Load these FIRST (before any code)

⚠️ 先加载这些内容（编写代码前必须完成）

reference/connecting-to-the-api.md
— auth (storefront key + cart/customer tokens), the
```
{data,meta}
```
/header pagination, error codes, and the verify-before-coding protocol.
reference/graphql.md
— if the client picked GraphQL: the result-field/
```
id
```
rule, camelCase inputs, cursor pagination.

The api-docs are the source of truth for exact request/response shapes —

https://api-docs.bagisto.com

and its

/llms.txt

index. The reference pages name the endpoints and flow; open the linked docs page for the precise body/response before writing the call. Never invent a payload from memory.

reference/connecting-to-the-api.md
—— 认证（店面密钥 + 购物车/客户令牌）、
```
{data,meta}
```
/请求头分页、错误码，以及编码前验证协议。
reference/graphql.md
—— 如果客户选择GraphQL：结果字段/
```
id
```
规则、驼峰式输入、游标分页。

API文档是请求/响应结构的唯一权威依据——访问

https://api-docs.bagisto.com

及其

/llms.txt

索引。参考页面会列出接口端点和流程；在编写接口调用前，请打开对应的文档页面查看精确的请求体/响应结构。切勿凭记忆编造请求负载。

Step 1 — ask the client (CRITICAL, before building)

步骤1 —— 询问客户（至关重要，开始构建前必须完成）

Platform — web, mobile (native/cross-platform), desktop?
Framework/stack — React/Next, Vue/Nuxt, Flutter, React Native, Swift/Kotlin, plain JS?
Transport — REST or GraphQL? (REST for simple screens; GraphQL when a screen needs many related fields at once. Both fully supported.)
First feature/flow — catalog, cart+checkout, account, …?

Confirm, then tailor everything to the answers. Don't assume a stack.

平台 —— Web端、移动端（原生/跨平台）、桌面端？
框架/技术栈 —— React/Next、Vue/Nuxt、Flutter、React Native、Swift/Kotlin、纯JS？
传输协议 —— REST还是GraphQL？（REST适用于简单页面；当页面需要一次性获取多个关联字段时使用GraphQL。两者均完全支持。）
首个功能/流程 —— 商品目录、购物车+结账、账户，……？

确认以上信息后，根据回答调整所有开发内容。切勿假设技术栈。

Step 2 — open the reference for the feature

步骤2 —— 打开对应功能的参考页面

Flows (multi-step journeys / pages)

流程（多步骤流程/页面）

Page	Build this
`reference/flows/product-listing.md`	Categories, product list, search, filters
`reference/flows/product-details.md`	Product page (per-type option discovery, reviews, related)
`reference/flows/add-to-cart.md`	Add-to-cart per product type
`reference/flows/cart.md`	Mini-cart + cart page (read/update/remove/merge/totals)
`reference/flows/checkout.md`	Address → shipping → payment → place order
`reference/flows/order-confirmation.md`	Post-order thank-you page
`reference/flows/authentication.md`	Register, login, logout, verify, forgot/change password
`reference/flows/account.md`	Profile + address book
`reference/flows/customer-orders.md`	Order history, detail, cancel, reorder, invoices, downloadables

页面	构建内容
`reference/flows/product-listing.md`	商品分类、商品列表、搜索、筛选
`reference/flows/product-details.md`	商品详情页（按类型的选项展示、评价、相关商品）
`reference/flows/add-to-cart.md`	按商品类型实现加入购物车功能
`reference/flows/cart.md`	迷你购物车 + 购物车页面（读取/更新/移除/合并/总计）
`reference/flows/checkout.md`	地址填写 → 配送选择 → 支付 → 提交订单
`reference/flows/order-confirmation.md`	订单提交后的感谢页面
`reference/flows/authentication.md`	注册、登录、登出、验证、找回/修改密码
`reference/flows/account.md`	个人资料 + 地址簿
`reference/flows/customer-orders.md`	订单历史、详情、取消、重新下单、发票、可下载商品

Features (single capabilities)

功能（单一能力）

Page	Build this
`reference/features/coupons.md`	Apply / remove coupon
`reference/features/wishlist.md`	Wishlist add/toggle/list/move-to-cart
`reference/features/compare.md`	Compare list
`reference/features/reviews.md`	Product reviews + the customer's own reviews
`reference/features/newsletter.md`	Newsletter subscribe
`reference/features/contact-us.md`	Contact form
`reference/features/storefront-context.md`	Countries/states, channels, currencies, locales, CMS pages, themes

Each page = overview → flow architecture → UI/UX → step-by-step API (with the exact endpoints) → errors → checklist. Follow it; it defers exact shapes to the api-docs.

页面	构建内容
`reference/features/coupons.md`	优惠券的应用 / 移除
`reference/features/wishlist.md`	心愿单的添加/切换/列表/移至购物车
`reference/features/compare.md`	商品对比列表
`reference/features/reviews.md`	商品评价 + 客户自身的评价
`reference/features/newsletter.md`	订阅新闻通讯
`reference/features/contact-us.md`	联系表单
`reference/features/storefront-context.md`	国家/地区、渠道、货币、语言区域、CMS页面、主题

每个页面的结构为概述 → 流程架构 → UI/UX → 分步API指引（含精确接口端点） → 错误处理 → 检查清单。请遵循该结构；具体的请求/响应结构以API文档为准。

Consolidated critical rules (the gotchas that bite)

关键规则汇总（容易踩坑的点）

Verify before coding. PAUSE → open the endpoint's docs page (or query the MCP) → confirm the method/fields → implement → check types. Don't guess endpoint names or bodies.
Auth per surface. Every shop call sends
```
X-STOREFRONT-KEY
```
; cart/account/checkout calls also send
```
Authorization: Bearer <cartToken | customerToken>
```
. Guests mint a cart token first (
```
POST /api/shop/cart-tokens
```
).
Mutating cart/checkout calls return the full updated cart — reconcile your UI from the response, don't mutate locally.
Guest→customer merge on login (
```
merge-carts
```
) or the guest's items are lost.
Post-order cleanup — clear cart state + discard the guest cart token after a placed order, or the cart popup shows stale items.
GraphQL: select the documented result fields of action mutations (
```
success
```
/
```
message
```
/
```
orderId
```
/totals), not a generic
```
id
```
; inputs are camelCase; one field per line. See
```
reference/graphql.md
```
.
Don't hardcode dynamic data (shipping/payment methods, prices, options) — fetch it from the API.

编码前验证。暂停开发 → 打开对应接口的文档页面（或查询MCP） → 确认请求方法/字段 → 实现 → 检查类型。切勿猜测接口名称或请求体。
按场景认证。所有店面接口调用需携带
```
X-STOREFRONT-KEY
```
；购物车/账户/结账接口调用还需携带
```
Authorization: Bearer <cartToken | customerToken>
```
。访客需先生成购物车令牌（
```
POST /api/shop/cart-tokens
```
）。
修改购物车/结账的接口调用会返回完整的更新后购物车——从响应中同步UI状态，切勿在本地修改。
登录时合并访客与客户购物车（
```
merge-carts
```
），否则访客的商品会丢失。
订单提交后清理——订单提交后清除购物车状态并丢弃访客购物车令牌，否则购物车弹窗会显示过期商品。
GraphQL： 选择文档中指定的操作突变结果字段（
```
success
```
/
```
message
```
/
```
orderId
```
/总计），而非通用的
```
id
```
；输入参数采用驼峰式；每行一个字段。详见
```
reference/graphql.md
```
。
不要硬编码动态数据（配送/支付方式、价格、选项）——从API获取这些数据。