API de BAS-IP Link: Cómo integrar el sistema de videoportero y el control de acceso
Un nuevo residente se configura primero en el sistema que el equipo de administración ya utiliza para los apartamentos, los residentes y los datos de contacto. Luego, la misma persona se crea nuevamente, esta vez en el sistema de control de acceso (intercomunicador). Los derechos de acceso cambian: se deben actualizar dos sistemas. El residente se muda: el registro debe eliminarse dos veces.
En un solo sitio, eso es simplemente administración adicional. En una cartera de propiedades con mudanzas regulares, cambios de acceso y pases temporales, se convierte en un proceso de gestión separado que nadie quería en primer lugar.
¿Qué son BAS-IP Link y Link API?
BAS-IP Link es la plataforma centralizada de BAS-IP para gestionar sitios, usuarios, derechos de acceso e infraestructura conectada.
BAS-IP Link API es una API HTTP REST que permite a un sistema del lado del servidor de terceros interactuar con Link de forma programática: transmitiendo datos de usuarios, gestionando derechos y credenciales de acceso, y recuperando datos de la plataforma.
El objetivo no es dar al personal otro sistema en el que trabajar. Todo lo contrario: la plataforma existente del cliente puede seguir siendo la interfaz operativa principal, mientras que BAS-IP pasa a formar parte de los procesos que ya se gestionan allí.
¿Cómo se ve esto en la práctica? Agregar un nuevo residente
La empresa de administración ya conoce el nombre del residente, su apartamento, datos de contacto y otra información relevante. Esos datos ya existen en su propio sistema.
Sin una integración, un miembro del personal tiene que abrir BAS-IP Link y volver a crear al mismo usuario.
Con Link API, ese segundo paso puede automatizarse. El sistema principal transfiere los datos requeridos a Link, el usuario es asignado al sitio y apartamento apropiados, y luego BAS-IP Link trabaja con la infraestructura de acceso e intercomunicación conectada.
El valor práctico no es simplemente que dos sistemas puedan intercambiar datos. Es que el personal no tiene que cambiar la forma en que ya trabaja.
Si las mudanzas, los cambios en los datos de los residentes y las salidas ya se gestionan en la plataforma principal, las mismas acciones no necesitan repetirse manualmente en el sistema de control de acceso.
¿Por qué usar Link API cuando los dispositivos BAS-IP tienen su propia API?
BAS-IP también admite la integración directa con el equipo a través de BAS-IP Device API.
Para un proyecto local, ese puede ser el enfoque correcto. Si un sistema necesita trabajar con uno o varios modelos de dispositivos conocidos y solo requiere un conjunto limitado de funciones, puede que no sea necesaria una capa de servidor adicional.
El requisito cambia a medida que el proyecto escala.
Diferentes edificios pueden usar diferentes paneles de entrada, monitores interiores y otros dispositivos. Se introducen nuevos modelos y versiones de firmware con el tiempo. Con una integración directa de dispositivos, el equipo de desarrollo de terceros debe tener en cuenta las características del equipo con el que se está integrando.
BAS-IP Link añade una capa de software centralizada entre la plataforma de terceros y la infraestructura de control de acceso.
En lugar de construir su lógica de negocio en torno a un panel de entrada particular, la plataforma externa trabaja con el modelo central de Link de usuarios, sitios, apartamentos, derechos de acceso y otras entidades.
Ese suele ser un modelo más natural para una plataforma de gestión de propiedades residenciales. Por lo general, no necesita saber qué panel de entrada exacto está instalado en una puerta en particular. Necesita saber que un residente particular pertenece a un apartamento particular y debe tener acceso a las áreas apropiadas.
BAS-IP Link conecta esa lógica de negocio con la infraestructura física de control de acceso e intercomunicación.
¿Qué se puede hacer a través de BAS-IP Link API?
Una integración particular normalmente utilizará solo una parte de la funcionalidad disponible en Link.
A través de la API, un sistema de terceros puede trabajar con:
- usuarios y estructura del sitio;
- derechos de acceso;
- credenciales de acceso permanentes y temporales, incluyendo tarjetas, llaveros, códigos PIN, códigos QR, Face ID, UKEY y números de matrícula de vehículos;
- acceso de invitados y visitantes;
- mensajes y encuestas;
- números virtuales y desvío de llamadas;
- configuración remota de dispositivos;
- eventos y registros.
Sin embargo, un proyecto de integración suele definirse mejor por una pregunta diferente a «¿Qué métodos API están disponibles?».
¿Qué tareas se realizan manualmente en la actualidad y cuáles de ellas deberían ocurrir automáticamente una vez que los sistemas estén integrados?
Para una plataforma, el caso de uso principal puede ser la gestión de residentes. Para otra, puede ser el acceso temporal de contratistas. Una tercera puede necesitar principalmente datos de eventos.
Gestión de todo el ciclo de vida del usuario, no solo de la creación de usuarios
La creación de un usuario es solo el primer paso.
Una vez que se ha añadido a un residente, se pueden asignar los derechos de acceso y las credenciales apropiadas. Si el residente se muda a otro apartamento, cambia de vehículo, recibe permisos adicionales o pierde el acceso, esos cambios también pueden formar parte del flujo de trabajo en la plataforma principal.
El mismo principio se aplica a los usuarios temporales.
Si un sistema existente ya gestiona visitantes, contratistas o personal de servicio, no hay necesidad de crear un proceso administrativo separado únicamente para BAS-IP.
Por ejemplo, la plataforma principal puede determinar que un contratista debe poder ingresar a un edificio el martes entre las 10:00 y las 14:00. En ese escenario, BAS-IP se convierte en la capa de acceso que lleva a cabo un proceso ya definido en otro lugar.
El control de acceso e intercomunicación se convierten así en parte del modelo operativo más amplio del edificio, en lugar de un sistema separado que debe administrarse independientemente.
¿Qué pasa si el sitio ya está en funcionamiento y tiene una gran base de usuarios?
Una integración no comienza necesariamente con una base de datos vacía.
Si un sistema existente ya contiene cientos o miles de residentes, no tienen que introducirse manualmente en BAS-IP Link uno por uno.
Al utilizar BAS-IP Link API, el método de creación de usuarios puede añadir múltiples usuarios en una sola solicitud.
Actualmente no se especifican un número máximo garantizado de registros por operación ni la frecuencia permitida de solicitudes consecutivas. Por lo tanto, para una migración grande, estos parámetros deben validarse en el entorno de prueba del proyecto antes de mover toda la base de usuarios.
Los detalles de implementación para el método API se proporcionan a los socios de integración en la documentación técnica.
También hay una opción integrada para la creación masiva de usuarios sin desarrollar una integración de API.
BAS-IP Link puede exportar la estructura del sitio a un archivo XLS. Los detalles del usuario y de la licencia se completan luego en la hoja de cálculo y se importan nuevamente a Link. Una vez importados, los usuarios se asignan automáticamente a los grupos de sitios especificados. Cuando varios usuarios pertenecen al mismo apartamento u otro grupo de sitio, las filas separadas pueden usar el mismo identificador de grupo.
Para un despliegue residencial inicial, no es necesario recopilar una dirección de correo electrónico para cada miembro del hogar. Una dirección de correo electrónico por apartamento es suficiente: el usuario invitado recibe un correo electrónico, completa el registro y luego puede añadir a los miembros de la familia por sí mismo.
Por lo tanto, para un desarrollo existente, el equipo del proyecto puede elegir entre una migración de API automatizada y el proceso de carga masiva integrado de Link, según la arquitectura del sistema y dónde se encuentre la base de datos de usuarios de origen.
¿Se pueden usar los eventos de BAS-IP en otro sistema?
Sí. Los datos y eventos alojados en Link pueden ser utilizados por un sistema de terceros.
Por ejemplo, un equipo de seguridad ya puede trabajar desde una única interfaz que reúne información del control de acceso, CCTV y otros sistemas del edificio. Los datos de BAS-IP pueden formar parte del mismo flujo de trabajo operativo.
Sin embargo, hay una distinción técnica importante.
BAS-IP Link no proporciona actualmente webhooks para enviar eventos a sistemas de terceros. El sistema externo recupera los datos requeridos realizando solicitudes a Link API.
Si un proyecto requiere que eventos particulares se entreguen directamente desde el equipo a través de webhooks, ese escenario está disponible en los paneles de entrada basados en Android compatibles a través de BAS-IP Device API.
Por lo tanto, un proyecto puede combinar la integración centralizada a través de Link con la interacción directa con dispositivos seleccionados cuando sea necesario.
¿Qué sistema debe ser la fuente de la verdad?
Una de las decisiones clave en una integración es qué sistema es responsable de cada tipo de datos.
Si el mismo usuario se puede modificar de forma independiente tanto en la plataforma de gestión de propiedades como en BAS-IP Link, los registros pueden llegar a ser inconsistentes.
Por ejemplo, la plataforma de gestión de propiedades puede seguir siendo responsable de los residentes y los apartamentos, BAS-IP Link puede aplicar esa información al control de acceso e intercomunicación, mientras que una plataforma de seguridad separada consume los datos de eventos necesarios para los operadores.
Otro proyecto puede dividir las responsabilidades de manera diferente.
El punto importante no es que BAS-IP, o la plataforma de terceros, deba ser siempre el sistema «maestro». Es que la fuente autorizada para cada entidad y la dirección de sincronización deben estar claramente definidas.
Eso es lo que elimina la administración duplicada en lugar de simplemente conectar dos bases de datos.
¿Dónde es más útil Link API?
Link API es particularmente relevante cuando BAS-IP necesita convertirse en parte de un ecosistema de software existente.
Ejemplos típicos incluyen:
- plataformas de gestión de propiedades residenciales y fincas;
- grandes sistemas de control de acceso;
- BMS y plataformas de edificios inteligentes;
- productos PropTech;
- plataformas de software propias de los integradores;
- plataformas que gestionan múltiples edificios o sitios.
Cuantos más usuarios, edificios y cambios de acceso regulares tenga un proyecto, más se duplica la administración cuando los sistemas permanecen separados.
Por lo tanto, el valor de Link API no suele definirse por el número de métodos API disponibles, sino por el número de procesos operativos separados que se pueden unificar.
Seguridad y permisos de integración
Un sistema de terceros no necesita acceso administrativo sin restricciones a Link.
En BAS-IP Link Self-Hosted, se puede crear una cuenta de integración dedicada y restringir sus permisos tanto por función como por sitio individual.
Por ejemplo, una integración utilizada por un operador de propiedades en particular se puede limitar a los edificios gestionados por esa organización.
La autenticación utiliza tokens de acceso y la comunicación API se realiza a través de HTTPS.
El flujo de autenticación detallado y las estructuras de solicitud se tratan en la documentación técnica de Link API.
BAS-IP Link Self-Hosted y Link Cloud
En el momento de la publicación, las integraciones del lado del servidor de terceros a través de BAS-IP Link API son compatibles con BAS-IP Link Self-Hosted.
BAS-IP está desarrollando una puerta de enlace API (API gateway) separada para BAS-IP Link Cloud.
Por lo tanto, si un proyecto requiere específicamente una integración de terceros con Link Cloud, la arquitectura propuesta debe discutirse con BAS-IP antes de que comience el desarrollo.
Cómo iniciar una integración
Un proyecto de Link API comienza con el caso de uso en lugar de una lista de llamadas API.
Por ejemplo:
«Cuando creamos un residente en nuestra plataforma, queremos que el usuario se cree automáticamente en el sitio BAS-IP correcto».
Eso es suficiente para iniciar una discusión arquitectónica.
Una vez acordado el escenario de integración, el socio firma un NDA (Acuerdo de confidencialidad) y recibe los materiales técnicos relevantes.
La integración en sí suele ser desarrollada por el equipo del socio. Un proyecto típico normalmente requerirá un desarrollador backend o full-stack. Las implementaciones más grandes también pueden requerir experiencia en DevOps.
Para el desarrollo y las pruebas, BAS-IP Link Self-Hosted se puede implementar en el propio entorno del socio. Actualmente no hay un entorno de pruebas público (sandbox) compartido para Link API. Las licencias de prueba y los arreglos de hardware se acuerdan de acuerdo con los requisitos del proyecto individual.
BAS-IP proporciona documentación, responde preguntas técnicas relacionadas con sus propios productos y ayuda a investigar casos en los que una implementación basada en la documentación no se comporta como se esperaba.
Si un proyecto requiere funcionalidad que no está disponible actualmente en el producto, el requisito se puede discutir con el equipo de producto. El trabajo involucrado y su lugar dentro del plan de desarrollo se evalúan primero. Dicha evaluación no constituye en sí misma un compromiso con una fecha de lanzamiento particular.
¿Cuánto tiempo lleva una integración de Link API?
No hay un plazo único que se aplique a todos los proyectos.
Para una integración relativamente estándar, alrededor de un mes de desarrollo enfocado se puede utilizar como una guía general, aunque la duración del calendario suele ser mayor.
El equipo de desarrollo del socio necesita tiempo para comprender el modelo de datos de Link, implementar su parte de la integración, probarla y ajustar el trabajo en su propio cronograma de desarrollo.
Por lo tanto, solo se puede hacer una estimación significativa una vez que se ha definido el escenario de integración real.
¿Hay algún cargo adicional por BAS-IP Link API?
Por lo general, BAS-IP no cobra una tarifa por separado por el acceso a la documentación y las herramientas de integración.
BAS-IP Link en sí tiene licencia bajo el modelo estándar de licencias de productos. El socio desarrolla su propio lado de la integración, mientras que el trabajo de desarrollo de BAS-IP no estándar o las solicitudes para cambiar la prioridad de dicho trabajo se pueden discutir por separado cuando sea necesario.
Por esa razón, describir la integración en sí como «gratuita» puede ser engañoso.
Una afirmación más precisa es que normalmente no hay un cargo adicional por el acceso a las herramientas de integración de BAS-IP.
¿Cuándo Link API no es el enfoque correcto?
Link API está pensada principalmente para la integración del lado del servidor con BAS-IP Link.
Si el requisito es trabajar directamente con equipos específicos, o recibir eventos particulares directamente desde un panel de entrada, BAS-IP Device API puede ser más apropiada. La documentación de integración de dispositivos está disponible a través del portal de desarrolladores público de BAS-IP.
Si una organización ya tiene su propia aplicación móvil y desea agregar llamadas de intercomunicador, video y apertura de puertas dentro de esa aplicación, BAS-IP Mobile SDK está diseñado para ese caso de uso.
Y donde la interoperabilidad estándar a través de SIP, RTSP o Wiegand es suficiente, es posible que no se requiera en absoluto una integración de software a medida.
Los diferentes enfoques se tratan con más detalle en «Integración de IP de control de acceso BAS-IP con sistemas de construcción existentes».
Preguntas frecuentes
¿Es BAS-IP Link API una API REST?
Sí. BAS-IP Link API es una API HTTP REST que permite a un sistema del lado del servidor de terceros interactuar programáticamente con BAS-IP Link.
¿Necesito BAS-IP Link para usar Link API?
Sí. Link API es la interfaz de programación para la plataforma BAS-IP Link.
¿Funciona BAS-IP Link API con Link Cloud?
En el momento de la publicación, las integraciones del lado del servidor de terceros a través de Link API son compatibles con BAS-IP Link Self-Hosted. BAS-IP está desarrollando una puerta de enlace API separada para Link Cloud.
¿Cómo obtengo la documentación y se requiere un NDA?
El caso de uso de integración se acuerda primero. Luego, el socio firma un NDA y recibe los materiales técnicos relevantes de Link API.
¿Cuál es la diferencia entre Link API y Mobile SDK?
Link API está destinada a la integración del lado del servidor con BAS-IP Link, incluidos usuarios, sitios, derechos de acceso y otras entidades de la plataforma centralizada.
BAS-IP Mobile SDK tiene un propósito diferente: agregar funcionalidad de intercomunicador (control de acceso) directamente a una aplicación móvil existente.
Ambos se pueden usar dentro del mismo proyecto cuando sea necesario.
¿Desea integrar su plataforma con BAS-IP Link?
No necesita preparar una especificación de API detallada antes de la primera discusión.
Comience describiendo el sistema que ya tiene y el proceso que desea automatizar.
Por ejemplo:
«Creamos residentes en nuestra propia plataforma y queremos que se transfieran automáticamente a BAS-IP».
o:
«Gestionamos el acceso de visitantes en nuestro propio sistema y queremos conectar ese proceso con BAS-IP».
El equipo de BAS-IP puede ayudar a determinar si Link API es el enfoque correcto, qué capacidades de la plataforma se requerirán y cómo debe estructurarse la integración.