El inventario exacto de endpoints, tipos de evento y alcances se comparte con integradores contra el runtime que van a llamar — crece con el producto, así que no congelamos un número aquí.
REST versionada en /api/public/pms/v1
La especificación se genera de las rutas que el runtime realmente sirve, y un gate de paridad tumba el build cuando ruta y documentación no coinciden.
- OpenAPI
- Publicada por el propio runtime, no mantenida a mano en paralelo.
- Versionado
- La versión es parte de la ruta. Un cambio que rompe crea una versión nueva; la anterior sigue respondiendo.
- Recursos
- Establecimientos, reservas, huéspedes, folios, pagos, POS, limpieza, mantenimiento, dato financiero e impuesto.
- Formatos
- JSON de entrada y de salida. Los importes son enteros en unidades menores, con la moneda declarada.
OAuth 2.0 client credentials
La credencial se emite dentro del producto, por alguien que ya ve el dato que va a leer. No hay registro self-service público.
- Grant
- client_credentials. El token es opaco y expira en una hora.
- Secreto
- Se muestra una vez, se guarda como hash y no es recuperable por diseño.
- Rotación
- Genere un secreto nuevo y el anterior sigue válido 24 horas, para que el socio cambie sin downtime.
- Revocación
- Suspenda o revoque la credencial y todo token emitido con ella deja de funcionar.
Dos preguntas, dos mecanismos
“¿Este client puede leer reservas?” es alcance. “¿Puede leer reservas de ESTE establecimiento?” es concesión. Confundirlas es como un socio termina viendo toda la red.
- Alcances
- Por recurso y por operación, separados entre lectura y escritura. Un alcance desconocido se niega, nunca se ignora.
- Concesión por establecimiento
- Explícita por hotel. Ninguna concesión significa ningún hotel — nunca “todos”.
- Tenant
- Viene del token. No hay parámetro de tenant en la API para equivocarse.
- Negativas
- Motivos estables y distinguibles: alcance negado, establecimiento negado, establecimiento obligatorio.
Lectura incremental que no pierde filas
Un cursor solo de timestamp se rompe en cuanto dos hechos comparten el mismo milisegundo. El nuestro lleva también el identificador, así que el corte dentro de un mismo instante sigue siendo exacto.
- updatedSince
- Pida lo que cambió desde su última lectura exitosa.
- Cursor compuesto
- Ordenado por instante e identificador, así el corte dentro de un instante no pierde ni duplica nada.
- Cursor ilegible
- Responde con error, nunca reinicia en silencio desde la primera página.
- Errores estables
- Cursor, timestamp, fecha operativa e identificador inválidos tienen cada uno su código público. Un error de base de datos nunca cruza la frontera.
Entrega firmada, con los estados de fallo visibles
Los hechos operativos se empujan a medida que ocurren. Lo que importa del lado que recibe no es el camino feliz — es saber exactamente qué se entregó y de qué se desistió.
- Firma
- HMAC-SHA256 sobre el timestamp y el cuerpo crudo, enviado como t=<unix>,v1=<hmac>, con tolerancia de 300 segundos. El material exacto está en la especificación.
- Protección contra reenvío
- Una firma capturada en tránsito no puede reenviarse después como si fuera nueva.
- Reentrega
- Reentrega automática con backoff, reentrega manual bajo demanda y un estado de abandono que usted ve.
- Seguridad del destino
- El destino se valida en cada intento, incluso tras la resolución de DNS, para que un endpoint no apunte a la infraestructura interna.
- Registro de entrega
- Cada intento, código de respuesta y desenlace, por endpoint.
Reintente con seguridad, y conozca su cuota
Una integración que no puede reintentar es una integración que duplica. Las escrituras son idempotentes y la cuota se comparte entre réplicas.
- Idempotencia
- Envíe una clave en la escritura y la repetición devuelve el resultado original. La misma clave con cuerpo distinto se rechaza, no se acepta en silencio.
- Rate limit
- Por credencial, contado en almacenamiento compartido para que las réplicas no concedan la cuota entera cada una. Las cabeceras llevan límite, resto y reset.
- Modo degradado
- Si el conteo compartido cae, el límite degrada a uno local más débil — y la respuesta lo dice en una cabecera, en vez de fingir.
- Errores
- Un código público estable y un mensaje humano. Sin identificador interno, sin stack trace.
Lo que la API se niega a hacer
Algunas garantías se expresan mejor como negativas — no se pueden desconfigurar.
- Sin dato de tarjeta
- El número de tarjeta y el código de seguridad se rechazan en la frontera. La API nunca se convierte en un lugar donde podrían guardarse.
- Sin lectura cruzada
- Una petición fuera de los establecimientos concedidos se niega con motivo propio, no se filtra a una lista vacía.
- Sin filtrar lo interno
- Los errores de base de datos e infraestructura se traducen antes de llegar al cliente.
- Traza de auditoría
- El ciclo de vida de la credencial y la actividad de la API se registran contra una taxonomía validada.
Cómo empezar
Cuatro pasos, todos dentro del producto. Nada de esto es self-service en el sitio público.
- Cree una credencialEn el PMS, en Integraciones y API. El secreto se muestra una sola vez.
- Conceda alcances y establecimientosSolo los recursos y los hoteles que esta integración necesita.
- Obtenga un tokenCambie la credencial por un token de acceso de una hora.
- Lea la especificaciónEl documento OpenAPI describe cada endpoint, payload y error que puede recibir.
Límites honestos
- No hay portal público de desarrollador ni registro de sandbox — la credencial se emite dentro del producto.
- La entrega de eventos es webhook HTTP; no existe stream por WebSocket.
- No hay marketplace de conectores de socios para descargar ni conectores certificados.
- La madurez actual apunta a un piloto controlado, no a un despliegue global.
¿Construyendo una integración?
Cuéntenos qué necesita leer o escribir. Compartimos la especificación y el alcance de credencial que corresponde.