--- title: "Lụa Spa: developer docs" description: "API, MCP server, errors, rate limits and versioning for Lụa Spa" canonical: https://spa.thenexova.cloud/docs.md lang: en last-updated: 2026-10-06 --- # Lụa Spa: tài liệu cho nhà phát triển / developer docs Không cần khoá API. Mọi lỗi dưới /api trả về `application/problem+json` (RFC 9457). Giới hạn 5 yêu cầu ghi mỗi giờ cho mỗi IP. No API key. Errors under /api are `application/problem+json` (RFC 9457). Write endpoints allow 5 requests per hour per IP. - Agent instructions (when to use this site, rules): https://spa.thenexova.cloud/AGENTS.md - Developer guide (HTML): https://spa.thenexova.cloud/developers - OpenAPI: https://spa.thenexova.cloud/openapi.json - API catalog (RFC 9727): https://spa.thenexova.cloud/.well-known/api-catalog - llms.txt: https://spa.thenexova.cloud/llms.txt ## MCP Endpoint: `https://spa.thenexova.cloud/mcp`. Streamable HTTP, stateless, JSON responses. Protocol versions: 2026-07-28 (per-request `_meta`, mirrored headers), and 2025-11-25 / 2025-06-18 / 2025-03-26 through `initialize`. ```bash curl -s https://spa.thenexova.cloud/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: tools/list' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}}}' ``` - `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` (ghi / writes): 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` (ghi / writes): 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` (ghi / writes): 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` (ghi / writes): 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` (ghi / writes): Create a membership card order (five or ten visits), pending payment by bank transfer after staff confirm. No money moves through this tool. ## HTTP API `GET https://spa.thenexova.cloud/api` lists every endpoint with the docs, OpenAPI and MCP addresses. ### GET /api/offers Dịch vụ và giá, phân trang bằng cursor. `?limit=1..50` (mặc định 20), `?cursor=`, tuỳ chọn `?category=`, `?locale=vi|en`. Trả về `{ ok, items, total, limit, next_cursor }`; `next_cursor` là `null` ở trang cuối. ```bash curl -s 'https://spa.thenexova.cloud/api/offers?limit=2' ``` ### POST /api/lead JSON hoặc form-urlencoded. Bắt buộc: `name`, `phone` (≥ 9 chữ số), `consent` = `"1"`. Tuỳ chọn: `email`, `need`, `note`, `locale` (`vi`|`en`). ```bash curl -X POST https://spa.thenexova.cloud/api/lead -H 'Content-Type: application/json' -d '{"name":"Nguyễn Văn A","phone":"0900000000","note":"Gọi lại giúp tôi","consent":"1"}' ``` ### GET /api/availability `?date=YYYY-MM-DD[&offer=][&resource=][&party=]` hoặc `?month=YYYY-MM` (tỉ lệ còn trống theo ngày). ### POST /api/booking Bắt buộc: `date`, `time` (HH:MM), `name`, `phone`, `consent` = `"1"`. Tuỳ chọn: `offerId`, `resourceId`, `party`, `email`, `note`. Trả về **202 Accepted** với `{ ok, code, status: "pending", statusUrl, summary }` và header `Location: /api/booking/`: yêu cầu chờ nhân viên gọi xác nhận. 409 khi vừa kín chỗ, kèm gợi ý thay thế. ### GET /api/booking/{code} Trạng thái của một yêu cầu đặt chỗ: `{ ok, code, status: "pending" | "confirmed" | "cancelled", done, date, ... }`. Không trả thông tin liên hệ. Hỏi lại tối đa mỗi phút một lần; `done` thành `true` khi đã xác nhận hoặc huỷ. ### POST /api/subscribe Bắt buộc: `email`. ## Authentication None. Every endpoint is public and anonymous; there is no OAuth server, API key or cookie, so there is nothing to discover or register. Write endpoints need the person's explicit consent, sent as `consent`. Details: https://spa.thenexova.cloud/auth.md ## Errors Every non-2xx response under `/api` is `application/problem+json` (RFC 9457): `type`, `title`, `status`, optional `detail`, and `fields` (a map of field name to message) on 422. The `type` is `about:blank#` with codes such as `invalid`, `too_many`, `bad_origin`, `not_found`, `method_not_allowed`. Messages follow the `locale` you send. | Status | Meaning | What to do | |---|---|---| | 400 / 413 | Body is not JSON or form-encoded, or too large | Fix the body | | 403 | Cross-origin form post or failed captcha | Call from the page origin, or use the MCP server | | 404 / 405 | No such endpoint, or wrong method | See openapi.json | | 409 | Slot just filled (bookings) | Offer the alternatives in the response | | 422 | Missing or invalid fields | Read `fields`, ask the person, retry | | 429 | Rate limit reached | Wait for `Retry-After` seconds, then retry | ## Rate limits Write endpoints (`POST /api/lead`, `POST /api/booking`, and the MCP tools that call them) allow 5 requests per hour per client IP. Every `/api` response carries `RateLimit-Policy: "writes";q=5;w=3600`; write responses also carry `RateLimit: "writes";r=;t=3600` with what is left of your quota, and a 429 carries `Retry-After: 3600`. Reads are not limited. ## Test mode (sandbox) Add `?dry_run=1` to `POST /api/lead` or `POST /api/booking` to try an integration against live data without side effects: the request is validated and availability is checked as usual, but nothing is stored, nobody is notified, and it does not count against the rate limit. The reply has `test: true` (and a `TEST-` booking code) with status 200. ## Idempotency `POST /api/lead` and `POST /api/booking` accept an `Idempotency-Key` header (8 to 64 characters from `A-Z a-z 0-9 _ . : -`). Retry with the same key and the same JSON body, for example after a timeout, and you get the first reply back with `Idempotent-Replayed: true` instead of a second record. Keys are kept for 24 hours and match on the key and the body, not on your IP. The same key with a different body returns 422 (`idempotency_key_reused`). Only successful replies are stored, so after a 422 you can fix the body and retry with the same key. A replay does not count against the rate limit. ## Versioning The API is at version 2.0 (`info.version` in openapi.json) and every `/api` response carries `API-Version: 2.0`. Within 2.x we only add optional fields and new endpoints. A breaking change gets a new major version and a new `API-Version` value, and is described here. Deprecation policy: nothing is removed silently. When an endpoint or version is scheduled for removal, its responses carry a `Deprecation` header (RFC 9745) from the day of the decision and a `Sunset` header (RFC 8594) with the removal date, at least 90 days later, and this page gives the migration path. No endpoint is deprecated today. Every `/api` response links here with `Link: ; rel="deprecation"`. ## Who runs this - [About](https://spa.thenexova.cloud/en/about) - [Contact](https://spa.thenexova.cloud/en/contact) - [Privacy policy](https://spa.thenexova.cloud/en/privacy) - contact@thenexova.com · 0963 929 241 _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._