|
|
| (75 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | [[Category:Apps]] | + | #REDIRECT [[:Category:API_V2]] |
| − | [[Category:API]]
| |
| − | [[Category:Automation]]
| |
| − | | |
| − | <div class="heading">API Version 2.0</div>
| |
| − | | |
| − | This page explains the capabilities of the API Version 2.0 and explains how to use it.
| |
| − | | |
| − | = Capabilities =
| |
| − | API V2 can allow third parties to access your account.
| |
| − | | |
| − | = Invite codes =
| |
| − | To grant a third party access to your account, you will need to provide them with an invite code.
| |
| − | | |
| − | | |
| − | '''Step 1: Select what the third party can access'''
| |
| − | | |
| − | Click the generate invite code button and select the scopes of the invite code.
| |
| − | Scopes determine what the third party will be able to access, and what they can do with it.
| |
| − | See the scopes section for more information.
| |
| − | | |
| − | | |
| − | '''Step 2: Linked properties'''
| |
| − | | |
| − | Decide if you want the third party to be able to access your linked properties, or just the properties in your account.
| |
| − | | |
| − | | |
| − | '''Step 3: IP Whitelisting '''
| |
| − | | |
| − | If you add an IP address here, only that IP address will be able to access your account using the invite code.
| |
| − | | |
| − | Multiple IP addresses can be added if separated by commas, e.g.
| |
| − | 192.168.0.1, 127.0.0.1
| |
| − | | |
| − | | |
| − | '''Step 4: Create the invite code '''
| |
| − | | |
| − | Click the Generate invite code button. You will now see the code listed in the table. Copy this code and give it to the third party.
| |
| − | | |
| − | = Scopes =
| |
| − | Each category of API endpoint (except /authentication) requires a corresponding scope to access.
| |
| − | | |
| − | bookings
| |
| − | bookings-personal
| |
| − | bookings-financial
| |
| − | inventory
| |
| − | properties
| |
| − | accounts
| |
| − | channel
| |
| − | | |
| − | | |
| − | Some categories have additional scopes that allow access to personal or financial information. For example, the "bookings" scope would grant access to a booking's basic information such as the check-in and checkout dates. To access personal information such as the name of a guest, the "bookings-personal" scope would be required. Similarly, to access the invoice of a bookings, the "bookings-financial" scope would be required.
| |
| − | | |
| − | Each scope must also have an accompanying method. For example "read:bookings" would grant read access to bookings, but in order to create a new booking "write:bookings" would be required.
| |
| − | | |
| − | The "all" method may be used as a shortcut to grant access to all methods. For example "all:bookings" would allow for the reading, updating, creating and deleting of bookings.
| |
| − | | |
| − | = POST requests =
| |
| − | == Creating/modifying multiple items ==
| |
| − | All POST endpoints accept an array of items (an item may be a booking, message, property etc).
| |
| − | | |
| − | It is possible to create and modify multiple different items in one request this way.
| |
| − | | |
| − | All existing "POSTable" items will have an "id" field to uniquely identify it.
| |
| − | * To create a new item, just do not include an id.
| |
| − | * To modify an existing item, include its id.
| |
| − | | |
| − | == Subitems ==
| |
| − | Some items can contain subitems. For example, a booking may contain an "invoice item" and an "info item".
| |
| − | | |
| − | Subitems generally work in the same way as their parent items.
| |
| − | | |
| − | Deleting a subitem requires the WRITE scope method, deleting a subitem's parent item requires the DELETE scope method.
| |
| − | | |
| − | '''To add a new subitem to an item, include the subitem without an id.'''
| |
| − | | |
| − | '''''Example: add a new info item to a booking:'''''
| |
| − | [
| |
| − | {
| |
| − | "id": {bookingId},
| |
| − | "infoItems": [
| |
| − | {
| |
| − | "code": "this will create",
| |
| − | "text": "a new info item"
| |
| − | }
| |
| − | ]
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | '''To update an existing subitem, include the subitem's id.'''
| |
| − | | |
| − | '''''Example: update a booking's info item:'''''
| |
| − | [
| |
| − | {
| |
| − | "id": {bookingId},
| |
| − | "infoItems": [
| |
| − | {
| |
| − | "id": {infoItemId},
| |
| − | "text": "this info item will have its text changed"
| |
| − | }
| |
| − | ]
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | '''To delete a subitem, include only the subitem's id.'''
| |
| − | | |
| − | '''''Example: delete a booking's info item:'''''
| |
| − | [
| |
| − | {
| |
| − | "id": {bookingId},
| |
| − | "infoItems": [
| |
| − | {
| |
| − | "id": {infoItemId},
| |
| − | }
| |
| − | ]
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | == Responses ==
| |
| − | All POST requests will have a standard response.
| |
| − | | |
| − | === Structure ===
| |
| − | Responses will be an array containing a number of response items equal to the number of items in the request.
| |
| − | | |
| − | Each response item will contain a "success" boolean field. Success will be false if there were any errors in processing the item.
| |
| − | Note: Success being false does not necessarily mean that nothing has changed.
| |
| − | E.g. if a valid booking with an invalid info item is posted, the booking will be created but the info item will not. Success will be false in this case because there was an error.
| |
| − | | |
| − | A response item may also contain one or more of the following:
| |
| − | *New - contains information about newly created items and subitems. For example, the id of a newly created booking, or the id of a new info item for an existing booking.
| |
| − | *Modified - contains information about modified items and subitems. For example, if the departure date of a booking is changed, this field will have information confirming this change.
| |
| − | *Errors - Contains information about fatal issues with an item or subitem in the request. An error means that an attempt was made to create or change an item or subitem, but that attempt failed.
| |
| − | *Warnings - Contains information about non-fatal issues with an item in the request. A warning means that an item or subitem was created or changed, but, for example, a non-required field had invalid data provided.
| |
| − | *Info - Contains general information about what has happened to the request.
| |
| − | | |
| − | === Order of response items ===
| |
| − | The order of the items in the response will correspond to the order that items were sent in the request.
| |
| − | | |
| − | '''''Example: POST two message for different bookings:'''''
| |
| − | [
| |
| − | {
| |
| − | "bookingId": 1111111,
| |
| − | "message": "a message"
| |
| − | },
| |
| − | {
| |
| − | "bookingId": 2222222,
| |
| − | "message": "a different message"
| |
| − | },
| |
| − | ]
| |
| − | | |
| − | '''''Example: response order for the above request:'''''
| |
| − | [
| |
| − | {
| |
| − | "success": true,
| |
| − | "info": [
| |
| − | {
| |
| − | "message": "information about the message for booking 1111111"
| |
| − | }
| |
| − | ]
| |
| − | },
| |
| − | {
| |
| − | "success": false,
| |
| − | "errors": [
| |
| − | {
| |
| − | "message": "an error about the message for booking 2222222"
| |
| − | }
| |
| − | ]
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | = Examples =
| |
| − | == Authentication ==
| |
| − | === Refreshing a token ===
| |
| − | Request:
| |
| − | <nowiki>curl -X 'GET' \
| |
| − | 'https://api.example.com/v2/authentication/token' \
| |
| − | -H 'accept: application/json' \
| |
| − | -H 'refreshToken: Ea6DftE50aYYRe/qAd9SkQaSmTF6kaLQxH6gtRxO1h10yVC64d4qIj4BGiQOU+y5'</nowiki>
| |
| − | | |
| − | Response:
| |
| − | <nowiki>{
| |
| − | "token": "wEoJHQIwRrLwHqTqAsn0/XjzaZkVk4E8sSDwbRN2HKDlulkt6n7aHQCcvdqfX+y5",
| |
| − | "expiresIn": 3600
| |
| − | }</nowiki>
| |
