商品 API 文档
本文档详细说明驱动 EmpireX 商品卡片、详情页、分类筛选、库存标签以及本地化 VND/USD 规格的公开只读 JSON 字段，不包含任何隐私数据。
通过列表接口拉取在售商品，即可渲染包含缩略图、多语言标题、VND/USD 价格、折扣力度与库存状态的商城卡片。
| 查询参数 | 参数说明 | 示例 |
|---|---|---|
| category_id | 按商城分类 ID 筛选商品 | cat-ai-tools |
| sort | 排序字段：view_count、created_at 或 price | price |
| order | 排序方向：asc（升序）或 desc（降序） | asc |
| page | 页码（从 1 开始计数） | 1 |
| limit | 每页返回条数（商城默认值为 20） | 20 |
| locale | 优先返回的语言区域代码 | zh |
{
"success": true,
"data": {
"items": [
{
"id": "prod_chatgpt_plus",
"slug": "chatgpt-plus-nang-cap-chinh-chu",
"type": "account",
"name_vi": "ChatGPT Plus - Nâng cấp chính chủ",
"name_en": "ChatGPT Plus - Official Upgrade",
"thumbnail": "https://empirex.org/images/chatgpt-plus.webp",
"inventory_status": "in-stock",
"categories": [
{
"category": {
"id": "cat-ai-tools",
"name_vi": "AI Tools",
"name_en": "AI Tools",
"slug": "ai-tools"
}
}
],
"variants": [
{
"id": "var_1m",
"name_vi": "Gói 1 tháng",
"name_en": "1 Month",
"price_vnd": 135000,
"price_usd": 5.5,
"original_price_vnd": 550000,
"original_price_usd": 22,
"stock": true,
"is_default": true,
"sku": "CGPT-PLUS-1M"
}
]
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 120,
"totalPages": 6
}
}
}在打开单个商品详情视图时调用此接口，可加载完整图文介绍、商品图集、质保时长及交付说明。
{
"success": true,
"data": {
"id": "prod_chatgpt_plus",
"slug": "chatgpt-plus-nang-cap-chinh-chu",
"type": "account",
"name_vi": "ChatGPT Plus - Nâng cấp chính chủ",
"name_en": "ChatGPT Plus - Official Upgrade",
"description_vi": "Mô tả chi tiết đang hiển thị ở trang sản phẩm.",
"description_en": "Product detail description shown on the product page.",
"thumbnail": "https://empirex.org/images/chatgpt-plus.webp",
"inventory_status": "in-stock",
"delivery_type_vi": "Giao tài khoản thủ công",
"delivery_type_en": "Manual account delivery",
"vietnam_only": false,
"variant_layout": "default",
"images": [
{
"image_url": "https://empirex.org/images/chatgpt-plus-1.webp",
"locale": "vi",
"order_index": 1
}
],
"categories": [
{
"category": {
"id": "cat-ai-tools",
"name_vi": "AI Tools",
"name_en": "AI Tools",
"slug": "ai-tools"
}
}
],
"variants": [
{
"id": "var_1m",
"name_vi": "Gói 1 tháng",
"name_en": "1 Month",
"sku": "CGPT-PLUS-1M",
"price_vnd": 135000,
"price_usd": 5.5,
"original_price_vnd": 550000,
"original_price_usd": 22,
"stock": true,
"is_default": true,
"warranty_duration": 1,
"warranty_unit": "month",
"image": "https://empirex.org/images/chatgpt-plus-variant.webp",
"images": []
}
]
}
}id商品唯一标识符，用于详情查询、购物车及结账下单。
slugURL 友好的商品别名路径，例如 /en/accounts/chatgpt-plus。
type目录路由类型：account（账号）或 service（技术服务）。
name_vi / name_en多语言本地化商品标题。
thumbnail目录列表页展示的商品主缩略图。
inventory_status在商品卡片与详情页展示的顶层库存状态标识。
categories商品所属分类列表，用于前端筛选与聚合展示。
variants订阅套餐规格列表，含 VND 与 USD 售价、原价、SKU 编码及独立库存。
description_vi / description_en在详情页渲染的多语言富文本商品介绍。
images详情页按顺序排列的商品展示图集。
delivery_type_vi / delivery_type_en在商品亮点区展示的多语言交付方式说明。
warranty_duration / warranty_unit各规格对应的质保周期数值与时间单位。
vietnam_only为 true 时表示该商品仅限越南地区激活或使用。
variant_layout规格选择器界面布局模式：default、matrix_2d 或 matrix_3d。
in-stock现货充足，可直接加入购物车并结账购买。
low-stock剩余库存较少，前端显示“库存紧张”提示标签。
out-of-stock暂时缺货，购买按钮处于禁用状态。
price = 0定制询价商品（“联系询价”），隐藏标准购买按钮。