bagisto-api-admin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build an admin app on the Bagisto Admin API

基于Bagisto Admin API构建管理应用

Implement any admin/back-office interface on the Bagisto Admin API (

/api/admin/*

REST +

POST /api/admin/graphql

). The API mirrors the Bagisto admin panel menu-for-menu, so any admin screen can be rebuilt from it. This skill is a router: it gives the flow and points you at the per-menu reference page; the reference pages carry the endpoints, UI/UX, and checklists.

在Bagisto Admin API（

/api/admin/*

REST +

POST /api/admin/graphql

）上实现任意管理/后台界面。该API与Bagisto管理面板的菜单完全对应，因此任何管理界面都可以通过它重新构建。此技能是一个路由工具：它提供流程指引，并指向对应菜单的参考页面；参考页面包含端点、UI/UX和检查清单。

⚠️ Load these FIRST (before any code)

⚠️ 请先加载这些内容（编写代码前）

reference/connecting-to-the-api.md
— admin auth (the Integration Bearer token), the
```
{data,meta}
```
listing envelope, the list→detail→action pattern, permissions, errors, and the verify-before-coding protocol.
reference/graphql.md
— if the client picked GraphQL: the admin endpoint, the result-field/
```
id
```
rule, camelCase inputs + filter args, cursor pagination.

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

https://api-docs.bagisto.com

(Admin API section) + 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
—— 管理端认证（Integration Bearer令牌）、
```
{data,meta}
```
列表包、列表→详情→操作模式、权限、错误处理，以及编码前的验证协议。
reference/graphql.md
—— 如果客户选择GraphQL：管理端端点、结果字段/
```
id
```
规则、驼峰式输入+过滤参数、游标分页。

API文档是精确数据结构的唯一依据 —— 访问

https://api-docs.bagisto.com

（Admin API板块）及其

/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, plain JS?
Which admin menus — Sales, Catalog, Customers, Marketing, CMS, Settings, Configuration, Dashboard/Reporting — or one first?
Transport — REST or GraphQL? (REST for list/detail/action screens; GraphQL when a screen needs many related fields in one round-trip. Both fully supported.)
First screen/flow — order list + actions, product management, Create-Order, a dashboard, …?

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

平台 —— Web、移动端（原生/跨平台）、桌面端？
框架/技术栈 —— React/Next、Vue/Nuxt、Flutter、React Native、纯JS？
涉及哪些管理菜单 —— 销售、商品目录、客户、营销、CMS、设置、配置、仪表板/报表 —— 还是先做其中一个？
传输方式 —— REST还是GraphQL？（REST适用于列表/详情/操作界面；当界面需要一次请求获取多个关联字段时使用GraphQL。两者均完全支持。）
首个界面/流程 —— 订单列表+操作、商品管理、创建订单、仪表板……？

确认以上信息后，根据答案定制所有内容。请勿假设技术栈。

The core admin pattern: list → detail → action

核心管理模式：列表 → 详情 → 操作

Almost every admin screen is the same shape (detailed in

connecting-to-the-api.md

List —
```
GET /api/admin/<resource>
```
→
```
{ data, meta }
```
envelope; drive tables with
```
?page=
```
+
```
?per_page=
```
+ the screen's filters.
Detail —
```
GET /api/admin/<resource>/{id}
```
→ full record, relations embedded (no follow-up calls).
Action —
```
POST/PUT/DELETE
```
for create/update/delete + per-record actions (cancel order, create invoice, mass-update, …), each with its own eligibility rules.

几乎所有管理界面都遵循相同的结构（

connecting-to-the-api.md

中有详细说明）：

列表 ——
```
GET /api/admin/<resource>
```
→ 返回
```
{ data, meta }
```
包；通过
```
?page=
```
+
```
?per_page=
```
+ 界面专属过滤器来驱动表格展示。
详情 ——
```
GET /api/admin/<resource>/{id}
```
→ 返回完整记录，包含嵌入的关联数据（无需后续调用）。
操作 —— 使用
```
POST/PUT/DELETE
```
进行创建/更新/删除操作，以及每条记录的专属操作（取消订单、创建发票、批量更新等），每个操作都有自己的适用规则。

Step 2 — open the reference for the menu

步骤2 —— 打开对应菜单的参考文档

Flagship flow

核心流程

Page	Build this
`reference/flows/create-order.md`	The admin Create-Order flow (place an order for a customer via a draft cart)

页面	构建内容
`reference/flows/create-order.md`	管理端创建订单流程（通过草稿购物车为客户下单）

Menus (mirror the admin sidebar)

菜单（与管理侧边栏完全对应）

Page	Covers
`reference/menus/sales.md`	Orders (list/detail + cancel/comment/invoice/shipment/refund), Invoices, Shipments, Refunds, Transactions, Bookings, CSV exports
`reference/menus/catalog.md`	Products (datagrid + CRUD + images/inventory/customer-group-prices + mass actions), Categories (+tree), Attributes (+options), Attribute Families
`reference/menus/customers.md`	Customers (CRUD + addresses/notes/impersonate), Groups, Reviews, GDPR
`reference/menus/marketing.md`	Cart Rules (+coupons), Catalog Rules, Email Templates, Events, Campaigns, Subscribers, Search Terms/Synonyms, URL Rewrites, Sitemaps
`reference/menus/cms.md`	CMS Pages
`reference/menus/settings.md`	Currencies, Channels, Locales, Exchange Rates, Inventory Sources, Tax Rates/Categories, Roles, Users, Themes, Data-Transfer Imports
`reference/menus/configuration.md`	Store configuration (schema / values / update)
`reference/menus/dashboard-reporting.md`	Dashboard stats + Reporting (sales/customers/products + export)

页面	涵盖内容
`reference/menus/sales.md`	订单（列表/详情 + 取消/备注/开票/发货/退款）、发票、发货单、退款单、交易记录、预订、CSV导出
`reference/menus/catalog.md`	商品（数据网格 + CRUD + 图片/库存/客户组价格 + 批量操作）、分类（树形结构）、属性（含选项）、属性组
`reference/menus/customers.md`	客户（CRUD + 地址/备注/模拟登录）、客户组、评论、GDPR合规
`reference/menus/marketing.md`	购物车规则（含优惠券）、商品目录规则、邮件模板、活动、营销活动、订阅者、搜索词/同义词、URL重写、站点地图
`reference/menus/cms.md`	CMS页面
`reference/menus/settings.md`	货币、渠道、区域设置、汇率、库存来源、税率/税分类、角色、用户、主题、数据传输导入
`reference/menus/configuration.md`	店铺配置（Schema / 配置值 / 更新）
`reference/menus/dashboard-reporting.md`	仪表板统计 + 报表（销售/客户/商品 + 导出）

Discovery — don't hardcode the nav or permissions

发现环节 —— 不要硬编码导航或权限

Two read-only endpoints (REST + GraphQL) tell you what the current token can do — drive navigation and action-gating from them instead of hardcoding:

```
GET /api/admin/menu
```
(
```
getAdminMenu
```
) — the admin sidebar as a permission-filtered tree; each node maps to its API endpoint (
```
apiResource: { rest, graphql }
```
, or
```
null
```
for group headers / panel-only screens).

GET /api/admin/permissions

(

getAdminPermissions

) — the token's effective

{ permissionType, permissions }

(

["*"]

= full access).

Details in

reference/connecting-to-the-api.md

有两个只读端点（REST + GraphQL）可以告诉你当前令牌的权限范围——请根据这些端点的返回结果来驱动导航和操作权限控制，而非硬编码：

```
GET /api/admin/menu
```
（
```
getAdminMenu
```
）—— 返回经过权限过滤的树形管理侧边栏；每个节点都映射到对应的API端点（
```
apiResource: { rest, graphql }
```
，对于分组标题/仅面板界面则为
```
null
```
）。

GET /api/admin/permissions

（

getAdminPermissions

）—— 返回令牌的有效权限

{ permissionType, permissions }

（

["*"]

表示完全访问）。

详细内容见

reference/connecting-to-the-api.md

。

Consolidated critical rules

关键规则汇总

Verify before coding. PAUSE → open the endpoint's docs page (or query the MCP) → confirm method/fields → implement → check types.
Auth: every call sends
```
Authorization: Bearer <id>|<token>
```
(a pre-issued admin Integration token). There's no login endpoint — the token is made in the store's admin panel. The admin GraphQL endpoint is
```
POST /api/admin/graphql
```
(admin token only; not the shop endpoint, no storefront key).
Permissions: a token is capped by its admin's role — an endpoint the role can't reach returns 403. Build for that.
Listings are
{ data, meta }
(+
```
X-Total-*
```
headers); page with
```
?page=
```
/
```
?per_page=
```
(default 10, cap 50) + the per-screen filters.
GraphQL action mutations (cancel/invoice/shipment/refund/place-order/cart writes/mass-actions) return result fields, not a generic
```
id
```
; inputs are camelCase; custom filter args are documented per page. See
```
reference/graphql.md
```
.
Don't hardcode dynamic data (shipping/payment methods in Create-Order, config options) — fetch it.

编码前验证：暂停→打开端点的文档页面（或查询MCP）→确认请求方法/字段→实现→检查类型。
认证：每次调用都需携带
```
Authorization: Bearer <id>|<token>
```
（预先颁发的管理端Integration令牌）。没有登录端点——令牌需在店铺管理面板中生成。管理端GraphQL端点为
```
POST /api/admin/graphql
```
（仅支持管理端令牌；不是店铺前端端点，无需店铺密钥）。
权限：令牌的权限受所属管理员角色限制——角色无权访问的端点会返回403。请针对这种情况进行开发。
列表返回
{ data, meta }
（+
```
X-Total-*
```
响应头）；使用
```
?page=
```
/
```
?per_page=
```
进行分页（默认10条，上限50条）+ 界面专属过滤器。
GraphQL操作突变（取消/开票/发货/退款/下单/购物车写入/批量操作）返回结果字段，而非通用
```
id
```
；输入参数为驼峰式；自定义过滤参数在对应页面中有文档说明。详见
```
reference/graphql.md
```
。
不要硬编码动态数据（创建订单中的配送/支付方式、配置选项）——请通过API获取。