{ "openapi": "3.1.0", "info": { "title": "PORO Platform API", "version": "2026-09-01", "description": "API mô tả năng lực, không mô tả hạ tầng. Mọi lệnh ghi cần Idempotency-Key. Mỗi khoá API thuộc đúng một tổ chức.", "contact": { "name": "PORO Platform", "email": "creator@poroai.life" } }, "servers": [ { "url": "https://creator.poroai.life/api/public/v1", "description": "Production" }, { "url": "https://project--942e7d1e-74ea-40bc-9e38-98bb41326feb-dev.lovable.app/api/public/v1", "description": "Preview" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Poro-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } }, "InventoryPool": { "type": "object", "properties": { "object": { "type": "string", "const": "inventory_pool" }, "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "store_id": { "type": "string", "nullable": true }, "price": { "type": "number" }, "available": { "type": "integer" }, "reserved": { "type": "integer" }, "sellable": { "type": "integer" } } }, "Reservation": { "type": "object", "properties": { "object": { "type": "string", "const": "reservation" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "held", "released", "committed", "expired" ] }, "quantity": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Order": { "type": "object", "properties": { "object": { "type": "string", "const": "order" }, "id": { "type": "string", "nullable": true }, "reference": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number", "nullable": true }, "currency": { "type": "string" } } }, "Event": { "type": "object", "properties": { "object": { "type": "string", "const": "event" }, "id": { "type": "string" }, "type": { "type": "string", "enum": [ "inventory.updated", "inventory.reserved", "inventory.released", "inventory.committed", "order.created", "order.paid", "order.cancelled", "order.fulfilled", "catalog.updated", "catalog.sync.completed", "catalog.sync.failed", "stream.created", "stream.started", "stream.ended", "stream.failed", "ai.job.created", "ai.job.completed", "ai.job.failed", "booking.confirmed", "booking.cancelled", "session.completed", "payout.requested", "payout.paid" ] }, "api_version": { "type": "string" }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_endpoint" }, "id": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "List": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } }, "paths": { "/ros/resources": { "get": { "summary": "Danh sách tài nguyên (creator / studio / operator / brand)", "operationId": "listResources", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "creator", "studio", "operator", "brand" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "cluster", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Danh sách", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } }, "post": { "summary": "Đăng ký tài nguyên vào Registry", "operationId": "createResource", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "display_name" ], "properties": { "type": { "type": "string", "enum": [ "creator", "studio", "operator", "brand" ] }, "display_name": { "type": "string" }, "cluster": { "type": "string" }, "province": { "type": "string" }, "district": { "type": "string" }, "rate_per_hour": { "type": "number" }, "level": { "type": "integer" }, "skills": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Đã tạo" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/resources/verify": { "post": { "summary": "Duyệt hoặc từ chối xác minh tài nguyên", "operationId": "verifyResource", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resource_id", "approve" ], "properties": { "resource_id": { "type": "string" }, "approve": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Đã cập nhật" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/resources/suspend": { "post": { "summary": "Tạm ngưng tài nguyên", "operationId": "suspendResource", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resource_id" ], "properties": { "resource_id": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đã tạm ngưng" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/availability": { "post": { "summary": "Khai báo khung giờ rảnh / bị chặn", "operationId": "addAvailability", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resource_id", "starts_at", "ends_at" ], "properties": { "resource_id": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "available", "blocked" ] }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "Đã ghi nhận" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/campaigns": { "get": { "summary": "Danh sách chiến dịch nhu cầu", "operationId": "listCampaigns", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Danh sách", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } }, "post": { "summary": "Tạo chiến dịch nhu cầu", "operationId": "createCampaign", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "resource_type": { "type": "string" }, "cluster": { "type": "string" }, "budget": { "type": "number" }, "session_count": { "type": "integer" }, "duration_minutes": { "type": "integer" }, "sku_ids": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Đã tạo" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/campaigns/match": { "post": { "summary": "Chấm điểm và lập danh sách tài nguyên phù hợp", "operationId": "matchCampaign", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "campaign_id" ], "properties": { "campaign_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Danh sách đề xuất kèm breakdown điểm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/bookings": { "get": { "summary": "Danh sách lịch đặt", "operationId": "listBookings", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Danh sách", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } }, "post": { "summary": "Giữ chỗ tài nguyên (soft hold, chống trùng khung giờ)", "operationId": "holdBooking", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "campaign_id", "resource_id", "starts_at", "ends_at" ], "properties": { "campaign_id": { "type": "string" }, "resource_id": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Đã giữ chỗ" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "409": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/bookings/confirm": { "post": { "summary": "Chốt lịch và tạo phiên điều phối", "operationId": "confirmBooking", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "booking_id" ], "properties": { "booking_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đã chốt" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/bookings/cancel": { "post": { "summary": "Huỷ lịch đặt", "operationId": "cancelBooking", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "booking_id" ], "properties": { "booking_id": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đã huỷ" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/sessions": { "get": { "summary": "Danh sách phiên điều phối", "operationId": "listRosSessions", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Danh sách", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/sessions/start": { "post": { "summary": "Bắt đầu phiên điều phối", "operationId": "startRosSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đang chạy" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/sessions/participants": { "post": { "summary": "Thêm tài nguyên tham gia phiên", "operationId": "addRosSessionParticipant", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "resource_id" ], "properties": { "session_id": { "type": "string" }, "resource_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Đã thêm" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/sessions/complete": { "post": { "summary": "Kết thúc phiên và quyết toán (settlement → ledger, idempotent)", "operationId": "completeRosSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "gmv" ], "properties": { "session_id": { "type": "string" }, "gmv": { "type": "number" }, "orders_count": { "type": "integer" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Bảng quyết toán" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/ros/capacity": { "get": { "summary": "Chỉ số công suất (toàn cụm, hoặc một tài nguyên khi có resource_id)", "operationId": "getCapacityIndex", "parameters": [ { "name": "resource_id", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Chỉ số công suất", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/inventory": { "get": { "summary": "Danh sách pool tồn kho", "operationId": "listInventory", "parameters": [ { "name": "store_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Danh sách pool", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/inventory/reserve": { "post": { "summary": "Giữ chỗ tồn kho (soft-lock)", "operationId": "reserveInventory", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pool_id": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "ttl_seconds": { "type": "integer" }, "store_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Đã giữ chỗ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reservation" } } } }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "409": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/inventory/release": { "post": { "summary": "Trả lại phần đang giữ chỗ", "operationId": "releaseInventory", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reservation_id" ], "properties": { "reservation_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đã trả lại" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/inventory/commit": { "post": { "summary": "Chốt phần giữ chỗ thành trừ kho thật", "operationId": "commitInventory", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reservation_id" ], "properties": { "reservation_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đã chốt" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "409": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/orders": { "post": { "summary": "Tạo đơn hàng", "operationId": "createOrder", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "store_id": { "type": "string" }, "customer_name": { "type": "string" }, "source": { "type": "string" }, "reference": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "pool_id": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" }, "reservation_id": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Đã tạo đơn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "409": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/orders/cancel": { "post": { "summary": "Huỷ đơn hàng", "operationId": "cancelOrder", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bắt buộc với mọi lệnh ghi. Gọi lại cùng khoá trả về đúng kết quả cũ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Đã huỷ" }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/catalog/items": { "get": { "summary": "Danh mục hàng hoá đã đồng bộ", "operationId": "listCatalogItems", "parameters": [ { "name": "source", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Danh sách hàng hoá", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/events": { "get": { "summary": "Sổ sự kiện nền tảng", "operationId": "listEvents", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Danh sách sự kiện", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/webhook-endpoints": { "get": { "summary": "Danh sách điểm nhận webhook", "operationId": "listWebhookEndpoints", "responses": { "200": { "description": "Danh sách", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } }, "post": { "summary": "Đăng ký điểm nhận webhook", "operationId": "createWebhookEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "inventory.updated", "inventory.reserved", "inventory.released", "inventory.committed", "order.created", "order.paid", "order.cancelled", "order.fulfilled", "catalog.updated", "catalog.sync.completed", "catalog.sync.failed", "stream.created", "stream.started", "stream.ended", "stream.failed", "ai.job.created", "ai.job.completed", "ai.job.failed", "booking.confirmed", "booking.cancelled", "session.completed", "payout.requested", "payout.paid" ] } } } } } } }, "responses": { "201": { "description": "Đã tạo, trả secret ký một lần duy nhất", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/usage": { "get": { "summary": "Mức sử dụng và hạn mức tài nguyên", "operationId": "getUsage", "responses": { "200": { "description": "Tổng hợp 30 ngày" }, "401": { "description": "Lỗi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found", "invalid_request", "conflict", "idempotency_error", "rate_limit_error", "quota_exceeded", "api_error", "upstream_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } } } }