com.beachvalencia/booking

WHEN: use it only after the traveller has (1) picked ONE category and dates, (2) given name, email and phone, and (3) EXPLICITLY accepted the cancellation policy — never set `accepted_terms: true` on your own. WHAT IT RETURNS: `booking_id`, `checkout_url` (a page on beachvalencia.com that shows the breakdown and asks the guest to tick the cancellation policy BEFORE jumping to Stripe), `expires_at` (ISO 8601, ~30 min in the future), `hold_minutes: 30`, total/nightly EUR, nights, guests, property, deposit, cancellation summary, `terms_url`, `idempotent` (true if a prior request with the same category+dates+pax+email was replayed), and a `message` ready to show to the guest. PAYMENT: always on Stripe, hosted at beachvalencia.com. The agent NEVER charges the guest itself. If the hold expires without payment, the unit is released automatically and a new request is needed. The price is the public rate (no member discount, no coupon codes — if the guest has a code, they apply it on the web). IDEMPOTENCY: a replay with the same category, dates, pax and email returns the same booking. EXAMPLE: {"id":"G4","check_in":"2027-05-22","check_out":"2027-05-27","adults":4,"guest_name":"Ada Lovelace","guest_email":"ada@example.com","guest_phone":"+34612345678","language":"en","accepted_terms":true}.

WHEN: use it whenever the traveller asks about cancellation, deposit, check-in/out times, or Spanish traveller registration ("what time can I arrive?", "is there a deposit?", "what if I cancel 10 days before?"). WHAT IT RETURNS: `check_in` (from 16:00 Europe/Madrid), `check_out` (by 11:00), `cancellation.summary` (free up to 14 calendar days before arrival) + `cancellation.details_url`, `deposit` (50 € refundable in pool/garage units), `online_check_in` (SES.Hospedajes link by email), and `contact` (reservas@beachvalencia.com). EXAMPLE: {"language":"en"}.

WHEN: use it after `search_availability` when the traveller wants to compare or see more detail about one specific category, or asks "tell me more about G4". WHAT IT RETURNS: description, max_guests, bedrooms (text + count), size_sqm, zone, generic location ("La Patacona, Alboraya — 30 m from the sea" / "Valencia city, close to the centre"), `location_summary` (how long to the old town, tram, airport…), `highlights` (terrace, sea views, pool, parking, m²), amenities (parking, pool_seasonal), up to 3 photos, `trust` (same block as search_availability), a `booking_url_base` to open the listing with no dates, and the Priority note. DO NOT ask here for the exact street address or access codes: they are only sent to the guest by email after a booking is confirmed. EXAMPLE: {"id":"G4","language":"en"}.

WHEN: use it when the traveller fixes ONE category and wants the exact total for a given date range ("how much is G4 from 8 to 15 June for 6?"). WHAT IT RETURNS: `available` boolean, `total_price_eur`, `nightly_avg_eur`, `nights`, `guests`, `deposit`, `cancellation` summary, `cancellation_details_url`, `booking_url`. When not available, `available: false` and the `booking_url` falls back to the search page (plus `hint` to call `search_availability`). The price is the public rate charged at checkout to a non-member with no discount code — if the traveller has a code, they enter it themselves on beachvalencia.com. EXAMPLE: {"id":"G4","check_in":"2027-06-08","check_out":"2027-06-15","adults":6}.

WHEN: use it whenever the traveller asks "what do you have from X to Y for N people" or shows date flexibility. WHAT IT RETURNS: `matches[]` with one entry per available category (G1..G6, G4B) ordered by total price, including name, zone (beach/city), bedrooms, m², highlights, location summary, photos, total/nightly EUR price (public rate, no discount code) and a `booking_url` with dates+pax prefilled. Also `alternatives[]` (up to 6, each with `reason` like "same dates, other category" or "2 days earlier, same category") when matches are empty or `flexible_days > 0`, `minimum_stay_only[]` for categories that would be available with a longer stay, `no_results_reason` when nothing applies, and `trust` (rating 9.4/10, 320+ Booking reviews, cheaper than Booking.com, Stripe payment, 14-day free cancellation, languages supported). Direct prices are BELOW Booking.com for the same dates. FLEXIBLE PARAMETERS: `flexible_days` (0–3, default 0) shifts the check-in by ±N days to broaden alternatives; `budget_eur` filters matches and alternatives by TOTAL EUR; `zone` ("beach" | "city" | "any", default "any"); `min_bedrooms` (default 1 — a sofa bed does not count). EXAMPLE: {"check_in":"2027-05-22","check_out":"2027-05-27","adults":4,"flexible_days":2,"budget_eur":900,"zone":"beach","min_bedrooms":2}.