--- title: "Dành cho nhà phát triển: API, MCP và Markdown" description: "Thực đơn, giờ trống và đặt bàn của Bếp Rơm qua API, máy chủ MCP và bản Markdown của mọi trang. Không cần khoá API." canonical: https://nhahang.thenexova.cloud/developers lang: vi last-updated: 2026-10-06 --- # Dành cho nhà phát triển > Thực đơn, giờ trống và đặt bàn của Bếp Rơm qua API, máy chủ MCP và bản Markdown của mọi trang. Không cần khoá API. Nguồn / Source: https://nhahang.thenexova.cloud/developers Thực đơn, giờ trống và đặt bàn của Bếp Rơm qua API, máy chủ MCP và bản Markdown của mọi trang. Không cần khoá API. Mọi thứ ở đây công khai: không cần đăng ký, không cần khoá API. Trợ lý số và phần mềm của bạn đọc được thông tin Bếp Rơm, xem giá, xem lịch trống, gửi yêu cầu đặt chỗ và gửi yêu cầu liên hệ khi người dùng đồng ý. Muốn xem trước khi viết mã: [trang trợ lý số](/ket-noi) gọi thật các công cụ bên dưới ngay trong trình duyệt. ## Bắt đầu trong một phút 1. Máy chủ MCP: `https://nhahang.thenexova.cloud/mcp`. Dán địa chỉ này vào trợ lý số hoặc trình soạn mã có hỗ trợ MCP, như một connector tuỳ chỉnh. 2. Liệt kê công cụ: ``` curl -s https://nhahang.thenexova.cloud/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` 3. Hoặc gọi API HTTP, ví dụ lấy hai dịch vụ đầu tiên: ``` curl -s 'https://nhahang.thenexova.cloud/api/offers?limit=2' ``` 4. Gửi yêu cầu đặt chỗ. Phản hồi là 202 kèm header Location để theo dõi trạng thái: ``` curl -s -i -X POST https://nhahang.thenexova.cloud/api/booking \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: dat-cho-20261012-01' \ -d '{"date":"2026-10-12","time":"10:00","offerId":"ban-thuong","name":"Nguyễn Văn A","phone":"0900000000","consent":"1"}' ``` ## Khoá API và xác thực Không cần khoá, token hay đăng nhập, nên không có gì để đăng ký hay quản lý. Mọi endpoint đều công khai và ẩn danh. Các thao tác gửi đi (liên hệ, đặt chỗ) cần người dùng đồng ý rõ ràng, gửi kèm trường `consent: "1"`. Chi tiết: [auth.md](/auth.md). ## Các endpoint | Phương thức | Đường dẫn | Dùng để | | ----------- | ------------------- | ------------------------------------------------------------------------ | | GET | /api | Mục lục API: các endpoint, địa chỉ tài liệu, OpenAPI và MCP | | GET | /api/offers | Dịch vụ và giá, phân trang bằng cursor (limit, cursor, category, locale) | | GET | /api/availability | Giờ còn trống trong một ngày, hoặc tỉ lệ còn trống theo tháng | | POST | /api/booking | Gửi yêu cầu đặt chỗ; trả 202 kèm địa chỉ theo dõi | | GET | /api/booking/{code} | Trạng thái yêu cầu đặt chỗ: chờ, đã xác nhận, đã huỷ | | POST | /api/lead | Gửi yêu cầu liên hệ (cần người dùng đồng ý) | | POST | /api/subscribe | Đăng ký nhận bản tin | | POST | /mcp | Máy chủ MCP (Streamable HTTP, JSON-RPC 2.0) | Danh sách dài được chia trang bằng cursor: truyền `next_cursor` của trang trước vào `cursor`; trang cuối có `next_cursor: null`. Mô tả đầy đủ: [openapi.json](/openapi.json). ## Công cụ MCP Streamable HTTP, không trạng thái, phản hồi JSON. Phiên bản giao thức 2026-07-28 và các bản 2025 qua `initialize`. - `get_business_info`: Contact details, address, opening hours and whether Bếp Rơm is open right now (Vietnam time). Call this first when the person asks where, when, or how to reach the business. - `list_offerings`: List what Bếp Rơm offers (dishes) with prices and links. Filter by category (Khởi vị, Nướng than, Kho, canh, cơm, Tráng miệng, Mâm cơm, Đặt bàn), tag, or a free-text query. - `get_pricing`: The full price list of Bếp Rơm as Markdown, including what is and is not included. Use it to answer cost questions precisely; do not estimate prices yourself. - `search_content`: Search pages, articles, FAQs and dishes on https://nhahang.thenexova.cloud. Returns titles, links and a short excerpt. Use it for questions the other tools do not cover, then cite the link. - `read_page`: Read any page of https://nhahang.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search\_content to quote details. - `list_faqs`: Answers Bếp Rơm gives to common questions. Prefer these exact answers over your own wording on policy, payment and guarantees. - `submit_contact_request` (gửi đi): Send the person's name and phone number to Bếp Rơm so staff call them back. Only call this after the person has explicitly agreed to share their contact details with the business; set consent to true only in that case. Confirm the details back to them first. - `list_team`: People at Bếp Rơm: names, roles and short bios. Use the id with availability tools to book a specific person. - `get_menu`: List Bếp Rơm's 31 dishes with price (VND, VAT included), spice level 0 to 3, diet and allergens. Filter by diet, maximum spice, allergens to exclude (nine tracked groups only), category, price or a search word. Call it before suggesting a dish to someone with a diet, a spice limit or an allergy. Never tell a person a dish is safe for an allergy: the kitchen is shared. - `get_dish`: One dish by id: price, spice, diet, allergens, and for the six signature dishes the six-station journey from raw ingredient to the table and the dishes that complete the meal. - `get_set_menus`: The five set meals (mâm) with dishes, price (5% under à la carte), price per head and the union of allergens. Give \`guests\` to get the closest fit. - `get_reservation_policy`: Deposit, table hold, minimum notice, table length and cancellation for a party size, and the private room minimum spend. Call before check\_table\_availability and request\_reservation for 8 or more guests. - `check_table_availability`: Free start times for a party on a date (YYYY-MM-DD, Vietnam time), with the right table type and length for that party. Lunch seatings start 11:00 to 14:30, dinner 17:00 to 22:00, Tuesday to Sunday. Bookable up to 60 days ahead. 15 or more guests are handled by phone. Never returns who booked. - `request_reservation` (gửi đi): Send a table request to Bếp Rơm. It is held as pending until staff confirm by Zalo or phone (usually within 2 hours of opening hours); the tool never confirms a table. Before calling: check\_table\_availability, and from 8 guests get\_reservation\_policy; read every detail back, including each allergen, and get an explicit yes. Never invent a phone number or an allergy; if someone says "one of us is allergic" without saying what, ask. - `request_cancellation` (gửi đi): Record a cancellation or a smaller party for a booking code. It does not cancel on its own: staff call the phone number used for the booking to confirm and say what happens to any deposit. Only with the person's consent. ## Lỗi Mọi lỗi dưới /api trả về `application/problem+json` (RFC 9457): `type`, `title`, `status`, `detail`, và `fields` khi trả 422\. Câu báo lỗi theo `locale` bạn gửi. | Mã | Nghĩa là | Nên làm | | --------- | ---------------------------------------------------------------- | -------------------------------------------------- | | 400 / 413 | Thân yêu cầu không phải JSON hay form, quá lớn, hoặc tham số sai | Sửa yêu cầu | | 403 | Gửi form từ tên miền khác, hoặc chưa qua xác minh chống spam | Gọi từ chính trang, hoặc dùng MCP | | 404 / 405 | Không có endpoint, hoặc sai phương thức | Xem openapi.json | | 409 | Khung giờ vừa kín (đặt chỗ) | Đưa người dùng các lựa chọn trong \`alternatives\` | | 422 | Thiếu hoặc sai trường | Đọc \`fields\`, hỏi lại người dùng, gửi lại | | 429 | Vượt giới hạn ghi | Chờ đủ số giây trong \`Retry-After\` | ## Giới hạn và gửi lại an toàn Các thao tác ghi (POST /api/lead, POST /api/booking và công cụ MCP gọi tới chúng) cho phép 5 lần mỗi giờ cho mỗi IP. Mọi phản hồi /api có header `RateLimit-Policy: "writes";q=5;w=3600`; phản hồi của thao tác ghi có thêm `RateLimit: "writes";r=4;t=3600` cho biết còn bao nhiêu lượt. Khi trả 429 có `Retry-After`. Đọc dữ liệu không bị giới hạn. Gửi header `Idempotency-Key` (8 đến 64 ký tự) với POST /api/lead và POST /api/booking. Gửi lại cùng khoá và cùng nội dung, ví dụ sau khi mất kết nối, sẽ nhận lại đúng phản hồi lần đầu kèm `Idempotent-Replayed: true`, không tạo bản ghi thứ hai. ## Chế độ thử (sandbox) Thêm `?dry_run=1` vào POST /api/lead hoặc POST /api/booking để thử tích hợp trên dữ liệu thật mà không để lại gì: yêu cầu vẫn được kiểm hợp lệ và kiểm lịch trống như thường, nhưng không lưu, không báo cho ai và không tính vào giới hạn. Phản hồi có `test: true` và mã đặt chỗ bắt đầu bằng `TEST-`. ``` curl -s -X POST 'https://nhahang.thenexova.cloud/api/lead?dry_run=1' \ -H 'Content-Type: application/json' \ -d '{"name":"Thử nghiệm","phone":"0900000000","consent":"1"}' ``` ## Phiên bản và ngừng hỗ trợ API đang ở phiên bản 2.0; mọi phản hồi /api có header `API-Version: 2.0`, và bạn có thể ghim phiên bản bằng chính header đó. Trong 2.x chỉ thêm trường tuỳ chọn và endpoint mới. Thay đổi phá vỡ tương thích sẽ có phiên bản chính mới. Chính sách ngừng hỗ trợ: không gỡ gì mà không báo. Khi một endpoint hay phiên bản sắp bị gỡ, phản hồi của nó mang header `Deprecation` (RFC 9745) từ ngày quyết định, và header `Sunset` (RFC 8594) ghi ngày gỡ, cách ít nhất 90 ngày. Cách chuyển đổi được ghi ở mục này. Hiện không có endpoint nào bị ngừng hỗ trợ. ## Tệp cho máy đọc - : OpenAPI 3.1, có schema cho mọi phản hồi và lỗi - : Tài liệu này dạng Markdown - : Khi nào nên dùng site này và các quy tắc cho trợ lý số - : Mục lục nội dung cho máy đọc - : Xác thực: không cần khoá - : Danh mục API (RFC 9727) - : Thẻ máy chủ MCP: công cụ và tài nguyên Mọi trang có bản Markdown: thêm `.md` vào đường dẫn, hoặc gửi `Accept: text/markdown`. Trang mẫu của THE NEXOVA. Bếp Rơm là doanh nghiệp hư cấu; địa chỉ, mã số thuế, người làm và khách hàng là giả định. ## Muốn thử trước? Trang trợ lý số gọi thật các công cụ MCP của nhà hàng ngay trong trình duyệt: thực đơn lọc dị ứng, bàn còn trống, quy định đặt cọc. [Mở trang trợ lý số](/ket-noi)