Chiavistello - API Documentation

Access

The client must provide a valid token bound to a single Chiavistello device
The owner will provide the token to the supplier using APIs and can invalidate it at any time
Access is allowed only over HTTPS (secure socket) using TLS 1.2
You can use our integrations with other services
Your API Key (token) is available in your control panel in the "Notification" section

Calling APIs

Endpoint: https://chiavistello.it/api
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"
}

Response

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

switchList List device switches

Request

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

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"
}

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
}

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,
	    "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
}

Request by externalReference

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

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,
	"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"
}

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"
}

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)
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
}

Response

{
    "deleted": 14223
}

guestList List of bookings guests

Request

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

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,
	    "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"
		},
		"2": {
		    "fname": "Luigi",
		    "lname": "Galvani",
		    "sex": "M",
		    "bornd": "09/09/1737",
		    "borns": "Italia",
		    "bornp": "Bologna BO",
		    "nat": "Italia",
		    "ress": "Italia",
		    "resp": "Bologna BO"
		}
	    },
	    "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
}

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
}

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"
}

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
}

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

Calling APIs

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