{
    "openapi": "3.1.0",
    "info": {
        "title": "Bếp Âu Á — Technical Services Catalog, Recommendation, NLWeb & Service Feed API",
        "summary": "API dữ liệu kỹ thuật, bảng giá tham khảo và hỏi đáp NLWeb công khai của Bếp Âu Á (suabepaua.com).",
        "version": "1.0.0",
        "description": "Đặc tả OpenAPI 3.1.0 chính thức cho hệ thống REST API công khai của Trung Tâm Kỹ Thuật Cơ Điện & Bếp Công Nghiệp Bếp Âu Á (https://suabepaua.com). Cho phép tra cứu danh mục 78 chuyên mục dịch vụ sửa chữa và bảo trì kỹ thuật tại TP. Hồ Chí Minh, đối chiếu dịch vụ phù hợp theo triệu chứng sự cố, truy vấn hỏi đáp ngôn ngữ tự nhiên NLWeb có dẫn nguồn và truy xuất nguồn cấp dữ liệu dịch vụ có cấu trúc.",
        "contact": {
            "name": "Bếp Âu Á",
            "url": "https://suabepaua.com/lien-he/",
            "email": "suabepaua@gmail.com"
        },
        "license": {
            "name": "Content Provenance & Attribution Policy — Bếp Âu Á (suabepaua.com)",
            "url": "https://suabepaua.com/ai.txt"
        }
    },
    "servers": [
        {
            "url": "https://suabepaua.com/wp-json/suabepaua-ai/v1",
            "description": "Production AI & NLWeb REST API Server (suabepaua.com)"
        }
    ],
    "paths": {
        "/catalog": {
            "get": {
                "operationId": "getSuabepauaServiceCatalog",
                "summary": "Tra cứu danh mục 78 dịch vụ kỹ thuật, thông số chẩn đoán, khung giá tham khảo và chế độ bảo hành",
                "description": "Trả về thông tin thực thể kỹ thuật, chính sách SLA/bảo hành và danh sách đầy đủ 78 dịch vụ sửa chữa, bảo trì tại TP.HCM hoặc chi tiết một dịch vụ cụ thể khi lọc theo slug, category hoặc từ khóa.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "query",
                        "required": false,
                        "description": "Slug của trang dịch vụ cần tra cứu chi tiết (ví dụ: sua-bep-tu-cong-nghiep, do-ro-ri-nuoc-am-tuong, sua-may-pha-ca-phe-chuyen-nghiep).",
                        "schema": {
                            "type": "string",
                            "example": "sua-bep-tu-cong-nghiep"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "description": "Lọc theo nhóm chuyên ngành kỹ thuật (ví dụ: fnb, hut-khoi, nuoc, cua-tu-dong, cong-nghiep, bao-tri).",
                        "schema": {
                            "type": "string",
                            "example": "fnb"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Từ khóa tìm kiếm theo tên thiết bị hoặc triệu chứng hư hỏng.",
                        "schema": {
                            "type": "string",
                            "example": "bếp từ báo lỗi E0"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Giới hạn số lượng dịch vụ trả về (1 - 78).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 78,
                            "example": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Danh mục dịch vụ kỹ thuật, thông tin thực thể và khung giá tham khảo tương ứng.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CatalogResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/recommend": {
            "get": {
                "operationId": "recommendSuabepauaService",
                "summary": "Đối chiếu và gợi ý chuyên khoa dịch vụ phù hợp theo triệu chứng sự cố, loại thiết bị, khu vực và nhu cầu B2B",
                "description": "Phân tích mô tả triệu chứng hư hỏng, nhóm thiết bị, ngân sách dự kiến, quận/huyện tại TP.HCM và yêu cầu hợp đồng/VAT B2B để trả về các dịch vụ kỹ thuật phù hợp kèm khung giá và SLA điều phối.",
                "parameters": [
                    {
                        "name": "issue",
                        "in": "query",
                        "required": false,
                        "description": "Mô tả triệu chứng sự cố hoặc thiết bị cần sửa chữa (ví dụ: rò rỉ nước âm tường, bếp âu mất lửa mồi, kẹt cửa cuốn ban đêm).",
                        "schema": {
                            "type": "string",
                            "example": "bếp từ nhà hàng báo lỗi E0 không nóng"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "description": "Nhóm thiết bị hoặc lĩnh vực kỹ thuật tùy chọn (ví dụ: fnb, nuoc, cua-tu-dong, dien-du-phong, cong-nghiep, bao-tri).",
                        "schema": {
                            "type": "string",
                            "example": "fnb"
                        }
                    },
                    {
                        "name": "district",
                        "in": "query",
                        "required": false,
                        "description": "Quận, huyện hoặc TP. Thủ Đức tại TP.HCM để xác định cụm trạm kỹ thuật gần nhất.",
                        "schema": {
                            "type": "string",
                            "example": "Quận 1"
                        }
                    },
                    {
                        "name": "budget",
                        "in": "query",
                        "required": false,
                        "description": "Ngân sách tham khảo dự kiến tính bằng VND (ví dụ: 1500000).",
                        "schema": {
                            "type": "integer",
                            "example": 1500000
                        }
                    },
                    {
                        "name": "is_b2b",
                        "in": "query",
                        "required": false,
                        "description": "1 nếu là doanh nghiệp/nhà hàng/tòa nhà cần biên bản nghiệm thu và hóa đơn VAT, 0 nếu là hộ gia đình.",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                0,
                                1
                            ],
                            "example": 1
                        }
                    },
                    {
                        "name": "urgent",
                        "in": "query",
                        "required": false,
                        "description": "1 nếu là sự cố khẩn cấp cần điều phối kỹ thuật viên 24/7 ngay lập tức.",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                0,
                                1
                            ],
                            "example": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Danh sách dịch vụ kỹ thuật phù hợp kèm khung giá tham khảo, trạm trực chiến và SLA.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RecommendResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ask": {
            "get": {
                "operationId": "askSuabepauaNlwebGet",
                "summary": "NLWeb (Natural Language Web) — Hỏi đáp ngôn ngữ tự nhiên có dẫn nguồn và đối tượng Schema.org (GET)",
                "description": "Giải đáp câu hỏi ngôn ngữ tự nhiên về triệu chứng lỗi thiết bị, quy trình đo kiểm, bảng giá tham khảo, SLA 15-30 phút, bảo hành 06-24 tháng và chính sách B2B VAT kèm dữ liệu Schema.org và liên kết nguồn.",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Câu hỏi ngôn ngữ tự nhiên bằng tiếng Việt hoặc tiếng Anh.",
                        "schema": {
                            "type": "string",
                            "example": "Sửa máy pha cà phê chuyên nghiệp tại Quận 1 giá bao nhiêu và bao lâu thợ tới?"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Câu trả lời dạng Markdown có căn cứ thực tế, dữ liệu cấu trúc Schema.org và danh sách URL trích dẫn.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NlwebAskResponse"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "askSuabepauaNlwebPost",
                "summary": "NLWeb (Natural Language Web) — Hỏi đáp ngôn ngữ tự nhiên có dẫn nguồn và đối tượng Schema.org (POST)",
                "description": "Phiên bản POST nhận payload JSON cho truy vấn hỏi đáp ngôn ngữ tự nhiên chuẩn W3C/Microsoft NLWeb 1.0.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "q"
                                ],
                                "properties": {
                                    "q": {
                                        "type": "string",
                                        "description": "Câu hỏi ngôn ngữ tự nhiên bằng tiếng Việt hoặc tiếng Anh.",
                                        "example": "Dò rò rỉ nước âm tường không đục phá dùng thiết bị gì và bảo hành bao lâu?"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Câu trả lời dạng Markdown có căn cứ thực tế, dữ liệu cấu trúc Schema.org và danh sách URL trích dẫn.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NlwebAskResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/service-feed": {
            "get": {
                "operationId": "getSuabepauaServiceFeed",
                "summary": "Truy xuất nguồn cấp dữ liệu có cấu trúc toàn bộ 78 dịch vụ sửa chữa và bảo trì kỹ thuật",
                "description": "Trả về toàn bộ 78 mục dịch vụ chuẩn hóa (tương đương /openai-service-feed.json) gồm id, title, description, link, markdown_link, category, price_range, service_area, availability, sla, warranty và seller.",
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "description": "Lọc tùy chọn theo tên hoặc mã nhóm danh mục kỹ thuật.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Nguồn cấp dữ liệu dịch vụ có cấu trúc chuẩn OpenAI Service Feed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ServiceFeedResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "SellerInfo": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "legal_name": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "headquarters": {
                        "type": "string"
                    },
                    "hotline": {
                        "type": "string"
                    },
                    "zalo_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "b2b_vat_invoice": {
                        "type": "boolean"
                    }
                }
            },
            "ServiceFeedItem": {
                "type": "object",
                "required": [
                    "id",
                    "title",
                    "description",
                    "link",
                    "markdown_link",
                    "category",
                    "price_range",
                    "service_area",
                    "availability",
                    "sla",
                    "warranty",
                    "seller"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "link": {
                        "type": "string",
                        "format": "uri"
                    },
                    "markdown_link": {
                        "type": "string",
                        "format": "uri"
                    },
                    "category": {
                        "type": "string"
                    },
                    "price_range": {
                        "type": "string"
                    },
                    "service_area": {
                        "type": "string"
                    },
                    "availability": {
                        "type": "string"
                    },
                    "sla": {
                        "type": "string"
                    },
                    "warranty": {
                        "type": "string"
                    },
                    "seller": {
                        "$ref": "#/components/schemas/SellerInfo"
                    }
                }
            },
            "CatalogResponse": {
                "type": "object",
                "properties": {
                    "entity": {
                        "type": "object"
                    },
                    "total_services": {
                        "type": "integer"
                    },
                    "services": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ServiceFeedItem"
                        }
                    }
                }
            },
            "RecommendResponse": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "object"
                    },
                    "recommendations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ServiceFeedItem"
                        }
                    },
                    "emergency_sla": {
                        "type": "object"
                    }
                }
            },
            "NlwebAskResponse": {
                "type": "object",
                "properties": {
                    "protocol": {
                        "type": "string",
                        "example": "W3C-NLWeb/1.0"
                    },
                    "query": {
                        "type": "string"
                    },
                    "answer_md": {
                        "type": "string"
                    },
                    "schema_object": {
                        "type": "object"
                    },
                    "citations": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "title": {
                                    "type": "string"
                                },
                                "url": {
                                    "type": "string",
                                    "format": "uri"
                                }
                            }
                        }
                    }
                }
            },
            "ServiceFeedResponse": {
                "type": "object",
                "properties": {
                    "feed_version": {
                        "type": "string"
                    },
                    "specification": {
                        "type": "string"
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "seller": {
                        "$ref": "#/components/schemas/SellerInfo"
                    },
                    "total_services": {
                        "type": "integer",
                        "example": 78
                    },
                    "services": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ServiceFeedItem"
                        }
                    }
                }
            }
        }
    }
}