Emitir API keys

Este es el lado del hotel de la External API. Vive en
Integraciones → API keys, con Registro de peticiones al lado.

Las dos secciones están restringidas al dueño del tenant o a un usuario admin.
Para cualquier otro no están en gris — están ausentes, con una línea que dice
quién las administra.

Una key es una credencial con cuatro límites

Una key es lo que usa un sistema externo — un motor de reservas, un sitio socio,
software propio — para alcanzar tu hotel. Lleva:

Más una expiración opcional.

Emitir una

Nueva key pide un nombre, los alcances, el alcance real y los límites.

El nombre es para uno — nunca sale de esta lista. Conviene usar el nombre del
sistema que la va a usar ("Motor de reservas", "Sitio socio"), porque eso es lo
que hace reconocible una fila un año después.

Alcances

Se marcan de a uno y no hay un alcance de "todo". Una key que puede hacer
todo tiene los ocho explícitamente, lo que significa que un alcance agregado a la
API más adelante nunca ensancha una key que ya existe. Ese es el punto
entero: tus integraciones no ganan capacidades en silencio cuando el producto
crece.

Crear y leer reservas están separados a propósito. Un motor de reservas que solo
coloca reservas no necesita leer las de otros — y leer una reserva devuelve los
datos de contacto del huésped, así que eso son datos personales, no información
de catálogo.

Por lo mismo, leer reservas quedó acotado a las que creó esa misma key. Una
integración ve su propio trabajo y nada más. Leer todas las reservas de la
propiedad existe para los casos que de verdad lo necesitan — un reporting, un
channel manager — y hay que marcarlo a sabiendas: es el alcance que, si esa key
se filtra, entrega la agenda de huéspedes completa de la propiedad.

Cancelar también es su propio alcance. Una key emitida para vender no debería
poder cancelar lo que vendió el hotel.

Alcance real

Se eligen las propiedades sobre las que la key puede actuar. Sin ninguna
marcada, la key alcanza todas las propiedades del tenant, incluidas las que uno
cree después.

La elección cambia cómo tiene que llamarte quien integra:

• Una propiedad → no deben mandar header X-Property. Se infiere, y
  mandar un id distinto responde 404.
• Varias → tienen que mandarlo en toda llamada atada a una propiedad.

Si uno está emitiendo una key para el motor de reservas de un solo hotel, conviene
acotarla a esa propiedad. Es una cosa menos que quien integra puede equivocar, y
una propiedad menos expuesta si la key se filtra.

Límite de peticiones y expiración

El límite de peticiones es por minuto, y un número por encima del tope nunca
se aplicó — el límite por IP lo acota igual. El valor por defecto alcanza para un
motor de reservas; hay que subirlo solo cuando una integración real lo pida.

La expiración es opcional. Vacío significa sin expiración; una fecha tiene que
ser de mañana en adelante. Una key que expira vale la pena para una integración
temporal — una migración, una prueba con una agencia — precisamente porque nadie
se acuerda de revocar esas.

Techos de inventario

El límite de peticiones no protege tu calendario. A 60 llamadas por minuto se
puede tapizar el libro de un hotel en una tarde sin excederlo nunca, porque
cuenta peticiones y no habitaciones.

Por eso cada key lleva además dos topes:

Al toparlos, la integración recibe un 429 que le dice cuál techo fue y cuánto
le queda. Los dos se pueden subir para una key en concreto sin subírselos a
todas — que es el punto de tenerlos por key.

Si los dejas vacíos, la key usa el valor de la plataforma en el momento de cada
comprobación, no el que había el día que la emitiste. Si mañana bajamos el
valor por defecto, tus keys sin número propio bajan con él.

La key se muestra una sola vez

Después de crearla, el texto de la key se muestra una vez. Hay que copiarlo en
ese momento y guardarlo donde la integración lo vaya a usar.

El servidor solo guarda un hash. Ni soporte ni un admin pueden volver a
mostrarlo. Si se pierde, se emite otra y se revoca la vieja.

