Difference between revisions of "Category:API V2"
(4 intermediate revisions by one other user not shown) | |||
Line 1: | Line 1: | ||
− | [[Category: | + | [[Category:API]] |
− | <div class="heading">API Version 2 | + | <div class="heading">API Version 2</div> |
− | This page explains the capabilities of | + | This page explains the capabilities of API V2 and explains how to use it. |
= Capabilities = | = Capabilities = | ||
Line 604: | Line 604: | ||
==Where can I see the possible values for a booking's apiSourceId (API Source ID)== | ==Where can I see the possible values for a booking's apiSourceId (API Source ID)== | ||
− | [[ | + | [[API_V2.0_apisourceids | apiSourceId values can be found here.]] |
+ | |||
+ | ==I am a PMS or OTA, how can I connect to Beds24?== | ||
+ | Guides for these use cases are available here [[:Category:Connect_PMS_or_OTA | Connect PMS or OTA]] |
Latest revision as of 11:09, 23 October 2024
This page explains the capabilities of API V2 and explains how to use it.
Contents
- 1 Capabilities
- 2 Authentication
- 3 Invite codes
- 4 Scopes
- 5 POST requests
- 6 Endpoints
- 7 Webhooks
- 8 Best Practices
- 9 Examples
- 10 Changelog
- 11 FAQ
- 11.1 How do I access API V2?
- 11.2 What are scopes?
- 11.3 Where are scopes set?
- 11.4 How long do invite codes/tokens last?
- 11.5 How big are tokens?
- 11.6 What is the API credit limit?
- 11.7 Where can I see my API credit limit?
- 11.8 Is the API limited per token or per account?
- 11.9 How do I make a new property/room/booking etc?
- 11.10 Where can I see or set price rules?
- 11.11 Where can I see or set offers?
- 11.12 How can I see or set prices, min stay, availability etc for specific dates like in the UI calendar?
- 11.13 Where can I see examples for how to use the API?
- 11.14 Can I use API V2 to send pictures or webhooks?
- 11.15 How can I see if a date is available for check-in/out?
- 11.16 What is the maximum amount of data I can send in a POST request?
- 11.17 Where can I see the possible values for a booking's apiSourceId (API Source ID)
- 11.18 I am a PMS or OTA, how can I connect to Beds24?
1 Capabilities
API V2 can allow third parties to access your account, properties, bookings and inventory.
More information can be found here beds24.com/api/v2
API V1 is depreciated, we do not recommend using it for new projects. Information about API V1 can be found here https://wiki.beds24.com/index.php/Category:API
2 Authentication
There are two kinds of tokens, long life tokens which have read only access, and refresh tokens which generate tokens that can read and make changes.
To use most API endpoints you will need to include a token header in the format "token: {token}"
2.1 Invite codes and refresh tokens
Step 1: Get an invite code or long life token
Invite codes and long life tokens can be generated here Invite Codes
For more information about invite codes, see here.
This step is the only one that must be done manually, all other steps can be performed and automated programmatically.
Step 2: If using an invite code, get a refresh token
Skip this step if using a long life token
You can use the invite code generated in step one with GET /authentication/setup.
This will return a token and a refresh token.
Tokens generated from refresh tokens expire after 24 hours.
Step 3: Use the token to authenticate calls
The token (either a long life token or a token generated using a refresh token) can be included as a header to authenticate calls to other API endpoints.
Step 4: Use the refresh token to generate new tokens
As tokens expire after 24 hours, you will need to use the refresh token with GET /authentication/token to get new tokens when old ones expire.
Refresh tokens do not expire so long as they have been used within the past 30 days.
3 Invite codes
To grant a third party access to your account, you will need to provide them with an invite code.
3.1 Create a code from a link given to you by a third party
If you are given such a link, most fields will be filled out for you.
You simply need to decide if the third party should be able to access your linked properties.
Click the Generate invite code button and give the code to the third party.
3.2 Create a code to give to a third party
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, 2001:0db8:85a3:0000:0000:8a2e:0370:7334
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.
3.3 Create a link to give to users (as a third party)
If you are a third party who requires invite codes from users, you can give users a link that will prefill the form with the scopes you require selected.
To do this, select the scopes you require then click the button in the bottom left corner to see your customized link.
You can also prefill a whitelisted IP address in the same way
4 Scopes
Each category of API endpoint (except /authentication) requires a corresponding scope to access.
4.1 bookings
The bookings scope provides access to basic information for
GET /bookings POST /bookings
4.2 bookings-personal
The bookings-personal scope provides access to personal information (in addition to the basic information granted by the bookings scope) for
GET /bookings POST /bookings GET /bookings/messages POST /bookings/messages PATCH /bookings/messages
4.3 bookings-financial
The bookings-financial scope provides access to financial information (in addition to the basic information granted by the bookings scope) for
GET /bookings POST /bookings
4.4 inventory
The inventory scope provides access to
GET /inventory/offers GET /inventory/availability GET /inventory/calendar POST /inventory/calendar
4.5 properties
The properties scope provides access to
GET /properties POST /properties
4.6 accounts
The account scope provides access to
GET /accounts POST /accounts
4.7 Linked Properties
Tokens do not provide access to linked properties and their bookings by default.
If you wish to access properties that are not in your account you must tick the "Allow linked properties" checkbox when selecting the scopes for the token.
Note: Properties must be linked under Account Management > Manage Account > Manage Property. Other methods of linking properties are not supported in API V2.
4.8 Subcategory scopes
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.
5 POST requests
5.1 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.
5.2 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}, } ] } ]
5.3 Responses
All POST requests will have a standard response.
5.3.1 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. 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.
5.3.2 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" } ] } ]
6 Endpoints
6.1 Bookings
6.1.1 GET /bookings
Get bookings matching specified criteria.
6.1.2 POST /bookings
Create or update bookings.
How to Add/remove bookings from a group booking
You can add or remove a booking from a group booking by using the parameter "masterId" without having to use the action "makeGroup"
To add a booking to a group booking, you set the master id of the group booking in the "masterId" parameter so it would look like this in your request: "masterId": 1234567, that will modify the booking to add it to the group.
To remove a booking from a group booking, you set the "masterId" parameter to null so it will look like this in your request: "masterId": null,
6.1.3 DELETE /bookings
Delete bookings by id.
6.1.4 GET /bookings/messages
Get messages for a booking.
6.1.5 POST /bookings/messages
Send messages or mark them as read, this endpoint only works for messages for an OTA booking, not bookings made directly from the booking page.
6.1.6 PATCH /bookings/messages
Make changes in all messages in a selection.
6.1.7 GET /bookings/invoices
Get invoices for bookings.
6.2 Inventory
6.2.1 GET /inventory/rooms/offers
Get offer based on specified criteria.
6.2.2 GET /inventory/rooms/availability
Get the availability status of dates.
6.2.3 GET /inventory/rooms/calendar
Get's per day values from the calendar.
6.2.4 POST /inventory/rooms/calendar
Modify per day calendar values.
6.3 Properties
6.3.1 GET /properties
Get properties matching specified criteria.
6.3.1.1 Prices
To get price setup rules, include the "includePriceRules" parameter in GET /properties like this
/api/v2/properties?includePriceRules=true
A room can have up to 16 prices.
In the control panel, these can be set under Prices -> Daily Price Rules.
In the API these can be accessed through GET and POST /inventory/calendar
{ "data": [ { "calendar": [ { "price1": 100, "price2": 300, "price3": 200, ... } ] } ] }
6.3.2 POST /properties
Create or modify properties.
6.3.3 DELETE /properties
Delete properties by id.
6.3.4 DELETE /properties/rooms
Delete rooms of properties by id.
6.4 Accounts
6.4.1 GET /accounts
Get accounts and sub-accounts.
6.4.2 POST /accounts
Create or modify accounts.
6.5 Webhooks
6.5.1 POST Webhooks - bookings
The webhook payload sent to your URL from the booking webhook found here: Settings -> Properties -> Access -> Booking Webhook
6.6 Channels - settings
6.6.1 GET /channels/settings
Get channel specific settings.
6.6.2 POST /channels/settings
Modify channel settings.
6.7 Channels - Airbnb
6.7.1 GET /channels/airbnb/users
Get all Airbnb user ids connected to an account.
6.7.2 GET /channels/airbnb/listings
Get all Airbnb listings for a specified Airbnb user id.
6.7.3 POST /channels/airbnb
Perform actions at Airbnb.
6.8 Channels - Booking.com
6.8.1 POST /channels/booking
Perform actions at Booking.com.
6.8.2 GET /channels/booking/reviews
Get reviews from Booking.com.
6.9 Channels - Stripe
You can collect the card directly with Stripe so you do not have any PCI DSS obligations.
The procedure would be like this:
1) Make the booking via API and get the new Booking ID.
2) Make a call to API V2 POST /channels/stripe with the booking ID and any charges you want to collect. The line_items should be in the Stripe format for their checkout.
https://docs.stripe.com/payments/checkout
3) POST /channels/stripe will return the session data required to instantly create a Stripe payment checkout you can show the booker and they can securely enter their card while on your site.
https://docs.stripe.com/api/checkout/sessions
4) After the booker enters their card, it is automatically connected to the booking ID and can be charged by API or manually from the control panel.
To use the Stripe endpoints, the process is basically the same as creating a normal Strip Checkout session, except by doing it via our API function it connects the payment to the booking.
Use our API to create the Stripe session and then follow Stripes instructions and use the Stripe API or widgets to create a payment checkout for your page.
The Stripe checkout session will create a Stripe checkout page for receiving payments into the properties Stripe account.
Pass the line_items, success_url and cancel_url in the format required by the Stripe API to create a checkout session.
The line_items format is defined in the Stripe documentation
If the booking already exists, pass it's booking ID as "bookId" and any payments to this checkout session will be added to the bookings invoice.
Setting "capture":false will authorize the amount but not collect the funds.
The Stripe session will be returned, the session id can be used to create the Stripe checkout in your App.
When initializing Stripe in your App, use this pk_live key and the stripe_account value (acct_) from the session response as follows:
var stripe = Stripe('pk_live_zWSW2ykzZoq4mYcKg9c8jmHS', {
stripeAccount: 'acct_stripe_acccont-value-from-response'
});
See here for more information https://stripe.com/docs/payments/checkout
6.9.1 POST /channels/stripe
Perform actions at Stripe.
6.9.2 GET /channels/stripe/paymentMethods
Get payment methods for a booking from Stripe.
6.9.3 GET /channels/stripe/charges
Get charges for a booking from Stripe.
7 Webhooks
7.1 Booking webhooks
To access booking webhooks for API V2 please contact support. They can then be enabled under Settings > Properties > Access > Booking webhooks.
7.2 Other webhooks
Information about other webhooks (including non API V2 webhooks) can be found here Webhooks
8 Best Practices
8.1 Token Management
Tokens last 24 hours. This means that you do not need to retrieve a new token for each request. Getting a new token costs credits so it is best to use an existing one when possible.
8.2 Retrieving information at high frequencies
If you need to get data such as new messages or bookings when they come in you do not need to perform frequent GET requests. Instead, you can use webhooks to be notified as soon as a new message/booking etc arrives.
8.3 Sending information at high frequencies
If you need to send large amounts of information such as messages at high frequencies it is best to send them grouped in bulk POST requests instead of sending one request per message. For example, you could send one POST request every 30 seconds containing all messages sent in the past 30 seconds.
8.4 Sending or getting information in one call
If you need to retrieve information about multiple different things, such as information about several properties, you can retrieve that in one call by specifying multiple IDs in the one request instead of performing one GET request per property. The same principle applies when POSTing information, for example, you can create or update multiple properties in one call.
9 Examples
9.1 Authentication
9.1.1 Refreshing a token
Request:
curl -X 'GET' \ 'https://api.example.com/v2/authentication/token' \ -H 'accept: application/json' \ -H 'refreshToken: Ea6DftE50aYYRe/qAd9SkQaSmTF6kaLQxH6gtRxO1h10yVC64d4qIj4BGiQOU+y5'
Response:
{ "token": "wEoJHQIwRrLwHqTqAsn0/XjzaZkVk4E8sSDwbRN2HKDlulkt6n7aHQCcvdqfX+y5", "expiresIn": 3600 }
10 Changelog
The API V2 changelog is available here.
11 FAQ
11.1 How do I access API V2?
Create an invite code under (SETTINGS) Apps & Integrations > API.
Exchange this invite code for a refresh token and token using the POST /authentication/setup endpoint.
Include the token in your requests to authenticate them.
You can try this out using our interactive UI here beds24.com/api/v2.
11.2 What are scopes?
Scopes limit what your token can do.
For example, the read/bookings scope allows your token to retrieve bookings via the API, but if your token does not have the write/bookings scope then it cannot be used to create or modify bookings.
11.3 Where are scopes set?
Scopes are set when you create an invite code.
Scopes cannot be changed later, you must create a new invite code with the scopes you want and exchange it for a new token.
11.4 How long do invite codes/tokens last?
Invite codes expire after 24 hours.
Refresh tokens last forever so long as they are being used. Unused refresh tokens expire after 30 days.
Long life tokens last forever so long as they are being used. Unused long life tokens expire after 90 days.
Tokens generated from refresh tokens expire after 24 hours.
11.5 How big are tokens?
Tokens will be between 152 and 172 characters long.
11.6 What is the API credit limit?
The API credit limit restricts how much you can use the API in a 5 minute window.
Each API request has a cost, this cost is calculated dynamically and depends on how complex the request is.
If you go over this limit you will not be able to make additional API calls until the 5 minute period is over.
11.7 Where can I see my API credit limit?
Information about your credit limit is included in the following API response headers:
- x-five-min-limit-remaining - the number of credits you have left for this 5 minute period.
- x-five-min-limit-resets-in - the number of seconds until the current period resets.
- x-request-cost - the number of credits this request cost.
11.8 Is the API limited per token or per account?
The API credit limits are at the account level.
This means that tokens under the same account share the same credit limit.
Different accounts, including sub accounts, have separate credit limits.
11.9 How do I make a new property/room/booking etc?
Simply do not include an id in your POST request.
Examples for how to do this can be found here:
11.10 Where can I see or set price rules?
Price rules can be found under /properties.
To retrieve them you must set the includePriceRules parameter to true.
11.11 Where can I see or set offers?
Offer setup rules can be found under /properties.
To retrieve them you must set the includeOffers parameter to true.
You can retrieve offers (i.e. calculated prices for specific dates) through the /inventory/rooms/offers endpoint.
11.12 How can I see or set prices, min stay, availability etc for specific dates like in the UI calendar?
These per date values can be read and set through the /inventory/rooms/calendar endpoint.
11.13 Where can I see examples for how to use the API?
Examples can be found here beds24.com/api/v2.
11.14 Can I use API V2 to send pictures or webhooks?
Currently no, however these features are coming soon.
11.15 How can I see if a date is available for check-in/out?
The GET /inventory/rooms/availability returns information about if dates are available or not. If a date is false, it means it is not available for check-in. However, if the previous date is available, it means the date is available for check-out.
For example, with the following a booking cannot check-in on 2024-01-03 because that date is unavailable. However, because the previous date 2024-01-04 is available, it means 2024-01-03 is available for check-out.
"availability": { "2024-01-01": true, "2024-01-02": true, "2024-01-03": false }
11.16 What is the maximum amount of data I can send in a POST request?
The API has a limit of approximately 1MB per POST payload.
In addition, there is a limit of 10000 top level JSON array item per POST request.
11.17 Where can I see the possible values for a booking's apiSourceId (API Source ID)
apiSourceId values can be found here.
11.18 I am a PMS or OTA, how can I connect to Beds24?
Guides for these use cases are available here Connect PMS or OTA
Subcategories
This category has the following 2 subcategories, out of 2 total.
Pages in category "API V2"
The following 6 pages are in this category, out of 6 total. download this selection of articles as a PDF book