CheKin Legals – Native Integration – Page 3

Quick Links:

Download Postman Collection

API Docs

Getting Started:

Account: First you need to get an account. Contact our sales team at partners@chekin.io and they will create an account for you with an email and password.

Token: Use your email & password to get a token using our API:

					
POST https://a.chekin.io/api/v3/token/
{
	"email": "your@user",
	"password": "yourpassword"
}
Response:
{
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiN2JkMzU4NzEyYzJiNDY3ODllM2Y3ZjY1Y2UyM2FlYjgiLCJ1c2VybmFtZSI6Im1hcmlhbm9AY2hla2luLmlvIiwiZXhwIjoxNTcxMjU2OTA2LCJvcmlnX2lhdCI6MTU3MTI1MzMwNiwiaXNfb2NyX2VuYWJsZSI6ZmFsc2UsImZhY2VfZXh0IjpmYWxzZSwib2NyX3ZpeiI6ZmFsc2UsIm9jcl9iYXJjb2RlcyI6ZmFsc2V9.yEYTAeTs3omjqyX4nkWyIogmWcANn-XkUTz2k220Hlg"
}

The token expires within 1 hour, but the same endpoint can be called to get a new one.

Headers: Add these headers in all your following requests:
- Content-Type application/json
- Authorization JWT {{your token}}

Use Case #1: Simplified Guest registration for Legal Compliance

Create a reservation doing a POST to CheKin API. Send all the required information, in a single request and let us take care of the rest. You will need to send some information related to the accommodation, login credentials, the stay dates, and the guests data:

Copy Code

					
POST https://a.chekin.io/api/v3/reservations/
{
   "check_in_date":"2019-10-31", 
   "check_out_date":"2019-11-10",
   "housing": {
        "type": "HOU",
        "name": "My Rental House",
        "police_account": { // Login used in police website, alloggiatiweb in this example 
            "type":"ISP", // Italian State Police
            "username": "police user",
            "password": "police password",
            “certificate_password”: "other police password" // Some authorities require extra fields
         },
        "stat_account": {  // Login used in statistics website, “radar istat” on this example
            "type": "ITRA", // RADAR: A statistics center in Italy
            "username": "statistics user",
            "password": "statistics password"
        },
        "location": { // We ask different data to the guest based in the country
            "country": "IT"
        }
    },
   "guest_group":{
      "number_of_guests":2, // Number of expected guests
      "type":"G", // Group
      "members":[
         {
            "is_leader":true,  // one guest must be the “leader” of the group
            "name":"Pedro",
            "surname":"Perez",
            "birth_date":"1974-03-20",
            "nationality":"ES",
            "document":{
               "type":"P",
               "number":"ABC12345",
               "issue_date":"2015-03-20"
            }
         },
         {
            "name":"Laura",
            "surname":"Garcia",
            "birth_date":"1988-11-22",
            "nationality":"IT",
            "document":{
               "type":"P",
               "number":"CDE5466",
               "issue_date":"2012-05-11"
            }
         }
      ]
   }
}

Response:
{
    "id": "1e35b404a7234006a7416ca88611b99f", // New reservation ID. Save it to check status later.
    "housing": {
        "id": "4badeee28ece41fcb127bc93be70ebd7", // A housing is internally created, and you can use this id to update accommodation details later, or not.
       ...
    },
    ...
    "created_at": "2019-11-06T18:30:30.725510Z",
    "guest_group": {
        "id": "590c61ece4964e3cb8e65b4ebaa82db0", // A guest group is internally created for this reservation. You can use this id to add guests later, or to update guests data.
        "url": "https://a.chekin.io/api/v3/guest-groups/590c61ec-e496-4e3c-b8e6-5b4ebaa82db0/",
        "number_of_guests": 2,
        "leader_id": "1412de6ae14b427e841902d11f31ab50",
        "type": "G",
        "members": [  // guests list
            {
                "id": "1412de6ae14b427e841902d11f31ab50", // guests id can be used later to get details 
                                                                                   // of a single guest.
                "full_name": "Pedro Perez",
                … // guest data fields
                "statuses":{
                 …  // Several statuses can be returned depending on the legal requirements of the country.
                }
            },
           … // other guests of the same reservation
        ]
    },
    "signup_form_link": "https://a.chekin.io/L/9tQqVaHLSTGlGM_-7OBmog", // Online CheKin form
    "aggregated_status": "NEW" // reservation-level status
}

Notice: You must set real and valid login credentials for the legal authorities in fields police_account and/or stat_account. Else, the registration will fail.

Check the full list of parameters required in API Docs.

Optionally, after creating a reservation, you can ask the guests to add their data using the Online Chekin form.
You can check the legal compliance status later using webhooks or polling.
In case of ERROR you can restart a registration.

Use Case #2: Full Integration for Legal Compliance

You can manage Properties, Credentials, Reservations and Guests and implement a two-way synchronization using CheKin API + Webhooks.

