skills/ridedesk-booking-site/SKILL.md

---
name: ridedesk-booking-site
description: Build a transfer booking, enquiry or rental flow on a RideDesk operator's public API — quote, book, then obey the operator's checkout mode. Use when someone asks to add RideDesk booking to a website, integrate the RideDesk API, build an airport-transfer or taxi booking form, or embed a RideDesk widget.
---

Use this skill when the user wants to put RideDesk booking on a website — a
hand-built form, a framework page, WordPress, or an embedded widget.

## Before anything else: get the operator's host

RideDesk is multi-tenant and **every account is served from its own domain**
(`their-workspace.ridedesk.app` or a custom domain). There is no shared API
host. Ask the user for their RideDesk domain if they have not given it, and
pass it as the `host` argument to the documentation tools so every example
comes back pointed at the right account.

**Never guess, infer, or invent the host.** If the user cannot supply it, say
that the integration cannot be written without it and stop.

## Then load the live contract

Call `get_integration_brief` (with `host`) first. It returns the current flow,
the server-enforced rules and the acceptance criteria in one piece.

For detail, call `get_doc` on `quote-and-book`, `checkout`, or `endpoints`, or
`search_docs` for a specific field name. **Prefer these tools over anything you
remember about RideDesk** — they are served live from the operator's platform,
while these instructions are a snapshot. If a tool result and this file
disagree, the tool is right.

## The flow

1. `GET /api/addons` — extras and their prices.
2. `GET /api/vehicles` — bookable vehicle classes and passenger capacity.
3. `POST /api/quote` — send `pickup_location`, `dropoff_location`, `trip_type`,
   `pickup_date` (and `voucher_code` if the user has one). Returns final
   per-class prices plus a `quote.ref`, valid 45 minutes.
4. `POST /api/transfers` — book with `quote_ref`. Returns `201 { id, pay_token,
   checkout }`.
5. Obey `checkout.mode` from that response — `email` → thank-you page; `link` →
   redirect to `checkout.pay_url`; `inline` → Stripe Payment and Express
   Checkout Elements. The operator changes this setting in their panel, so
   **read it at runtime; never hardcode one payment path.**

## Rules the server enforces

Breaking any of these does not throw — the booking silently stays pending for
manual review, which the user will not notice until bookings pile up.

- **Always book with `quote_ref`.** Never compute, cache, re-apply or "check" a
  price, surcharge, discount or voucher on the client. Quoted prices are final.
- Send `pickup_date` on the quote, or lead-time pricing cannot apply.
- Render the Cloudflare Turnstile widget and send its token on POSTs.
- Add `<script src="https://<host>/embed/attribution.js"></script>` high in
  `<head>` on **every** page, not deferred, and send
  `attribution: window.rdAttribution?.() ?? {}` on every POST. Attribution is
  captured on arrival; reading the URL at submit time reports paid traffic as
  direct.

## Enquiry forms

`POST /api/enquiries` takes the route as **dedicated fields** —
`pickup_location`, `dropoff_location`, `passengers`, `preferred_date`,
`flight_number` — plus `message` and `lang`. `vehicle_interest` carries the
class or car the customer asked for; name it from `GET /api/vehicles`.

Put those in the fields, never only inside `message`: a route buried in prose
is invisible to the operator's filters, list view and reply drafting.

## Offer the no-code path when it fits

If the user is on WordPress, has no developer, or just wants a form on a page,
call `get_widget_snippets` and give them the iframe or the WordPress plugin
instead of writing an integration. Say plainly that it is the smaller job.

## Never do these

- Never state, estimate or cache a RideDesk price, or quote a plan price. Prices
  come from the operator's own rate card via `/api/quote`, at request time.
- Never write credentials into client-side code. The public booking endpoints
  need no API key; the per-account **booking** MCP server does — that is a
  different server from this documentation one (see `get_doc mcp-connector`).
- Never invent an endpoint, field or response shape. If the docs tools do not
  document it, say so and point the user at their panel's `/admin/help`.