# nisebookings

> Hosted booking service for businesses (https://app.nisebookings.com): appointments, group bookings,
> recurring series, packages, waiting lists and event tickets. Integrate it with two lines of HTML (an
> embeddable web component) or with a REST API (one public key per business).

The engine re-checks every booking server-side inside a transaction (capacity can never be exceeded,
two customers can never get the same seat), prices are always recomputed on the server, one
checkout is one order with one payment, and all times are UTC on the wire but business-local in the UI.

Integration rules that prevent most mistakes: send back the exact `start` (and `staffId`) a slot
search returned; handle `409 slot_unavailable` by re-fetching slots; never compute prices or times
client-side; the business's public key is the only credential on the public side; send an
`Idempotency-Key` header on `POST bookings`/`tickets`/`reschedule` (and any management-API `POST`) and retry with the
same key — never a blind retry without one.

## Docs

- [When to use it](09-when-to-use.md): honest fit check — the use cases this serves best, the ones it cannot serve (multi-day rentals, calendar sync, SMS, file uploads, a third widget language), and how it compares to Cal.com, Calendly, SimplyBook.me and Bookly.
- [Quickstart](01-quickstart.md): add bookings to a website, WordPress (Custom HTML block), or a custom front-end in minutes; troubleshooting table.
- [Concepts](02-concepts.md): account (tenant), catalogue, services and their four types, when a time is bookable, appointments/bookings/orders, statuses, money, notifications, time zones, Dutch↔English glossary.
- [Widget reference](03-widget-reference.md): `<nise-booking>` and `<nise-events>` attributes, every flow step, payment return handling, CSS custom properties, accessibility, WordPress, limits.
- [Public API](04-public-api.md): every endpoint with exact request/response JSON, error codes, `Idempotency-Key` retries (24 h, `Idempotent-Replayed`, 409/422), payment lifecycle, integration recipes (Mollie checkout, recurring, waiting list, tickets).
- [Management API](../api/README.md): configure your account from code with a scoped key — settings, opening hours, categories, services, staff, schedules, holidays; OpenAPI spec ([yaml](../api/openapi.yaml) · [json](../api/openapi.json)) and a scripted end-to-end example.
- [MCP server](../api/mcp.md): hosted MCP endpoint `https://app.nisebookings.com/api/mcp` (Streamable HTTP, `Authorization: Bearer nk_…`); connect snippets for Claude Code, Codex, Cursor and VS Code; tool list; errors, `force` and scopes.
- [Admin guide](05-admin-guide.md): roles, calendar, appointments, services, staff, customers, packages, events, payments, coupons, settings tabs, public customer pages.
- [Notifications](06-notifications.md): template types, recipients, timing, template language, all `{codes}`, retries, background processing.
- [Data and privacy](07-data-and-privacy.md): what is stored, account isolation, what is publicly reachable, deleting data.
- [Webhooks](10-webhooks.md): `POST /api/v1/webhooks {url, events}` → signed JSON (Standard Webhooks: `webhook-id`, `webhook-timestamp`, `webhook-signature` v1 HMAC-SHA256, `whsec_` secret) for `booking.created|updated|cancelled`, `ticket.created|approved|cancelled`, `payment.completed|failed|refunded`; thin payloads (ids + status); retries 1m…24h (7 attempts); deliveries log + retry; test ping; secret rotation; plain-Node verifier.
- [Sandbox](08-sandbox.md): `POST https://app.nisebookings.com/api/sandbox` (no auth) → a 24-hour test account with `publicKey` + all-scopes `apiKey`; sample staff/services/event; 5 per hour per IP; mail is never delivered (read it via `GET /api/v1/outbox` or MCP `list_outbox`); Mollie goes to a fake checkout page; `DELETE /api/v1/sandbox` removes it.

## For coding agents

- [agents/README.md](agents/README.md): which instruction file to use with Codex, Claude Code, Cursor and GitHub Copilot, and where to place it.
- [agents/AGENTS.md](agents/AGENTS.md): drop-in AGENTS.md for the project that integrates this service (paths, invariants, error codes, verification).
- [agents/claude/nisebookings/SKILL.md](agents/claude/nisebookings/SKILL.md): Claude Code skill — copy to `.claude/skills/nisebookings/`.
- [agents/copilot-instructions.md](agents/copilot-instructions.md): copy to `.github/copilot-instructions.md`.
- [examples/](examples/README.md): widget embed (`embed.html`) and headless booking script (`headless.mjs`).

## Machine-readable

- [openapi.yaml](openapi.yaml) · [openapi.json](openapi.json): OpenAPI 3.1 description of the entire public API (`/api/public/{key}/**`).
- [llms-full.txt](llms-full.txt): all guide pages concatenated into one document.