API, MCP và dữ liệu mở của Nhà Sương

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 Nhà Sương, 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ố 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://homestay.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://homestay.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://homestay.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://homestay.thenexova.cloud/api/booking \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: dat-cho-20261012-01' \
     -d '{"date":"2026-10-12","checkOut":"2026-10-14","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.

Các endpoint

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.

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 Nhà Sương 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 Nhà Sương offers (rooms) with prices and links. Filter by category (Phòng), tag, or a free-text query.
• get_pricing: The full price list of Nhà Sương 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 rooms on https://homestay.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://homestay.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search_content to quote details.
• list_faqs: Answers Nhà Sương 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 Nhà Sương 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 Nhà Sương: names, roles and short bios. Use the id with availability tools to book a specific person.
• list_rooms: Rooms with size, beds, max guests, what the window faces, steps from the lounge (the gate to the lounge is a further 46 stone steps), features and the regular midweek rate in VND (VAT, service and breakfast for two included). Filters narrow the list; they never invent a room.
• check_room_availability: For a check-in and check-out date: the nights, the minimum nights rule, and for each room whether it is free, the rate of each night with its season band, the total and the deposit. Read only; returns no guest data. When the dates fail the minimum nights rule it returns the rule instead of rooms.
• get_stay_quote: Nightly lines, the long-stay discount, extra guests, extras, the total in VND, the deposit percent and amount, when the balance is due and the cancellation tiers that apply. Read only; never says confirmed. Does not check that the room is free: use check_room_availability for that.
• get_stay_policies: Check-in and check-out times, the deposit percent, cancellation tiers, child and pet rules, stay registration, quiet hours and stove hours. With dates, the rules of the strictest night of the stay; without, the regular-season rules and the exceptions.
• list_local_experiences: Four things the house arranges: the sunrise cloud-hunting car, the fireside dinner, the car to the vintage train, the airport pickup. Price, unit and notice. The train ticket is at the station price; no ticket price is given.
• request_booking (gửi đi): Hold one room for the dates as a pending request. Read back room, dates, nights, guests, total, deposit, name and phone to the person and get their agreement to share contact details before calling (consent: true). Staff confirm by phone or Zalo the same day; the deposit is paid by bank transfer after that, never through this tool. Never accepts card, bank or ID numbers.

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.

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.

Thư xác nhận gửi tới email người đặt chỉ đi với yêu cầu từ form trên site (đã qua Cloudflare Turnstile). Yêu cầu qua API hoặc MCP vẫn được ghi nhận và báo cho doanh nghiệp, nhưng khách không nhận thư; hãy báo lại mã và trạng thái cho người đặt.

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://homestay.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.json: OpenAPI 3.1, có schema cho mọi phản hồi và lỗi
• /docs.md: Tài liệu này dạng Markdown
• /AGENTS.md: Khi nào nên dùng site này và các quy tắc cho trợ lý số
• /llms.txt: Mục lục nội dung cho máy đọc
• /auth.md: Xác thực: không cần khoá
• /.well-known/api-catalog: Danh mục API (RFC 9727)
• /.well-known/mcp/server-card.json: 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. Nhà Sương là doanh nghiệp hư cấu; địa chỉ, mã số thuế, người làm và khách hàng là giả định.