|
|
| (92 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 Access=
| |
| − | To use the API you need to allow API ACCESS.
| |
| − | Go to SETTINGS -> ACCOUNT -> ACCOUNT ACCESS and allow API access.
| |
| − | *The JSON functions can be created with a API and prop key which you set yourself in the Beds24 control panel {#fas:cog}} (SETTINGS)ACCOUNT and {{#fas:cog}} (SETTINGS) PROPERTIES > ACCESS
| |
| − | | |
| − | = Tokens =
| |
| − | | |
| − | = Scopes =
| |
| − | Each category of API endpoint (except /authentication) requires the corrosponding scope to access.
| |
| − | | |
| − | 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 acompanying method. For example "get:bookings" would grant read access to bookings, but in order to create a new booking "post: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 method =
| |
| − | == 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.
| |
| − | | |
| − | '''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" field, and may contain a "modified", "errors", "warnings" or "info" field (these are not mutually exclusive).
| |
| − | | |
| − | ==== 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"
| |
| − | }
| |
| − | ]
| |
| − | }
| |
| − | ]
| |
| − | | |
| − | ====The "new" field====
| |
| − | | |
| − | = 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>
| |
