{ "openapi": "3.0.3", "info": { "title": "Sellsuite Storefront API", "version": "1.0.0", "description": "API công khai cho headless storefront — mọi frontend (web/app/agent) đều dựng được trải nghiệm mua hàng đầy đủ. CORS mở (*), giỏ hàng phía client, giá/tồn tính lại server-side ở checkout-preview/checkout. Đơn vị tiền: số nguyên theo currency của gian hàng." }, "servers": [ { "url": "https://sellsuite-worker.phamgiagia.workers.dev" } ], "components": { "securitySchemes": { "customerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT khách — lấy từ /customer/login, /customer/signup hoặc /customer/otp/verify" } }, "schemas": { "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "integer" }, "compare_at_price": { "type": "integer", "nullable": true }, "stock_qty": { "type": "integer" }, "allow_backorder": { "type": "integer" }, "image_r2_keys": { "type": "string", "description": "JSON array key ảnh — dựng URL: {origin}/platform/files/serve/{key}" }, "is_digital": { "type": "integer" }, "is_kit": { "type": "integer" }, "is_rental": { "type": "integer", "description": "1 = cho thuê theo ngày, price là đơn giá/ngày" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" } } }, "CheckoutItem": { "type": "object", "properties": { "productId": { "type": "string" }, "qty": { "type": "integer" }, "variantId": { "type": "string" }, "addonOptionIds": { "type": "array", "items": { "type": "string" } }, "giftMessage": { "type": "string", "description": "Lời chúc quà tặng theo dòng (≤1000 ký tự)" }, "rentalStart": { "type": "string", "description": "YYYY-MM-DD — bắt buộc với sản phẩm is_rental" }, "rentalEnd": { "type": "string" } }, "required": [ "productId", "qty" ] } } }, "paths": { "/api/site/{slug}": { "get": { "summary": "Thông tin gian hàng (tiền tệ, phương thức thanh toán, vùng, cờ tính năng)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" }, { "name": "region", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "currency": { "type": "string" }, "country": { "type": "string" }, "available_payment_methods": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } } } }, "otp_login": { "type": "boolean" }, "recipe_marketplace": { "type": "boolean" }, "recipe_subscriptions": { "type": "boolean" } } } } } } } } } } }, "/api/site/{slug}/products": { "get": { "summary": "Danh sách sản phẩm (lọc/sắp xếp/phân trang)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "option1", "in": "query", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "schema": { "type": "string" } }, { "name": "region", "in": "query", "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "schema": { "type": "integer" } }, { "name": "max_price", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "in_stock", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } } } } } } }, "/api/site/{slug}/products/{id}": { "get": { "summary": "Chi tiết sản phẩm (biến thể + nhóm tuỳ chọn cộng giá)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "schema": { "type": "string" } }, { "name": "region", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {} } } } } } }, "404": { "description": "Không tồn tại" } } } }, "/api/site/{slug}/categories": { "get": { "summary": "Danh mục (kèm ảnh đại diện nếu có)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": "string", "nullable": true }, "image_r2_key": { "type": "string", "nullable": true } } } } } } } } } } } } } }, "/api/site/{slug}/checkout-preview": { "post": { "summary": "Tính thử giỏ (giá vùng/khuyến mãi/phí ship) — KHÔNG side-effect", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutItem" } }, "couponCode": { "type": "string" }, "giftCardCode": { "type": "string" }, "customerEmail": { "type": "string" }, "country": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "discount": { "type": "integer" }, "shippingFee": { "type": "integer" }, "total": { "type": "integer" }, "currency": { "type": "string" }, "allDigital": { "type": "boolean" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "unitPrice": { "type": "integer" }, "lineTotal": { "type": "integer" } } } } } } } } } } } } } }, "/api/site/{slug}/checkout": { "post": { "summary": "Đặt hàng thật (khách vãng lai hoặc kèm JWT khách)", "description": "Gửi clientRef (UUID tự sinh) để idempotent khi retry. paymentMethod lấy từ available_payment_methods. savedPaymentMethodId (kèm JWT) trừ thẻ đã lưu ngay.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutItem" } }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "customerEmail": { "type": "string" }, "shippingAddress": { "type": "string" }, "province": { "type": "string" }, "paymentMethod": { "type": "string" }, "couponCode": { "type": "string" }, "note": { "type": "string" }, "clientRef": { "type": "string" }, "country": { "type": "string" }, "savedPaymentMethodId": { "type": "string" } }, "required": [ "items", "customerName", "customerPhone", "paymentMethod" ] } } } }, "responses": { "201": { "description": "Đã tạo đơn", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "orderId": { "type": "string" }, "code": { "type": "string" }, "total": { "type": "integer" }, "payUrl": { "type": "string", "nullable": true }, "qrImageUrl": { "type": "string", "nullable": true }, "gatewayError": { "type": "string", "nullable": true }, "paidWithSavedCard": { "type": "boolean" } } } } } } } }, "400": { "description": "Dữ liệu/tồn kho/khuyến mãi không hợp lệ — message tiếng Việt rõ ràng" } } } }, "/api/orders/{orderId}": { "get": { "summary": "Tra cứu đơn công khai (trang xác nhận)", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "qty": { "type": "integer" }, "line_total": { "type": "integer" }, "gift_message": { "type": "string", "nullable": true }, "custom_note": { "type": "string", "nullable": true }, "rental_start": { "type": "string", "nullable": true } } } } } } } } } } } } } }, "/api/site/{slug}/pages/{pageSlug}": { "get": { "summary": "Trang CMS tuỳ chỉnh", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" }, { "name": "pageSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {} } } } } } } } } }, "/api/site/{slug}/blog": { "get": { "summary": "Danh sách bài blog đã đăng", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": {} } } } } } } } } } } } }, "/api/site/{slug}/newsletter": { "post": { "summary": "Đăng ký nhận tin", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "subscribed": { "type": "boolean" } } } } } } } } } } }, "/api/site/{slug}/feed.xml": { "get": { "summary": "Catalog feed Google Merchant/Meta (RSS 2.0 XML)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "responses": { "200": { "description": "application/xml" } } } }, "/api/site/{slug}/sitemap.xml": { "get": { "summary": "Sitemap per-store", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "responses": { "200": { "description": "application/xml" } } } }, "/api/site/{slug}/llms.txt": { "get": { "summary": "Hướng dẫn cho AI agent (text)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "responses": { "200": { "description": "text/plain" } } } }, "/api/site/{slug}/agent-commerce.json": { "get": { "summary": "Manifest máy-đọc cho AI agent", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "responses": { "200": { "description": "application/json" } } } }, "/api/site/{slug}/customer/signup": { "post": { "summary": "Khách tạo tài khoản (email + mật khẩu)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" } } } } } } } } } } }, "/api/site/{slug}/customer/login": { "post": { "summary": "Khách đăng nhập (email)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" } } } } } } } } } } }, "/api/site/{slug}/customer/otp/request": { "post": { "summary": "Gửi mã OTP đăng nhập SĐT (khi gian hàng bật otp_login)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "boolean" } } } } } } } } } } }, "/api/site/{slug}/customer/otp/verify": { "post": { "summary": "Xác minh OTP → JWT khách", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug gian hàng (VD: demo-combo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "code": { "type": "string" } }, "required": [ "phone", "code" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" } } } } } } } } } } }, "/api/customer/me": { "get": { "summary": "Hồ sơ khách hiện tại", "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } } } } } } } } } }, "/api/customer/orders": { "get": { "summary": "Lịch sử đơn của khách", "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": {} } } } } } } } } } } } }, "/api/customer/wishlist": { "get": { "summary": "Sản phẩm yêu thích", "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": {} } } } } } } } } } } } }, "/api/customer/payment-methods": { "get": { "summary": "Thẻ đã lưu (brand + 4 số cuối — không bao giờ trả pm id thô)", "security": [ { "customerToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" } } } } } } } } } } } } } } } }