Alcances y el header X-Property

Dos permisos separados deciden si una llamada tiene éxito: qué puede hacer la
key (los alcances) y dónde puede hacerlo (la lista de propiedades).

Los once alcances

Una key tiene un subconjunto. Un alcance faltante es un 403 y — cosa poco
habitual — el mensaje nombra el alcance que faltaba:

{
  "message": "This API key does not have the required scope: bookings:read",
  "error_code": "APIKEY_SCOPE_MISSING"
}

Eso es deliberadamente más útil que las
fallas de credencial,
porque quien llama ya demostró quién es.

bookings:read no es un alcance de "información pública". Devuelve los
datos de contacto del huésped. Esas respuestas hay que tratarlas como datos
personales.

bookings:read lee lo que esta key creó, y nada más

GET /bookings y GET /bookings/{booking} devuelven únicamente las reservas
creadas por la key que hace la llamada. Una reserva creada por otra key, o
por el hotel desde su propio panel, responde 404 BOOKING_NOT_FOUND — el mismo
código que una que no existe, y por la misma razón que arriba: distinguirlas
confirmaría que el id es real.

Eso acota lo que una key filtrada puede leer. Antes, bookings:read paginaba
todas las reservas de la propiedad con el nombre, el correo, el teléfono y
el documento de cada huésped.

bookings:read:all recupera esa vista completa, y se concede a propósito —
una integración de reporting o un channel manager sí la necesitan. Es
aditiva: la key necesita bookings:read para llegar al endpoint, y
bookings:read:all encima para verlo todo. Una key que sólo tenga
bookings:read:all recibe 403 APIKEY_SCOPE_MISSING.

bookings:read:all ensancha la LECTURA, nunca la escritura. Aunque la key
vea toda la propiedad, confirm y cancel siguen operando sólo sobre las
reservas que esa key creó. Una reserva ajena responde 404, y no se toca.

Vender y cancelar son alcances distintos

bookings:cancel está separado de bookings:write a propósito: una key emitida
para vender habitaciones no debería poder cancelar las del hotel. Si tu
integración sólo crea reservas, no pidas el segundo.

GET /health no requiere alcance alguno.

El header X-Property

Que haya que mandarlo depende de cuántas propiedades cubre la key, y la regla es
lo contrario de lo que la gente suele suponer.

Una key acotada a exactamente una propiedad no debe mandarlo. La propiedad se
infiere. El motor de reservas de un solo hotel no debería tener que nombrar su
propio hotel en cada llamada. Si manda el header de todos modos y el valor no
coincide con la propiedad de la key, la respuesta es 404.

Una key acotada a varias tiene que mandarlo en toda llamada atada a una
propiedad. Omitirlo es:

{ "message": "…", "error_code": "PROPERTY_NOT_IDENTIFIED" }

422.

Una propiedad fuera de la lista de la key y una propiedad que no existe se
responden igual — 404 PROPERTY_NOT_FOUND. Un código distinto para la primera
confirmaría que el id pertenece a la cuenta de otro, que es justamente el hecho
que el 404 existe para esconder.

Un header vacío (X-Property:) se trata como ausente, no como una petición
por la propiedad cuyo id es la cadena vacía.

Encontrar el id

GET /properties lista todas las propiedades que
cubre la key. Hay que llamarlo primero — una key de varias propiedades necesita
el id de ahí en todas las demás llamadas.

Ya que se está ahí, conviene revisar api_rate_plans_configured. Cuando está en
false, la propiedad no tiene ningún plan tarifario activo del canal api, y
/units, /availability y /rates van a volver vacíos legítimamente. Solo el
hotel puede cambiar eso — ver
Planes tarifarios.

Relacionado

• Autenticación y API keys — qué es una key.
• Errores — los códigos de arriba, en contexto.