Integration between Partner and Chekin API to import listing and reservation into CheKin ecosystem, preferably with webhooks in order to keep sync the 2 systems in real time. End-users will use both Partner and CheKin solution.
Flow:
The first step to set up the integration and test it would be to get a test account by contacting partners@chekin.io. Make sure to specify the email you would like to use for your test account and the origin (the generic name of your system within CheKin that will be used to mark your users in our system). For example, email – DonaldDuck@happycompany.com; origin – happycompany.
Once the partner has the credentials, he/she is able to log into the dashboard (https://dashboard.chekin.io/login) or work with the API.
After receiving the credentials the user can log into the system by making the following
POST request to /api/v3/token/.
curl -X POST \
https://a.chekin.io/api/v3/token/ \
-H 'Content-Type: application/json' \
-d '{
"email": "username@email.host",
"password": "secret"
}'
The request will return a JSON with a JWT token in response:
{
"token": "eyJ0eXAiOiJKV1QJ.....some..long..token..value....Fvdx3tvxe4dilwapHRYiQwS8"
}
If the credentials are invalid, the following error will return:
{
"non_field_errors": [
"Unable to log in with provided credentials."
]
}
Token update
The token received allows the user to make API calls to CheKin. The token lasts 1 (one) hour. In order to get a new token the following request containing the old token should be made to /api/v3/token/refresh/:
curl -X POST \
https://a.chekin.io/api/v3/token/refresh/ \
-H 'Content-Type: application/json' \
-d '{
"email": "username@email.host",
"password": "secret"
"token": "..."
}'
In case your token is still active and you request a new token, there will be two active tokens for the account until the first one is due.
Unauthorized access
The token is mandatory for making calls to the API. If the user makes a request to the API without an access token the following error will return:
{
"code": 4002,
"message": "Invalid Authorization header. No credentials provided.",
"status_code": 401,
"errors": []
}
Reset Password
To change the password for the account the following POST request should be made to /api/v3/users/me/:
curl -X POST \
https://a.chekin.io/api/v3/users/me/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
"password": "secret2",
"old_password": "secret",
}'
Where the old_password is the current password, and the password is the new password the user would like to set.
The user will get a JSON with the user data in response.
{
'id': '2a0f1613bc614813a69a520c9b48f51c',
'name': '',
'surname': '',
'first_name': '',
...
}
In order to create an account, the user should enter an email address and a password into the relevant form on the PMS side. The credentials entered by the user should be included in a POST request to api/v3/auth/registration/. The request should also contain the origin of the user that you specified when getting a test account:
curl -X POST \
https://a.chekin.io/api/v3/auth/registration/ \
-H 'Content-Type: application/json' \
-d '{
"email": "username@email.host",
"password": "secret",
"origin": "happycompany”
}'
After that, the account with the user email and password, and a unique JWT token are created. The PMS will receive the response with the JWT token in the following format:
{
"token": "eyJ0eXAiOiJKV1QJ.....some..long..token..value....Fvdx3tvxe4dilwapHRYiQwS8"
}
After the account is created the user should be redirected to the login page (https://dashboard.chekin.io/login), and an email with the credentials should be sent to the user. The user will enter the CheKin dashboard using the credentials from the email.
In order to create a housing in CheKin, make a POST request to /api/v3/housings/ with the following payload with the specified name, type, and location of the housing:
curl -X POST \
https://a.chekin.io/api/v3/housings/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Amazing Housing",
"type": "HOU",
"location": {
"country": "ES",
"community": "ES-AN",
"province": "ES-AL",
"address": "housing address"
}
}
For more information on the location, refer to the API documentation.
The request above will return a json containing the housing information including the housing id, which the PMS needs to make further operations with this housing;
{
"id": "8ecaf8888f844a049c60da1d7b0d3f1d",
"url": "https://a.chekin.io/api/v3/housings/8ecaf888-8f84-4a04-9c60-da1d7b0d3f1d/",
"type": "HOU",
"name": "Amazing Housing"
…
}
Housing types
It is mandatory to specify the housing type HOU (Vacation Rental) or HOT (Hotel / Hostel / Hostal Campground / B&B) if you are planning to connect a police account to the given property.
https://integrations.chekin.io/housing-types/
Updating a Housing
You can update a housing by making a PATCH request to /api/v3/housings/{{HOUSING_ID}}/ with the payload containing the set of fields you mean to update:
curl -X PATCH \
https://a.chekin.io/api/v3/housings/{{HOUSING_ID}}/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Super-Amazing housing"
}'
In response, you will receive a json with the updated housing information:
{
"id": "8ecaf8888f844a049c60da1d7b0d3f1d",
"url": "http://api-ng.chekintest.xyz/api/v3/housings/8ecaf888-8f84-4a04-9c60-da1d7b0d3f1d/",
"type": "HOU",
"name": "Super-Amazing housing",
…
}
Deleting a Housing
To delete a housing make a DELETE request to the /api/v3/housings/{id}/ endpoint:
curl -X DELETE \
https://a.chekin.io/api/v3/housings/c2fcc7a252e64a23b4cd4111a22874f0/ \
-H 'Authorization: JWT {{TOKEN}}'
Checking the existing housings
To retrieve the list of all your housings with the detailed information, make a GET request to /api/v3/housings/:
curl -X GET \
https://a.chekin.io/api/v3/housings/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json'
To retrieve the detailed information of one specific housing, make a GET request to /api/v3/housings/{{HOUSING_ID}}/ with specified housing ID:
curl -X GET \
https://a.chekin.io/api/v3/housings/{{HOUSING_ID}}/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json'
To create a reservation in CheKin make a POST request to /api/v3/reservations/ with the specified
- check-in date – ”check_in_date” – DateTime
- check-out date – “check_out_date” – DateTime
- the id of the housing the reservation belongs to – “housing_id” – ID
- main guest full name – “default_leader_full_name” – string,
- main guest email – “default_invite_email” – Email:
curl -X POST \
https://a.chekin.io/api/v3/reservations/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
"check_in_date": "2019-06-25",
"check_out_date": "2019-06-30",
"housing_id": "{{HOUSING_ID}}",
"default_leader_full_name": "Name Surname",
"default_invite_email": "some.email@example.org"
}'
The command will return a json with the reservation information, including the checkin-online link you can share with the guests:
{
"id": "{{id}}",
...
"signup_form_link": "http://a.chekin.io/L/..."
}
Updating a reservation
To update a reservation make a PATCH request to the /api/v3/reservations/:id/ endpoint with a specified reservation ID and the set of fields that need to be updated.
curl -X PATCH \
https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
"check_out_date": "2019-11-01"
}'
Deleting a reservation
To delete a reservation from your account make a DELETE request to the /api/v3/reservations/{id}/ endpoint.
curl -X DELETE \
https://a.chekin.io/api/v3/reservations/c2fcc7a252e64a23b4cd4111a22874f0/ \
-H 'Authorization: JWT {{TOKEN}}'
Checking the existing reservations
To retrieve the list of all your reservations with the detailed information, make a GET request to /api/v3/reservations/:
curl -X GET \
https://a.chekin.io/api/v3/reservations/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json'
To retrieve the detailed information of one specific reservation, make a GET request to /api/v3/reservations/:id/ with specified reservation ID:
curl -X GET \
https://a.chekin.io/api/v3/reservations/{{RESERVATION_ID}}/ \
-H 'Authorization: JWT {{TOKEN}}' \
-H 'Content-Type: application/json'
- Get guest data by guest group id
GET https://a.chekin.io/api/v3/guest-groups/4707a97810504e8084b8b16f6f22f298/ Response: { "id":"4707a97810504e8084b8b16f6f22f298", "url":"https://a.chekin.io/api/v3/guest-groups/4707a978-1050-4e80-84b8-b16f6f22f298/", "number_of_guests":2, "members":[ // guests list { // one guest data "id":"ff23cc1796764f52bbf727afe81a82be", "phone":"", "full_name":"MARTIN PEREZ", "name":"MARTIN", "surname":"PEREZ", "second_surname":"", "gender":"M", "birth_date":"1984-08-11", … // some extra fields and structures may be present. They are used for Italy or other countries requiring extra data "language":"eng", "nationality":{ "code":"AR", "alpha_3":"ARG", "name":"Argentina" }, "names":{ "name":"MARTIN", "surname":"PEREZ" }, "document":{ "id":"629a8c349cd146199ff32d4d550f9e71", "type":"P", "number":"AAA875441", "issue_date":"2012-05-17", … // some extra fields may be present for Italy or other countries "type_str":"Passport" }, "status":"COMPLETE", // status is not used without police connection "status_display":"All the necessary data are filled in" }, { // another guest "id":"2f3d24418d084476ae28bbc484ca1224", "phone":"", "full_name":"CARLOS GONZALEZ FERNANDEZ", "name":"CARLOS", "surname":"GONZALEZ", "second_surname":"FERNANDEZ", "gender":"M", "birth_date":"1967-11-24", … } ], "leader_id":"ff23cc1796764f52bbf727afe81a82be", // In some countries like italy there is a guest leader, usually the first guest. "type":"G" } - Get reservation by ID and looking at field “guest_group”
GET https://a.chekin.io/api/v3/reservations/c4f529e7ad5c4c96a6dd6c3d61072705/ Response: { "id": "c4f529e7ad5c4c96a6dd6c3d61072705", … // reservation data "guest_group": { "number_of_guests":2, "members":[ … // guests data as described in a. ] } } - Get the full List of your reservations and get guest_group from each one
GET https://a.chekin.io/api/v3/reservations/ Response: { "count":5, // total reservations "next":null, // used with pagination "previous":null, "results":[ // List of reservations { "id":"7a2b3fe5c5d34463aa2583f09de5ab75", ... // Reservation and housing data "guest_group":{ "id":"06adcc1c9a194f858335ee22bbb1d3e3", "number_of_guests":2, "members":[ { "id":"74567767b20f47f5a14b4333b55a26b0", "full_name":"Alejandro Perez", ... // Full guest data }, { "id":"40e6099998964ec7947b84354f00c321", "full_name":"Sara Gomez", ... // Full guest data } ], "leader_id":"74567767b20f47f5a14b4333b55a26b0", "type":"G" }, ... }, { "id":"d52b50adcf6446ca9f4c9305cfbe5538", ... // Reservation and housing data "guest_group":{ "id":"4707a97810504e8084b8b16f6f22f298", "number_of_guests":2, "members":[ { "id":"ff23cc1796764f52bbf727afe81a82be", "full_name":"MARIANO MARTINEZ", ... // Full guest data }, { "id":"2f3d24418d084476ae28bbc484ca1224", "full_name":"CARLOS GONZALEZ FERNANDEZ", ... // Full guest data } ], "leader_id":"ff23cc1796764f52bbf727afe81a82be", "type":"G" }, ... } ] } - Subscribe to webhooks to be notified every time a guest is added:
POST https://a.chekin.io/api/v3/webhooks/ { "target": "https://your.domain.con/target-endpoint/", "event": "Guest.created" } Response { "id": "5adecfc46a6c4b72a15c98fe0e96b048", "event": "Guest.created", "target": "https://your.domain.con/target-endpoint/" }Every time a guest is added we will do a POST request to your endpoint sending the following data:
{ "hook": { "id": "fab8af5dd0074d04a42395d00890c310", "event": "Guest.created", "target": "http://example.org/target-url/" }, "data": { "reservation_id": "620186f602de439faffb6caa71b5014e", "guest_id": "3cdcede6af45448ebaf28315d09ceec2", "guest_origin": "CH_ONLINE" } }You can use the guest id or reservation id to retrieve the guest data in that moment. Example using guest_id:
GET https://a.chekin.io/api/v3/guests/3cdcede6-af45-448e-baf2-8315d09ceec2/ Response: { "id":"3cdcede6af45448ebaf28315d09ceec2", "phone":"", "full_name":"MARTIN PEREZ", "name":"MARTIN", "surname":"PEREZ", "second_surname":"", "gender":"M", "birth_date":"1984-08-11", … // some extra fields and structures may be present. They are used for Italy or other countries requiring extra data "language":"eng", "nationality":{ "code":"AR", "alpha_3":"ARG", "name":"Argentina" }, "names":{ "name":"MARTIN", "surname":"PEREZ" }, "document":{ "id":"629a8c349cd146199ff32d4d550f9e71", "type":"P", "number":"AAA875441", "issue_date":"2012-05-17", … // some extra fields may be present for Italy or other countries "type_str":"Passport" }, // other status fields can be ignored in this use case. They are used when the house is connected with legal authorities (police, statistics..). }Find more information about webhook events available in API Docs