ChatBedsDesenvolvedores
Apps e OAuth

Esta página ainda não foi traduzida, então você está lendo a versão em inglês.

Scopes

The permissions an app can ask for, what the hotel sees for each, and which operations each one unlocks.

Scopes limit what an app token may do. You choose the most your app may ask for when you register it; each authorize request asks for those or fewer; the hotel sees each one in plain words and allows them together.

API keys made by hand on Settings → Partner API have no scopes: they can do everything at their property.

The scopes

ScopeWhat the hotel seesOperations it unlocks
property:readSee the property's details, policies and what it offersGET /properties, GET /properties/{id}/policies, GET /properties/{id}/booking-rules
rooms:readSee room types, rooms, rate plans and extrasGET /properties/{id}/room-types, /rate-plans, /units, /extras
availability:readSearch availability and pricesGET /properties/{id}/offers
reservations:readSee bookingsGET /reservations/{id}, GET /properties/{id}/reservations, GET /reservations/{id}/cancellation-quote, GET /properties/{id}/arrivals, /departures, /in-house, and booking webhooks
reservations:writeMake, change and cancel bookingsPOST /properties/{id}/reservations, PATCH /reservations/{id} (dates, guests, room type, rate plan; ?dry_run=true to preview), POST /reservations/{id}/cancel, POST /reservations/{id}/extras
folios:readSee guests' bills and paymentsGET /reservations/{id}/folio, GET /payments/{id}, and payment webhooks
folios:writeAdd charges and record payments on billsPOST /reservations/{id}/folio/charges, POST /reservations/{id}/folio/payments, POST /reservations/{id}/folio/lines/{line_id}/complimentary, and giving an extra free (POST /reservations/{id}/extras with complimentary)
payments:writeCreate card payment links on the hotel's Stripe accountPOST /reservations/{id}/payment-link, POST /payment-links (several bookings, one page), POST /payments/{id}/void, and payment webhooks
frontdesk:writeCheck guests in and out, and mark no-showsPOST /reservations/{id}/check-in, /check-out, /no-show
guests:readSee guest profilesGET /guests, GET /guests/{id}
guests:writeAdd and change guest profilesPOST /guests, PATCH /guests/{id}
rates:readSee prices and restrictions by dateGET /properties/{id}/rates
rates:writeChange prices and restrictions (closed, minimum and maximum stay)POST /properties/{id}/rates, POST /properties/{id}/rates/range
extras:writeAdd, change and take extras off salePOST /properties/{id}/extras, PATCH /extras/{id}, DELETE /extras/{id}
policies:writeChange cancellation policies and booking rules (deposit, children, pets, check-in times)POST /properties/{id}/cancellation-policies, PATCH and DELETE /cancellation-policies/{id}, PATCH /properties/{id}/booking-rules, PATCH /rate-plans/{id}/rules
negotiation:readSee the private offers your app asked forGET /properties/{id}/negotiation, GET /properties/{id}/negotiations, GET /negotiations/{id}
negotiation:writeAsk for private offers inside the hotel's limits, counter, and book the agreed onePOST /properties/{id}/negotiations, POST /negotiations/{id}/counter, /book, /decline

GET /me and GET /capabilities need no scope. Every connected app can call them.

When you tick scopes on the Developers page, each checkbox shows the endpoints it opens. GET /api/v1/developer/catalogue gives the same list: every scope with its endpoints, and every webhook event.

Write doesn't include read

Each scope stands alone. An app that books with reservations:write and then reads the booking back needs reservations:read as well. The same goes for folios:write and folios:read.

Webhooks need a scope

EventsNeed one of
reservation.*reservations:read
payment.*folios:read or payments:write
folio.updatedfolios:read

A connection receives an event only if the hotel allowed the scope it needs. Without it, nothing is sent to your webhook address for that property, even if the address is set. Payment events are also off until you turn them on; you can turn them on only if your app has folios:read or payments:write.

A missing scope

Calling an operation the hotel didn't allow answers 403. Nothing is done.

403 Forbidden
{
  "detail": "This connection was not allowed 'reservations:write'. Ask the hotel to connect the app again with that scope."
}

To get a scope you don't have:

  1. Make sure it is ticked on your app. If your app is Listed, adding a scope sends it back to review; existing connections keep working meanwhile.
  2. Send the hotel through the consent page again, asking for the new scope. The hotel picks the same property and sees it as already connected; allowing again updates what your app may do there.

The scope field of every token response tells you exactly what the connection may do. Check it rather than assuming.

Ask for the fewest

Hotels see every scope you ask for before they press Allow, and reviewers check that each one is needed.

You're buildingYou probably need
A booking site or channelproperty:read, rooms:read, availability:read, reservations:read, reservations:write
A channel manager or PMS syncrooms:read, availability:read, reservations:read, reservations:write
A guest messaging toolproperty:read, reservations:read
An accounting exportreservations:read, folios:read
A payments toolreservations:read, folios:read, folios:write, payments:write

Ask for a scope when a feature needs it, not in case it might.

Criando algo?

Nesta página