--- title: "Sổ Sách Sáng: developer docs" description: "API, MCP server, errors, rate limits and versioning for Sổ Sách Sáng" canonical: https://sosachsang.thenexova.cloud/docs.md lang: en last-updated: 2026-10-04 --- # Sổ Sách Sáng: 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://sosachsang.thenexova.cloud/AGENTS.md - OpenAPI: https://sosachsang.thenexova.cloud/openapi.json - API catalog (RFC 9727): https://sosachsang.thenexova.cloud/.well-known/api-catalog - llms.txt: https://sosachsang.thenexova.cloud/llms.txt ## MCP Endpoint: `https://sosachsang.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://sosachsang.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 Sổ Sách 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 Sổ Sách Sáng offers (services) with prices and links. Filter by category (tax, books, setup, consult), tag, or a free-text query. - `get_pricing`: The full price list of Sổ Sách 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 services on https://sosachsang.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://sosachsang.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search_content to quote details. - `list_faqs`: Answers Sổ Sách Sáng 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 Sổ Sách 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 Sổ Sách Sáng: names, roles and short bios. Use the id with availability tools to book a specific person. - `check_availability`: Free appointment times on a date (YYYY-MM-DD, Vietnam time), optionally for one service or person. Bookable up to 21 days ahead, at least 3 hours from now. Call before request_booking. - `request_booking` (ghi / writes): Create a booking request at Sổ Sách Sáng. It is held as pending until staff confirm by phone or Zalo, and returns a booking reference. Before calling: check_availability, read the details back to the person (date, time, service, party size, name, phone) and get their explicit agreement to share contact details. - `get_tax_deadlines`: Upcoming tax filing and payment deadlines in Vietnam (2026 to March 2027) for small companies and household businesses, with the legal date and the actual working day after weekend or holiday shifts. Filter by business type. Checked 04/10/2026. - `estimate_fee`: Estimate the fixed monthly fee at Sổ Sách Sáng from the business type, documents per month and staff count. Same rules as the calculator on the website. Prices exclude 8% VAT. ## HTTP API ### 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://sosachsang.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ề `{ ok, code, status: "pending", summary }`; 409 khi vừa kín chỗ, kèm gợi ý thay thế. ### 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://sosachsang.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. Responses carry `RateLimit-Policy: "writes";q=5;w=3600`, and a 429 carries `Retry-After: 3600`. Reads are not limited. ## 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: no version is deprecated today. When one is, its responses carry `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594) with the retirement date, and this page says so. ## Who runs this - [About](https://sosachsang.thenexova.cloud/en/about) - [Contact](https://sosachsang.thenexova.cloud/en/contact) - [Privacy policy](https://sosachsang.thenexova.cloud/en/privacy) - [Terms](https://sosachsang.thenexova.cloud/en/terms) - xinchao@sosachsang.demo · 0900 000 001 _Trang mẫu của THE NEXOVA. Sổ Sách Sáng là doanh nghiệp hư cấu; địa chỉ, mã số thuế, nhân sự và khách hàng là giả định._