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
Calling APIs
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)
- token secret
- action requestType
Actions
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 recordsetmatches: 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 listmatches: 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 dayspage: (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 recordsetmatches: 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
}
