Chiavistello - API Documentation

Access

The client must provide a valid token bound to a single Chiavistello property
The owner will provide the token to the integrator and can invalidate it at any time
You can use our integrations with other services
Your API Key (token) is available in your control panel in the "Notification" section

OpenAPI v3.0 REST

Swagger-UI standard documentation and tester available here

Legacy APIs Deprecated

Endpoint: https://chiavistello.it/api
TLS: Only HTTPS with TLS (plain HTTP not allowed) Charset: UTF-8
Data type: JSON
Methods:

Raw POST of JSON (curl -d @request.json https://chiavistello.it/api)
POST with www-form-encoded (as for a web-form submit) posting JSON in variable named "data" (curl -F data='{"token":"secret", "action":"switchList"}' https://chiavistello.it/api)
POST JSON file as web-form file upload (curl -F data=@request.json https://chiavistello.it/api)

JSON request (common fields):

token secret
action requestType

info Device information

Request

{
    "token": "secret",
    "action": "info"
}

Copy to tester

Response

{
    "device": {
	"serial": "00000000712b0b7d",
	"name": "Appartamento Chiavistello",
	"online": 1
    }
}

switchList List device switches

Request

{
    "token": "secret",
    "action": "switchList"
}

Copy to tester

Response

{
    "switchList": [
	{
	    "id": 1,
	    "name": "Portone condominiale|Main door"
	},{
	    "id": 2,
	    "name": "Porta appartamento|Apartment door"
	},{
	    "id": 3,
	    "name": "Camera Rossa|Red room"
	},{
	    "id": 4,
	    "name": "Camera Blu|Blue room"
	}
    ]
}

partitionList List device partitions

Request

{
    "token": "secret",
    "action": "partitionList"
}

Copy to tester

Response if partitioned

{
    "partitionList": [
	{
	    "id": 1,
	    "name": "Camera Rossa",
	    "switches": [
	    	1,
		2,
		3
	    ]
	},{
	    "id": 2,
	    "name": "Camera Blu",
	    "switches": [
	    	1,
		2,
		4
	    ]
	}
    ]
}

Response if not partitioned

{
    "partitionList": [
	{
	    "id": 0,
	    "name": "Unpartitioned"
	}
    ]
}

bookingList List bookings

Request

{
    "token": "secret",
    "action": "bookingList",
    "all": 1,
    "page": 0
}

Copy to tester all: (Optional) If set to 1 lists all bookings, else only those with checkOut after now()
perPage: (Optional) Items to return per request (max 50)
page: (Optional) Page number (starting from 0)

Response

{
    "bookingList": [
	{
	    "id": 14223,
	    "partition": 1,
	    "name": "Alessandro Volta",
	    "phone": "+393351112222",
	    "email": "alessandro.volta@gmail.com",
	    "checkIn": "2018-10-25 18:30:00",
	    "checkOut": "2018-10-27 10:30:00",
	    "status": 0,
	    "openToken": "4434ddes345afhdf446342deabd323ddc",
	    "pin": "12345",
	    "notify": 1,
	    "price": 40,
	    "pricePaid": 0,
	    "documentRequest": 1,
	    "documentComplete": 1,
	    "externalReference": "443223DFRE"
	}
    ],[
    	...
    ],
    "matches": 4,
    "nextPage": 1
}

bookingList: Array of associative arrays with bookings (see bookingSet for details) with 50 elements per recordset
matches: Total number of results matching the request
nextPage: Next page to request (if not present this was the last page)

bookingGet Get single booking

Request by id

{
    "token": "secret",
    "action": "bookingGet",
    "id": 14223
}

Copy to tester

Request by externalReference

{
    "token": "secret",
    "action": "bookingGet",
    "externalReference": "443223DFRE"
}

Copy to tester

Response

{
    "booking": {
	"id": 14223,
	"partition": 1,
	"name": "Alessandro Volta",
	"phone": "+393351112222",
	"email": "alessandro.volta@gmail.com",
	"checkIn": "2018-10-25 18:30:00",
	"checkOut": "2018-10-28 11:30:00",
	"status": 0,
	"openToken": "4434ddes345afhdf446342deabd323ddc",
	"pin": "12345",
	"notify": 1,
	"price": 40,
	"pricePaid": 0,
	"documentRequest": 1,
	"documentComplete": 1,
	"externalReference": "443223DFRE"
    }
}

bookingSet Insert/Update booking

Request only mandatory data for insertion

{
    "token": "secret",
    "action": "bookingSet",
    "partition": 1,
    "name": "Alessandro Volta",
    "checkIn": "2018-10-25 18:30:00",
    "checkOut": "2018-10-28 11:30:00"
}

Copy to tester

Request update

{
    "token": "secret",
    "action": "bookingSet",
    "id": 14223,
    "partition": 1,
    "name": "Alessandro Volta",
    "phone": "+393351112222",
    "email": "alessandro.volta@gmail.com",
    "checkIn": "2018-10-25 18:30:00",
    "checkOut": "2018-10-28 11:30:00",
    "status": 0,
    "pin": "12345",
    "notify": 1,
    "price": 40,
    "pricePaid": 0,
    "documentRequest": 1,
    "externalReference": "443223DFRE"
}

Copy to tester

Response always with full data

{
    "booking": {
	"id": 14223,
	"partition": 1,
	"name": "Alessandro Volta",
	"phone": "+393351112222",
	"email": "alessandro.volta@gmail.com",
	"checkIn": "2018-10-25 18:30:00",
	"checkOut": "2018-10-28 11:30:00",
	"status": 0,
	"openToken": "4434ddes345afhdf446342deabd323ddc",
	"pin": "12345",
	"notify": 1,
	"price": 40,
	"pricePaid": 0,
	"documentRequest": 1,
	"externalReference": "443223DFRE"
    }
}

Notes

If present id field the request will be an update else will be an insertion of a new booking.
The record will be updated only with the fields provided: missing fields will remain unchanged.

id: If 0 (or missing) insertion, else update existing
partition: Partition id (mandatory if partitioned)
name: Visible name of booking (mandatory)
phone: Guest's phone number (international format, +xxyyyyyyyy)
name: Guest's E-Mail address
checkIn: Check-in date and time (yyyy-mm-dd hh:mm:ss) (mandatory)
checkOut: Check-out date and time (yyyy-mm-dd hh:mm:ss) (mandatory)
openToken: Read-only (generated by system on booking creation) URL will be https://chiavistello.it/open/openToken
status: 0=Active 1=opening inhibit 2=disabled (defaults to 0)
pin: Numeric PIN (0=PIN not required, defaults to random generated)
notify: Notification: 0=no 1=yes 2=only first access 3=first access done (defaults to 1)
price: Payment request
pricePaid: Amount paid of payment request
documentRequest: Guest document form (number of guests, 0=no, defaults to 0)
documentComplete: Read-only flag present if document form is complete for all guests
externalReference: Foreign key reference (for external sync, max 80 chars), reported only if present
ownerBooking: Read-only flag reported with value '1' only if true that indicates the booking is for owners

bookingDelete Delete booking

Request

{
    "token": "secret",
    "action": "bookingDelete",
    "id": 14223
}

Copy to tester

Response

{
    "deleted": 14223
}

guestList List of bookings guests

Request

{
    "token": "secret",
    "action": "guestList",
    "page": 0
}

Copy to tester page: (Optional) Page number (starting from 0)

Response

{
    "guestList": [
	{
	    "id": 14223,
	    "partition": 1,
	    "name": "Alessandro Volta",
	    "phone": "+393351112222",
	    "email": "alessandro.volta@gmail.com",
	    "checkIn": "2018-10-25 18:30:00",
	    "checkOut": "2018-10-27 10:30:00",
	    "documentRequest": 2,
	    "documentComplete": 1,
	    "externalReference": "443223DFRE",
	    "guests": {
		"1": {
		    "fname": "Alessandro",
		    "lname": "Volta",
		    "sex": "M",
		    "bornd": "18/02/1745",
		    "borns": "Italia",
		    "bornp": "Como CO",
		    "nat": "Italia",
		    "doct": "CID",
		    "docn": "112321",
		    "docp": "Como CO",
		    "ress": "Italia",
		    "resp": "Como CO",
			"pic": [
				"path/pic1.jpg",
				"path/pic2.jpg"
			]
		},
		"2": {
		    "fname": "Luigi",
		    "lname": "Galvani",
		    "sex": "M",
		    "bornd": "09/09/1737",
		    "borns": "Italia",
		    "bornp": "Bologna BO",
		    "nat": "Italia",
		    "ress": "Italia",
		    "resp": "Bologna BO",
			"pic": [
				"path/pic1.jpg",
				"path/pic2.jpg"
			]
		}
	    },
	    "complete": true,
	    "updated": "2018-10-25 13:15:24"
	}
    ],[
    	...
    ],
    "matches": 4,
    "nextPage": 1
}

guestList: Array of associative arrays with guests list
matches: Number of results matching the request
nextPage: Next page to request (if not present this was the last page)

paymentList List payments requests/confirmations

Request

{
    "token": "secret",
    "action": "paymentList",
    "all": 1,
    "page": 0
}

Copy to tester all: (Optional) if set to 1 lists all payment requests, else only those with created or paid newer than 3 days
page: (Optional) Page number (starting from 0)

Response

{
    "paymentList": [
	{
	    "id": 3284,
	    "created": "2019-12-22 13:59:07",
	    "amount": 95.00,
	    "purpose": "Extra night",
	    "token": "ffd45de32sa1f4",
	    "externalReference": "fdfj309fk330dd",
	    "paid": "2019-12-22 14:22:12",
	    "channel": "paypal",
	    "response": {
	    	...
		[payment gateway response data]
	    	...
	    }
	}
    ],[
    	...
    ],
    "matches": 2,
    "nextPage": 1
}

paymentList: Array of associative arrays with payment requests (see paymentSet for details) with 50 elements per recordset
matches: Number of results matching the request
nextPage: Next page to request (if not present this was the last page)

paymentGet Get single payment request/confirmation

Request

{
    "token": "secret",
    "action": "paymentGet",
    "id": 3284
}

Copy to tester

Response

{
    "payment": {
	    "id": 3284,
	    "created": "2019-12-22 13:59:07",
	    "amount": 95.00,
	    "purpose": "Extra night",
	    "token": "ffd45de32sa1f4",
    	    "externalReference": "MTE334A",
    	    "lang": "en",
	    "paid": "2019-12-22 14:22:12",
	    "channel": "paypal",
	    "response": {
	    	...
		[payment gateway response data]
	    	...
	    }
    }
}

paymentSet Set payments requests/confirmations

Request

{
    "token": "secret",
    "action": "paymentSet",
    "amount": 95.00,
    "purpose": "Extra night",
    "externalReference": "MTE334A",
    "lang": "en"
}

Copy to tester

Response

{
    "payment": {
	    "id": 3284,
	    "created": "2019-12-22 13:59:07",
	    "amount": 95.00,
	    "purpose": "Extra night",
	    "token": "ffd45de32sa1f4",
    	    "externalReference": "MTE334A",
	    "lang": "en"
    }
}

Notes

If present id field the request will be an update else will be an insertion of a new payment request.
The record will be updated only with the fields provided: missing fields will remain unchanged.
Paid requests cannot be modified (but can be deleted).

id: If 0 (or missing) insertion, else update existing
amount: Amount in Euro
purpose: Purpose of payment, visible to user
token: Read-only (generated by system on creation) URL will be https://chiavistello.it/mypayments/id?token=token
externalReference: Foreign key reference (for external sync, max 80 chars), reported only if present
lang: Optional language code (reported only if present), if missing it defaults to user's browser settings: used for VReception totem systems

paymentDelete Delete payment request/confirmation

Request

{
    "token": "secret",
    "action": "paymentDelete"
    "id": 3284
}

Copy to tester

Response

{
    "deleted": 3284
}

Integrations with other services

Integromat

Integromat is a very advanced online automation platform. Take a tour!

Zapier

App currently under review, available on invite at this link

RSS

Easily integrate notification using a private RSS feed: activate RSS under your control panel in the "Notification" section

Access

OpenAPI v3.0 REST

Legacy APIs Deprecated

Actions

Request

Response

Request

Response

Request

Response if partitioned

Response if not partitioned

Request

Response

Request by id

Request by externalReference

Response

Request only mandatory data for insertion

Request update

Response always with full data

Notes

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Notes

Request

Response

Integrations with other services

Integromat

Zapier

RSS

API Test Request

Result