El ciclo de vida

Pausar es la reversible — sirve cuando una integración se está portando mal y
uno quiere que pare ya mientras averigua por qué.

Revocar no se puede deshacer. Cualquier integración que use esa key deja de
funcionar de inmediato, y la key no se puede reactivar — se emite una nueva. Es lo
que hay que usar cuando una key se filtró.

Revocar y anular. Cuando una key se filtró, cortarla no alcanza: lo que ya
creó sigue ocupando tu calendario. Revocar y anular hace las dos cosas —
mata la key y cancela todo lo que creó desde la fecha que le indiques.

Primero te dice cuánto va a tocar. Antes de anular nada te muestra cuántas
reservas, cuántas noches y qué propiedades entran. Hay que leer ese número: no
todo lo que creó una key comprometida es falso, y un huésped real puede
aparecerse en recepción. Si la fecha que elegiste barre demasiado, se acota y se
vuelve a mirar.

Las reservas anuladas no le mandan nada al huésped y no cuentan como
cancelaciones suyas ni en sus estadísticas ni en tus reportes.

Las keys revocadas se quedan en la lista. La fila es la historia de lo que
hizo esa credencial, y borrarla borraría la respuesta a "¿qué estaba haciendo esta
key en marzo?".

Editar una key cambia qué puede hacer y hasta dónde llega. Nunca cambia el texto
de la key, así que una integración sigue funcionando a través de un cambio de
alcance sin tener que volver a desplegarse.

Registro de peticiones

Cada llamada que hicieron tus integraciones, la más nueva primero.

Cubre todo el tenant y no cambia con la propiedad seleccionada arriba — una
key puede alcanzar varias propiedades, así que un registro acotado a una propiedad
escondería la mitad de lo que hizo esa key.

Las fechas y horas son UTC, no el reloj de la propiedad. Eso es lo contrario
de todas las demás pantallas de Axis Pro, y es deliberado: quien integra leyendo
sus propios logs está leyendo UTC, y los dos tienen que alinearse para ser
comparables.

Se guardan los últimos 90 días.

Se filtra por key, estado, método, ruta, rango de fechas, una búsqueda sobre la
ruta, y solo errores — que es el filtro que uno de verdad va a usar.

La columna que se gana su lugar es Diagnóstico. Un 422 por sí solo no le
dice nada a quien integra; esta dice qué campos se rechazaron, o que no se cumplió
una estadía mínima, o cuántas habitaciones quedaban contra cuántas se pidieron, o
que se llegó al límite de peticiones. Es lo que permite responderle a un "su API
rechazó mi llamada" sin pedirle que lo reproduzca.

Cada key tiene además su propia vista de uso: peticiones totales, fallas, tasa de
falla y peticiones por día. Una tasa de falla que sube en una key y no en las
otras es una integración que se rompió, no una API que lo hizo.

Qué entregarle a quien integra

Tres cosas, y solo la primera es un secreto:

1. La key, por un canal que uno usaría para una contraseña. No correo.
2. Para qué ambiente es la key. Una key sirve en un solo ambiente — a una de
   sandbox producción la rechaza, y al revés igual. Los dos hosts están publicados
   en la referencia, con un interruptor entre ellos, así que quien integra
   necesita saber a cuál pertenece esta key.
3. Si la key cubre una propiedad o varias, para que sepan si tienen que mandar
   X-Property.

Conviene apuntarlos al Inicio rápido. Los lleva de la key a
una reserva en cinco llamadas.

Antes de culpar a la API

Una habitación que se ve en las pantallas propias puede estar ausente en la
API. Una unidad solo se expone si está publicada, no bloqueada para la venta, y
tiene al menos un plan tarifario activo en el canal de venta api. Esa última
condición es la respuesta casi siempre, y solo uno puede cambiarla — ver
Planes tarifarios.

GET /properties devuelve api_rate_plans_configured precisamente para que quien
integra pueda distinguir eso de un bug de su lado.