323
edits
Changes
Jump to navigation
Jump to search
To get price setup rules, include the "includePriceRules" parameter in GET === POST /properties like this bookings/api/v2/properties?includePriceRulesmessages ===true
A room can have up to 16 pricesSend messages or mark them as read.
In the control panel, these can be set under Prices -> Daily Price Setup.=== PATCH /bookings/messages ===
In Make changes in all messages in a selection. === GET /bookings/invoices === Get invoices for bookings. == Inventory == === GET /inventory/rooms/offers === Get offer based on specified criteria. === GET /inventory/rooms/availability === Get the availability status of dates. === GET /inventory/rooms/calendar === Get's per day values from the calendar. === POST /inventory/rooms/calendar === Modify per day calendar values. == Properties == === GET /properties === Get properties matching specified criteria. === POST /properties === Create or modify properties. === DELETE /properties === Delete properties by id. === DELETE /properties/rooms === Delete rooms of properties by id. == Accounts == === GET /accounts === Get accounts and sub-accounts. === POST /accounts === Create or modify accounts. == Webhooks == === POST Webhooks - bookings === The webhook payload sent to your URL from the API these booking webhook found here: Settings -> Properties -> Access -> Booking Webhook == Channels - settings == === GET /channels/settings === Get channel specific settings. === POST /channels/settings === Modify channel settings. == Channels - Airbnb == === GET /channels/airbnb/users === Get all Airbnb user ids connected to an account. === GET /channels/airbnb/listings === Get all Airbnb listings for a specified Airbnb user id. === POST /channels/airbnb === Perform actions at Airbnb. == Channels - Booking.com == === POST /channels/booking === Perform actions at Booking.com. === GET /channels/booking/reviews === Get reviews from Booking.com. == Channels - Stripe == You can collect the card directly with Stripe so you do not have any PCI DSS obligations. The procedure would be accessed through GET 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/inventorypayments/calendarcheckout { "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 "calendarbookId": [and any payments to this checkout session will be added to the bookings invoice. { Setting "price1capture": 100false 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. "price2"When initializing Stripe in your App, use this pk_live key and the stripe_account value (acct_) from the session response as follows: 300 <code>var stripe = Stripe('pk_live_zWSW2ykzZoq4mYcKg9c8jmHS',{stripeAccount: 'acct_stripe_acccont-value-from-response' "price3"});</code> See here for more information https: 200,//stripe.com/docs/payments/checkout === POST /channels/stripe === Perform actions at Stripe. === GET /channels/stripe/paymentMethods === Get payment methods for a booking from Stripe. === GET /channels/stripe/charges === Get charges for a booking from Stripe. = Webhooks === Booking webhooks ==To access booking webhooks for API V2 please contact support.They can then be enabled under Settings > Properties > Access > Booking webhooks. }== Other webhooks == Information about other webhooks (including non API V2 webhooks) can be found here [https://wiki.beds24.com/index.php/Category:Webhooks Webhooks] } ]= Best Practices === 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. == 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. == 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. == 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.
= 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.
== Invite codes and refresh tokens == '''Step 1: Get an invite codeor long life token'''
Invite codes and long life tokens can be generated here [https://beds24.com/control3.php?pagetype=apiv2 Invite Codes]
For more information about invite codes, [[API_V2.0#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: Get If using an invite code, get a refresh token using the invite code''' 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''.
<span style="color:#019cde; font-size: 150%;“ >{{#fas:info-circle}} </span> ''Tokens'' generated from refresh tokens expire after 24 hours.
'''Step 3: Use the token to authenticate calls'''
The ''token'' returned in step 2 (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. <span style="color:#019cde; font-size: 150%;“ >{{#fas:info-circle}} </span> ''Tokens'' expire after 24 hours.
'''Step 4: Use the refresh token to generate new tokens'''
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.
== Subcategory scopes ==
]
= Prices Endpoints = == Bookings == === GET /bookings === Get bookings matching specified criteria. === POST /bookings === Create or update bookings. === DELETE /bookings === Delete bookings by id. === GET /bookings/messages === Get messages for a booking.
= Examples =
=FAQ=
==How do I access API V2?==
Create an invite code under Settings -> {{#fas:cog}} (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 [https://beds24.com/api/v2 beds24.com/api/v2] ==How long do invite codes/tokens last?==Invite codes expire after 15 minutes. Refresh tokens last forever so long as they are being used. Unused refresh tokens expire after 30 days. Tokens expire after 24 hours.
==What are scopes?==
Scopes cannot be changed later, you must create a new invite code with the scopes you want and exchange it for a new token.
==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.
==How big are tokens?==
Tokens will be between 152 and 172 characters long.
==What is the API credit limit?==
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.
==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.
==Is the API limited per token or per account?==
This means that tokens under the same account share the same credit limit.
==How do I make a new booking/property/room /booking etc?==
Simply do not include an id in your POST request.
Examples for how to do this can be found here:
[https://beds24.com/api/v2/#/Properties/post_properties Properties/Rooms]
[https://beds24.com/api/v2/#/Bookings/post_bookings Bookings]
==Where can I see or set price rules?==
To retrieve them you must set the includePriceRules parameter to true.
==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.
==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.
==Where can I see examples for how to use the API?==
Examples can be found here [https://beds24.com/api/v2 beds24.com/api/v2].
==Can I use API V2 to send pictures or webhooks?==
Currently no, however these features are coming soon.
==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
}
==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.
==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.]]