Legal Authorities credentials: Depending of the legal requirements of the country, you will need to manage Police Accounts and/or Statistics Accounts. They consist of a username and password, and sometimes some extra ID or a second password. These credentials are given to the Host / Property Owner by the local authorities, and we need them to automate the data sending.
Police:
Example: Italian State Police account

Copy Code

					
POST https://a.chekin.io/api/v3/police-accounts/
{
    "type":"ISP", // This code selects the specific legal authority. Italian State Police on this case
    "username": "police user", // The credentials used by the host to login in the police website
    "password": "police password",
    "certificate_password": "other police password" 
}

Response:
{
    "id": "2b904da7e7ce4859a21dde8133ae6861", // Use this id to manage this account (CRUD)
    "url": "https://a.chekin.io/api/v3/police-accounts/2b904da7-e7ce-4859-a21d-de8133ae6861/",
    "type": "ISP",
    "username": "police user",
    "password": "police password",
    "certificate_password": "other police password",
    "establishment_number": "", // Extra fields required by some other polices
    "external_name": "",
    "external_id": "",
    "local_send_time": "23:00:00", // The time of the day when CheKin sends the data to this Authority
    "delay": "THIS_DAY" // The data is sent the same day of the check-in. In some cases can take more
}

Check more details about parameters and CRUD operations in API Docs.

Statistics:
Example: Italian Statistics center account (called “ISTAT”) for the region of CAMPAGNA

Copy Code

					
POST https://a.chekin.io/api/v3/stat-accounts/
{
    "type":"ITCA", // Select the statistics center
    "username": "istat user", // credentials to login into the statistics website
    "password": "istat password"
}

Response:
{
    "id": "aaf20214643e4ff191e5b15d6462b975", // Use this id to manage this account (CRUD)
    "url": "https://a.chekin.io/api/v3/stat-accounts/aaf20214-643e-4ff1-91e5-b15d6462b975/",
    "type": "ITCA",
    "username": "istat user",
    "password": "istat password",
    "local_send_time": "06:00:00", // The time of the day when CheKin sends the data to this Authority
    "delay": "ONE_DAY",  // The data is sent to istat the same day after the check-in.
    "external_housing_id": "",  // Extra fields required by some other statistics centers
    "external_location_id": "",
    "send_mode": "AGGREGATED" // The data of all the guests of a group is sent at once. 
}

Check more details about parameters and CRUD operations in API Docs.

Housings: Create and manage you accomodations. A “housing” can be any rental unit like a hotel, a vacation rental house or an apartment. Different data about the accommodation can be required depending on the country:

Copy Code

					POST https://a.chekin.io/api/v3/housings/
{
   "name":"My Vacational House 1",
   "type":"HOU", // House, Hotel, others..
   "vatin": "12345", // Value Added Tax Identification Number
   "police_account_id": "2b904da7e7ce4859a21dde8133ae6861",
   "stat_account_id": "aaf20214643e4ff191e5b15d6462b975",
   "location": {
  	 "country": {
	        "code": "IT",
	 }
   },
   "time_zone": "Europe/Rome", 
   "is_police_registration_enabled": true,  // Enable police and stats registration
   "is_auto_police_registration_enabled": true,
   "is_stat_registration_enabled": true
}

Response:
{
    "id": "86f17ce207bf48d6bade2b9f4c839942", // Use this id to manage this housing (CRUD)
    "url": "https://a.chekin.io/api/v3/housings/86f17ce2-07bf-48d6-bade-2b9f4c839942/",
    "type": "HOU",
    "name": "My Vacational House 1",
    "picture": null,
    "police_account": {
        ...
    },
    "stat_account": {
      ...
    },
    "vatin": "12345",
    "tourism_registration_number": "",  // Extra parameters required by some authorities
    "max_capacity": 1, 
    "rooms_quantity": 1,
    "beds_quantity": 1,
    "deregistration_date": null,
    "is_biometric_match_enabled": false, // Automatisms settings
    "is_police_registration_enabled": true, 
    "is_auto_police_registration_enabled": true,
    "is_stat_registration_enabled": true,
    "is_automatic_precheckin_email_enabled": false,
    "is_checkin_complete_email_enabled": false, 
    "is_checkin_docs_email_enabled": false,
    "is_sending_email_once_reservation_data_complete_enabled": false,
    "location": {
        ...
    },
    "status": "COMPLETE", // All the required data for this housing is filled in
    "status_display": "Complete",
    "enabled_features": [
        "police",
        "stat"
    ]
    "time_zone": "Europe/Rome"
}

Automatisms settings:

is_biometric_match_enabled: Extra optional feature to verify guest identity in self-checkin.
is_police_registration_enabled: Enables the data sending to police at a global level for this housing.
is_auto_police_registration_enabled: Enables the automatic data sending at the time set in police account. If disabled, you can still trigger the data sending to the police manually, from our web dashboard.
is_stat_registration_enabled: Enables the data sending to police at a global level for this housing.
is_automatic_precheckin_email_enabled: A self-chekin link is sent to the guest by email, every time a reservation is created. Alternatively, you can take the self-chekin link from reservation and send the email yourself.
is_checkin_complete_email_enabled: An email is sent to the host after the legal compliance is complete for all the guests in a reservation.
is_sending_email_once_reservation_data_complete_enabled:
A documentation email is sent to the host, with a proof of registration in pdf format, for every guest registered in a reservation. This email is sent after all the expected guests are added to the reservation.

