API, MCP và dữ liệu mở của Lụa Spa

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 Lụa Spa, 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. Giá trả về qua API giống hệt bảng giá.

Bắt đầu trong một phút

1. Máy chủ MCP: https://spa.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://spa.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://spa.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://spa.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":"facial-lam-diu","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 Lụa Spa 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 Lụa Spa offers (treatments) with prices and links. Filter by category (Chăm sóc da mặt, Massage body, Gội đầu dưỡng sinh, Gói kết hợp), tag, or a free-text query.
• get_pricing: The full price list of Lụa Spa 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 treatments on https://spa.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://spa.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search_content to quote details.
• list_faqs: Answers Lụa Spa 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 Lụa Spa 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_services: Treatments with minutes in the room, price in VND (VAT 8% included, no tip), which therapists do each, feeling tags and what is or is not in it. Category `the` lists memberships, `qua` gift cards.
• list_therapists: The four therapists: role, gender, working days (ISO weekdays) and which treatments each does. No photos of faces, no medical titles.
• suggest_treatment: The treatment finder as a tool: one treatment and one alternative from how the skin and body feel, the time available and any health boxes. Never a diagnosis. When a skin condition under treatment or a wound is set, no facial is suggested and needs_doctor_first is true.
• check_slots: Free start times for one treatment on one date (Vietnam time), optionally with one therapist or a therapist gender. Call this before request_appointment; say the end time and the price out loud; do not guess times. party_size 2 is only the For Two package in the double room.
• request_appointment (gửi đi): Send a booking request; it stays pending until the front desk confirms by phone or Zalo. Before calling, confirm treatment, date, time, therapist, name and phone with the person, tell them "free change until 12 hours before", and get explicit agreement to share contact details and the health boxes. Do not promise any result of the treatment.
• request_change (gửi đi): Ask the front desk to move or cancel a booking, given its code and the last four digits of the phone used. It never confirms by itself and never says who booked what; a wrong pair gets the same answer as a missing booking.
• list_gift_options: Gift card amounts, the option to name a treatment, validity, delivery and the company-order rule.
• request_gift_card (gửi đi): Create a gift card order, pending payment by bank transfer (staff send the details after confirming). No money moves through this tool. The card is sent within one opening hour of the transfer.
• request_membership (gửi đi): Create a membership card order (five or ten visits), pending payment by bank transfer after staff confirm. No money moves through this tool.

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.

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://spa.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. Lụa Spa là doanh nghiệp hư cấu; địa chỉ, mã số thuế, kỹ thuật viên và khách hàng là giả định.