Bookings

هذه الصفحة بالإنجليزية عمدًا: أسماء الحقول والأوامر يجب أن تُقرأ تمامًا كما يعرضها المنتج وواجهة البرمجة.

A published holiday home (listing_type holiday_home, priced per night) can be booked from the website in three calls, when the company has bookings switched on. Otherwise these operations answer 404.

1. Availability and rules

GET /api/v1/listings/{slug}/availability?from=YYYY-MM-DD&to=YYYY-MM-DD returns the blocked ranges in the window (start inclusive, end exclusive, never who booked) and the home’s rules:

• min_nights, max_nights;
• closed_arrival_days (0 = Monday to 6 = Sunday);
• advance_days, notice_hours;
• available_from, available_to;
• check_in_time, check_out_time.

Up to 400 days per call; the default window is the year ahead. The answer is cached briefly.

2. A quote

GET /api/v1/listings/{slug}/quote?check_in=…&check_out=…&guests=N gives the price of a stay before the visitor asks for it: each night’s price, every fee line (such as a tourism fee), the deposit and the total, as decimal strings in the company’s currency.

Dates the home cannot take answer 400 with a problem code (min_nights, arrival_day, notice, advance, unavailable, …) so the form can say why.

3. The booking request

POST /api/v1/bookings is the request itself, from the visitor’s browser like an enquiry: the same publishable key, origin, consent, challenge and hidden website rules as lead forms.

Fields: listing, check_in, check_out, guests, name, email, phone, message, language, consent, consent_version.

The answer gives the booking reference and the stay address: the guest’s own page on the company’s host, where the status, the quote and later the payment live.

What happens next

• The dates are held for the company’s hold period while staff confirm.
• Nothing is charged at request. The guest pays after the company confirms, within the home’s payment window, from the stay page and the confirmation email.
• The website never collects payment details and never asks for identity documents: those are refused as in lead forms.

Keeping a calendar in step

Webhooks booking.requested, booking.confirmed, booking.paid and booking.cancelled carry the booking id, reference and listing id only, so a website can refresh its calendar without ever holding guest data. See Webhooks.

The guest space

Guests who want to see their stays, pay, or come back later sign in to the company’s guest space, which can be embedded in the website.