Booking creation¶
This endpoint lets you push a booking in our system. Booking you push to our system are definitive, you should not push them before making sure that the client successfully paid (on your side).
This endpoint shares a lot of similarities with the Real time availability check and Real time price check endpoints, both in the fields we expect from you and the errors you can receive.
You can cancel the booking you create here using the Booking cancellation.
URL¶
This api endpoint is accessible via /{lang}/bookingengine/create_booking/
(replace {lang}
with fr
or en
) via POST, using the sub_instance_url
(see the Rental api endpoint)
Expected fields¶
Required fields¶
start
: The start date of the stay. Format:DD/MM/YYYY
end
: The end date of the stay. Format:DD/MM/YYYY
rental
: The ID of the rental (see the Rental api endpoint)origin
: The name of your configured origin. Ask your Homeloc contact if you don’t have one already.tenant_firstname
: The first name of the tenanttenant_lastname
: The last name of the tenanttenant_email
: The email of the tenanttenant_birthdate
: The birth date of the tenant. Format:YYYY-MM-DD
Optional fields¶
guests_firstname
: A list of the guests’ first names. Names should be separated with commas.guests_lastname
: A list of the guests’ last names. Names should be separated with commas.guests_birthdate
: A list of the guests’ birth dates. Birth dates should have the formatYYYY-MM-DD
and be separated by commas.
Details for guests data¶
The guests_birthdates
field behaves the same way as in the price check.
First and last names are not mandatory for guests and will default to .
. Only the birth dates field will be used to calculate how many guests are present in the booking.
Do note that the tenant must not be contained in the guests data, otherwise she will be counted twice.
Response¶
The response is given in JSON form.
Valid response¶
Here is an example of a valid response:
{
'status': 'ok',
'reservation_id': 5432,
'price': '158.65',
}
The status
key indicates the call you made was valid and we were able to create a booking.
The reservation_id
key is the internal id of the booking you just created. You will need it later on if you want to cancel the booking. Keep it close by :)
The price
key contains a string indicating the price of the stay. If you did not subscribe to any option, this price should be the same as the one you get with the Real time price check.
Invalid response¶
{ 'status': 'error', 'code': 'too_many_guests' 'error': 'This rental is limited to 3 people' }
The status
is not ok
, you call you made was not valid (or we were not able to create a booking).
The code
contains a string telling you what the problem is. You should use this to handle the API’s response. See below for the possible values.
error
contains a string that you can show to the client to explain why the call did not lead to a booking.
Possible error codes¶
Some of these codes are the same than those of the availability check.
bad_dates
: The dates you provided are not valid (isstart
beforeend
?)unavailable
: The rental is not available for the dates you specifiednot_bookable_online
: This code means that you cannot book the rental online. It usually means we don’t have control over the stock for this rentalmin_duration
: The stay you specified does not respect the minimum booking duration (see the Rental API)max_duration
: The stay you specified does not respect the maximum booking duration (see the Rental API)too close
: The stay you specified is too close. Some rentals need to be booked in advance (usually a couple of days).too far
: The stay you specified is too far. Some rentals cannot be booked too long in advance (usually more than a year).badly_filled_form
: This means some (at least one) of the fields were not properly filled. In this case, theerror
of the response contains a list of the badly filled fields.origin_unknown
: The origin you gave us does not match any origin on our side.tenant_too_young
: The tenant is not 18 (she needs to be at least 18 on the day of the booking).too_many_guests
: The rental you chose cannot hold that many guests.
Examples¶
Valid call that creates a booking¶
Booking for two adults
Python¶
import requests response = requests.post( 'https://example.homelocpay.net/en/bookingengine/create_booking', data={ 'start': '17/09/2015', 'end': '18/09/2015', 'rental': '6', 'origin': 'My Partner Name', 'tenant_firstname': 'John', 'tenant_lastname': 'Watson', 'tenant_email': 'john@watson.com', 'tenant_birthdate': '1980-01-01', 'guests_firstname': 'Sherlock', 'guests_lastname': 'Holmes', 'guests_birthdates': '1980-01-01', } )
API response¶
{ 'status': 'ok', 'reservation_id': 221, 'price': '155.55' }
Too many guests¶
Booking for four adults when the rental has a maximal capacity of 3
Python¶
import requests response = requests.post( 'https://example.homelocpay.net/en/bookingengine/create_booking', data={ 'start': '17/09/2015', 'end': '18/09/2015', 'rental': '6', 'origin': 'My Partner Name', 'tenant_firstname': 'John', 'tenant_lastname': 'Watson', 'tenant_email': 'john@watson.com', 'tenant_birthdate': '1980-01-01', 'guests_firstname': '', 'guests_lastname': '', 'guests_birthdates': ',,', } )
API response¶
{ 'status': 'error', 'code': 'too_many_guests' 'error': 'This rental is limited to 3 people' }