Referencia de la API
Conecta tu software a las puertas de AI360
Da acceso a tus huéspedes, abre en remoto y consulta quién entró y cuándo, desde tu propio sistema. Esta guía cubre la autenticación, cada endpoint y los códigos de error de la versión 2.0.
Cómo funciona
Conectas tu software a una cuenta de AI360 y, a partir de ahí, puede dar acceso a las puertas y abrirlas en remoto.
location
Localización
Un inmueble o edificio: un apartamento, un hotel, una oficina. Tu cuenta tiene que ser administradora de la localización para gestionarla desde la API.
room
Sala
Un espacio dentro de una localización, como "Apartamento 3B" o "Entrada principal". El acceso siempre se da por sala.
device
Dispositivo
El hardware instalado en una sala: una cerradura, un controlador, un hub. Son los que abren la puerta.
invitation
Invitación
El permiso para que una persona abra los dispositivos de una sala. Puede valer siempre, entre dos fechas (ocasional) o unos días y horas concretos (habitual).
invitation link
Enlace de invitación
Un enlace público que el huésped abre en su móvil para abrir la puerta, sin app ni cuenta. Puede agrupar varias invitaciones, como el portal y el apartamento.
activity
Actividad
El registro de lo que ha pasado: quién abrió qué puerta y cuándo.
Una integración típica
Los pasos que sigue la mayoría de los PMS y gestores al conectarse.
- Conecta. Consigue tu Client ID y tu Client Secret y deja que el propietario de la cuenta autorice tu app con OAuth 2.0. Recibirás un access token que envías en cada petición.
- Mapea tus salas. Lista las salas para obtener el uid de cada sala y de sus dispositivos, y enlázalas con los inmuebles de tu sistema.
- Da acceso. Cuando un huésped reserva, crea una invitación para su sala y sus fechas. AI360 puede enviársela por email, o devolverte un enlace público que le envías tú (incluso a un huésped anónimo, sin email).
- Agrupa puertas. Si el huésped necesita varias puertas, junta sus invitaciones en un único enlace de invitación.
- Opera (opcional). Abre una puerta desde tu sistema, comprueba que los dispositivos están en línea y consulta la actividad.
Credenciales de desarrollador
Para usar la API necesitas una cuenta de desarrollador. El acceso está restringido: una vez aprobado, verás tu cuenta en developers.ai360access.com y tu Client ID y Client Secret en developers.ai360access.com/dev-oauth.
Autenticación OAuth 2.0
Usamos OAuth 2 con el flujo Authorization Code.
Direcciones
https://api.ai360access.com/o/authorizehttps://api.ai360access.com/o/token/Scopes
GET)Cada endpoint pide read o write según el método, más el scope del recurso. Un token sin ellos se rechaza con HTTP 403 y el error 3013.
- Llama al endpoint de autorización. El usuario inicia sesión y concede permisos, y volvemos a tu
redirect_uricon elcode. - Cambia el código por un access token y un refresh token en el endpoint de token (
grant_type=authorization_code). - Cuando caduque el access token, renuévalo con el refresh token (
grant_type=refresh_token). - Envía el access token en la cabecera
Authorizationde todos los endpoints/2.0/.
Si el access token falta, no es válido o ha caducado, los endpoints /2.0/ responden HTTP 401 con el cuerpo vacío {}. Renueva el token y vuelve a intentarlo.
Licencias
La API solo funciona en localizaciones con una licencia de API activa, una por localización. En cualquier otra, la petición devuelve 3016 y los listados no incluyen la localización. Pide a tu asesor de AI360 que la active.
Códigos de error
Todos los errores se devuelven con HTTP 400 (403 para el 3013) y esta estructura. El texto de error_info llega siempre en inglés, tal cual aparece en la tabla.