Status: The housing status will indicate if all the fields required to accomplish legal compliance are complete, or not. If status in INCOMPLETE means you haven’t provided all the required data.

Quick Setup:
Optionally, the police and/or statistics accounts can be created in the same request:

Copy Code

					
POST https://a.chekin.io/api/v3/housings/
{
   "name":"My Vacational House 1",
   "type":"HOU",
   "vatin": "12345",
   "police_account": {
	    "type":"ISP",
	    "username": "police user",
	    "password": "police password",
	    "certificate_password": "other police password" 
    },
   "stat_account": {
	    "type":"ITCA",
	    "username": "istat user",
	    "password": "istat password"
	},
   "location": {
	"country": {
	        "code": "IT"
    	}
   },
   "time_zone": "Europe/Rome"
}

Check more details about parameters and CRUD operations in the API Docs.

Reservations & Guests:
A reservation contains information related to the stay and it has a “guest group” containing the information related to the guests. We need that information to send it to the legal authorities.There are several options to add guests information

You can create a reservation without guests and add them later:

Copy Code

					
POST https://a.chekin.io/api/v3/reservations/
{
   "check_in_date":"2019-10-31",
   "check_out_date":"2019-11-10",
   "housing_id": "d87799b74bce4118868e22a8f0bef754",
   "guest_group":{}
}


Response:
{
    "id": "78d867207e1c4b32bfaba10e429eed1a", // Use this id to manage this reservation (CRUD)
    "housing": {
       ...
    },
    "check_in_date": "2019-10-31T01:00:00Z",
    "check_out_date": "2019-11-10T01:00:00Z",
    "nights_of_stay": 10,
    "origin": "DEFAULT",
    "external_id": "",
    "created_at": "2019-11-08T14:48:35.318779Z",
    "guest_group": { // An empty guest group will be created
        "id": "0d9803b3261f4f8f9a29ca15cf12f855", // Use this id to manage this guests group (CRUD)
        "url": "https://a.chekin.io/api/v3/guest-groups/0d9803b3-261f-4f8f-9a29-ca15cf12f855/",
        "number_of_guests": 1,
        "leader_id": null,
        "type": "S",
        "members": []
    }
    ...
}

You can use guest_group id or reservation id to add guests through API later.

You can add the guests in the same request

Copy Code

					
POST https://a.chekin.io/api/v3/reservations/
{
   "check_in_date":"2019-10-31",
   "check_out_date":"2019-11-10",
   "housing_id": "d87799b74bce4118868e22a8f0bef754",
   "guest_group":{
      "number_of_guests":2, // Number of expected guests
      "type":"G",
      "members":[ // Guests list
         {
            "is_leader":true, // There is a group leader
            "name":"Pedro",
            "surname":"Perez",
            "gender":"M",
            "birth_date":"1974-03-20",
            "nationality":"ES",
            "document":{
               "type":"P", // Passport
               "number":"ABC12345",
               "issue_date":"2015-03-20"
            }
         },
         {
            "name":"Laura",
            "surname":"Garcia",
            "gender":"F",
            "birth_date":"1988-11-22",
            "nationality":"IT",
            "document":{
               "type":"P",
               "number":"CDE5466",
               "issue_date":"2012-05-11"
            }
         }
      ]
   }
}

Check more details about parameters and CRUD operations in in API Docs.

Self Check-in: You can ask the guests to add their data themselves using the Online CheKin.

You can create a guest and set the guest group id or reservation id, to add it to an existing reservation during creation.

Copy Code

					
POST https://a.chekin.io/api/v3/guests/
{
    "guest_group_id": "0d9803b3261f4f8f9a29ca15cf12f855",
    "is_leader":true,
    "name":"Pedro",
    "surname":"Perez",
    "gender":"M",
    "birth_date":"1974-03-20",
    "nationality":"ES",
    "document":{
       "type":"P",
       "number":"ABC12345",
       "issue_date":"2015-03-20"
    }
}

Response:
{
    "id": "1d8fe5e8e70b4b9ab957817c1e9d22e3", 
    "phone": "",
    "full_name": "Jose Lopez",
    … // Guest data
    "signature": null,
    "origin": "DEFAULT",
    "status": "COMPLETE",
    "status_display": "All the necessary data are filled in"
}

Check more details about parameters and CRUD operations in in API Docs.

Legal Compliance: CheKin will send the data to the different authorities as required, to accomplish legal compliance in time. If some data is missing or wrong, the process can fail, so you need to check the status and take action when needed:
- You can check the legal compliance status using webhooks or polling.
- In case of ERROR you can restart a registration.

FAQ

CheKin Legals – Native Integration

Related Articles

Post a Comment Cancel reply

Company

Support

FAQ

CheKin Legals – Native Integration

Do you have any question related to this post? Please submit a request!

Related Articles

Post a Comment Cancel reply