{"openapi": "3.1.0", "info": {"title": "Clonetraucho API", "version": "1.0.0", "description": "API đại lý để đọc sản phẩm, số dư và quản lý đơn hàng."}, "servers": [{"url": "https://www.traubommo.com", "description": "Máy chủ hiện tại"}], "tags": [{"name": "Catalog", "description": "Danh mục và sản phẩm đang bán."}, {"name": "Tài khoản", "description": "Số dư và chính sách giá của API key."}, {"name": "Đơn hàng", "description": "Tạo đơn và đọc lại dữ liệu đơn đã mua."}], "paths": {"/api/v1/categories": {"get": {"tags": ["Catalog"], "summary": "Liệt kê danh mục đang bật", "description": "Endpoint công khai, trả về các danh mục sản phẩm đang hoạt động.", "operationId": "list_categories", "security": [], "responses": {"200": {"description": "Danh sách danh mục", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CategoryList"}, "example": {"data": [{"id": 1, "name": "TẤT CẢ SẢN PHẨM", "slug": "all"}]}}}}}}}, "/api/v1/products": {"get": {"tags": ["Catalog"], "summary": "Liệt kê sản phẩm và tồn kho", "description": "Endpoint công khai. Gửi API key để nhận giá sau chiết khấu riêng theo từng sản phẩm; không gửi key sẽ nhận giá niêm yết.", "operationId": "list_products", "security": [{}, {"XApiKey": []}, {"BearerAuth": []}], "responses": {"200": {"description": "Danh sách sản phẩm", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProductList"}, "example": {"data": [{"id": 10, "name": "Tiktok Japan", "description": "Login bằng username và pass", "format_text": "username|password|2fa", "country_code": "jp", "base_price": 2999, "discount_percent": 10, "price": 2700, "stock": 50, "category": "CLONE TIKTOK"}]}}}}}}}, "/api/v1/balance": {"get": {"tags": ["Tài khoản"], "summary": "Đọc số dư và chính sách giá", "description": "Yêu cầu API key có quyền balance:read.", "operationId": "get_balance", "security": [{"XApiKey": []}, {"BearerAuth": []}], "responses": {"200": {"description": "Thông tin số dư", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Balance"}, "example": {"data": {"username": "daily_agent", "balance": 100000, "pricing_mode": "per_product", "discounted_product_count": 2}}}}}, "401": {"description": "API key không hợp lệ", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "API key thiếu quyền balance:read", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "x-required-scope": "balance:read"}}, "/api/v1/orders": {"post": {"tags": ["Đơn hàng"], "summary": "Tạo đơn mua tài khoản", "description": "Tạo đơn mua thật và trừ tiền trong ví. Idempotency-Key là bắt buộc để retry an toàn mà không tạo đơn trùng.", "operationId": "create_order", "security": [{"XApiKey": []}, {"BearerAuth": []}], "responses": {"200": {"description": "Đơn đã tồn tại hoặc hoàn tất", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}, "example": {"data": {"order_id": 123, "status": "completed", "total": 2999, "delivery": "username|password|2fa"}}}}}, "201": {"description": "Tạo đơn thành công", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}, "example": {"data": {"order_id": 123, "status": "completed", "total": 2999, "delivery": "username|password|2fa"}}}}}, "401": {"description": "API key không hợp lệ", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Số dư không đủ", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Hết hàng hoặc Idempotency-Key xung đột", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Nguồn API từ chối đơn", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "x-required-scope": "orders:write", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "description": "Mã duy nhất cho một yêu cầu mua.", "schema": {"type": "string", "minLength": 8, "maxLength": 200}, "example": "order-20260731-001"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["product_id", "quantity"], "properties": {"product_id": {"type": "integer", "minimum": 1}, "quantity": {"type": "integer", "minimum": 1, "maximum": 1000}}}, "example": {"product_id": 10, "quantity": 1}}}}}, "get": {"tags": ["Đơn hàng"], "summary": "Liệt kê đơn hàng", "description": "Trả về tối đa 100 đơn còn trong thời hạn lưu dữ liệu.", "operationId": "list_orders", "security": [{"XApiKey": []}, {"BearerAuth": []}], "responses": {"200": {"description": "Danh sách đơn hàng", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OrderList"}, "example": {"data": [{"order_id": 123, "status": "completed", "quantity": 1, "total": 2999, "product_name": "Tiktok Japan"}]}}}}, "401": {"description": "API key không hợp lệ", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "API key thiếu quyền orders:read", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "x-required-scope": "orders:read"}}, "/api/v1/orders/{id}": {"get": {"tags": ["Đơn hàng"], "summary": "Đọc chi tiết một đơn", "description": "Chỉ trả về đơn thuộc tài khoản sở hữu API key.", "operationId": "get_order", "security": [{"XApiKey": []}, {"BearerAuth": []}], "responses": {"200": {"description": "Chi tiết đơn hàng", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}, "example": {"data": {"order_id": 123, "status": "completed", "quantity": 1, "total": 2999, "delivery": "username|password|2fa"}}}}}, "401": {"description": "API key không hợp lệ", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "API key thiếu quyền orders:read", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy đơn", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "x-required-scope": "orders:read", "parameters": [{"name": "id", "in": "path", "required": true, "description": "ID đơn hàng cần đọc.", "schema": {"type": "integer", "minimum": 1}, "example": 123}]}}}, "components": {"securitySchemes": {"XApiKey": {"type": "apiKey", "in": "header", "name": "X-API-Key"}, "BearerAuth": {"type": "http", "scheme": "bearer"}}, "schemas": {"Category": {"type": "object", "required": ["id", "name", "slug"], "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "slug": {"type": "string"}}}, "Product": {"type": "object", "required": ["id", "name", "price", "stock", "category"], "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "description": {"type": "string"}, "format_text": {"type": "string"}, "country_code": {"type": "string"}, "base_price": {"type": "integer"}, "discount_percent": {"type": "integer"}, "price": {"type": "integer"}, "stock": {"type": "integer"}, "category": {"type": "string"}}}, "BalanceData": {"type": "object", "properties": {"username": {"type": "string"}, "balance": {"type": "integer"}, "pricing_mode": {"type": "string"}, "discounted_product_count": {"type": "integer"}}}, "OrderData": {"type": "object", "properties": {"order_id": {"type": "integer"}, "status": {"type": "string"}, "quantity": {"type": "integer"}, "total": {"type": "integer"}, "product_name": {"type": "string"}, "delivery": {"type": "string"}}}, "CategoryList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Category"}}}}, "ProductList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Product"}}}}, "Balance": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/BalanceData"}}}, "Order": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/OrderData"}}}, "OrderList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/OrderData"}}}}, "Error": {"type": "object", "required": ["error", "message"], "properties": {"error": {"type": "string"}, "message": {"type": "string"}}}}}}