API e integraciones con software de terceros

El esquema técnico es sencillo y robusto: puedes conectar tu software a la capa de API de tu instalación y gestionarla de forma autónoma.

La estructura de la API permite realizar operaciones simulando casi la totalidad de las funciones del panel de manage que incluimos con el KIT. Todas las llamadas deben estar activadas y provenir de una IP autorizada.

A continuación encontrarás la guía completa de todas las llamadas disponibles, organizadas por área funcional. La misma documentación también está disponible en formato interactivo en Postman: ¡haz clic aquí!.

Nota: también está disponible una versión reforzada del servicio de API (API PRO), que permite obtener los logs de las llamadas API y realizar la apertura remota — consulta la sección Api Pro o contáctanos para más información.

Para ejemplos prácticos de integración con sistemas de gestión, PMS, plataformas de reservas y de pago, consulta Integraciones más comunes: cómo hacerlo.

Autenticación

Todas las llamadas (excepto la comprobación de estado) requieren un token Bearer, obtenido mediante la llamada authorize y enviado como header en las solicitudes posteriores.

• El token es válido durante 1 hora: debe renovarse periódicamente repitiendo la llamada authorize.
• No hay límites en el número de llamadas que se pueden realizar.
• Errores posibles en la llamada authorize: IP no autorizada o secret_key incorrecta (invalid_access), credenciales incorrectas (invalid_credentials), error genérico (could not create token).
• Errores posibles en las demás llamadas: token expirado, inválido o ausente (invalid_token). Los errores específicos se indican en el campo messages de la respuesta JSON.

POST /api/v2/authorize — Obtener el token

Devuelve el token Bearer que se debe usar en todas las llamadas posteriores.

• Parámetros obligatorios: email (email del operador), password (contraseña del operador), secret_key (asociada a la IP autorizada, se encuentra en el panel en la sección API / Setup)
• Respuesta 200: token
• Respuesta 401: invalid_credentials (email o contraseña incorrectos), invalid_credentials2 (IP no autorizada o secret_key incorrecta), invalid_access1 (secret_key ausente)

GET /api/v2/ — Test de estado

Verifica que el panel esté activo y funcionando (imprime Test). No requiere autenticación ni parámetros.

Usuarios

PUT /api/v2/adduser — Crear nuevo usuario

Crea un nuevo usuario en el panel.

• Parámetros obligatorios: name (nombre), surname (apellido)
• Parámetros opcionales: email, phone, prefix (prefijo internacional urlencoded, ej. +39 → %2b39), tags (array; cada coma se sustituye por un guion bajo), status (1 = habilitado, 0 = deshabilitado), fields (array de campos adicionales personalizados en el formato fields[id_campo]=valor)

PUT /api/v2/updateuser — Modificar usuario

Actualiza los datos de un usuario existente.

• Parámetros obligatorios: user_id, name, surname
• Parámetros opcionales: email, phone, prefix, tags, status (1 = habilitado, 0 = deshabilitado), fields (array de campos adicionales, mismo formato que AddUser)

DELETE /api/v2/deleteuser — Eliminar usuario

Elimina un usuario del panel.

• Parámetros obligatorios: user_id
• Respuesta 200: usuario eliminado con éxito
• Respuesta 400: usuario no encontrado

GET /api/v2/getusers — Lista de usuarios

Devuelve los datos de todos los usuarios presentes en el panel, o de uno específico si se pasa el parámetro opcional.

• Parámetros opcionales: user_id, tags (filtra los usuarios por tag), getGrantInfo (si es 1, incluye también los detalles de los accesos asociados)
• Respuesta 404: ningún usuario encontrado

GET /api/v2/users/getStatus — Estado del usuario

Devuelve si un usuario está habilitado o deshabilitado.

• Parámetros: user_id

POST /api/v2/users/changeStatus — Cambiar estado del usuario (aún no disponible)

Si status = 1 el usuario queda habilitado para los accesos, si status = 0 queda deshabilitado.

• Parámetros: user_id, status (1 = habilitado, 0 = deshabilitado)

Grupos

GET /api/v2/getGroup — Lista de grupos

Devuelve los datos de todos los grupos presentes en el panel, o de uno o más específicos si se pasa el parámetro opcional.

• Parámetros opcionales: group_id (puede ser un array)
• Respuesta 404: ningún grupo encontrado

POST /api/v2/grantAccessGroup — Habilitar acceso a un grupo

Habilita el acceso de uno o más usuarios a uno o más grupos indicados, creando la asociación usuario-grupo.

• Parámetros obligatorios: user_id (puede ser un array), group_id (puede ser un array)
• Respuesta 200: asociaciones creadas con éxito
• Respuesta 400: usuario no encontrado, grupo no encontrado, asociación ya existente

POST /api/v2/dropAccessGroup — Revocar acceso a un grupo

Revoca los permisos de acceso de un usuario perteneciente a un grupo, eliminando la asociación usuario-grupo.

• Parámetros obligatorios: user_id (puede ser un array), group_id (puede ser un array)
• Respuesta 200: asociaciones eliminadas con éxito
• Respuesta 400: asociación no existente, grupo no encontrado, usuario no encontrado

Créditos

GET /api/v2/getcredits — Saldo de créditos

Devuelve el saldo de créditos disponible.

GET /api/v2/getprices — Lista de precios

Devuelve la lista de precios para la recarga de créditos.

POST /api/v2/recharge — Recargar créditos

Efectúa una recarga de crédito.

• Parámetros: user_id, amount (ej. 10.50)

Llaves

GET /api/v2/getunusednfc — Llaves NFC libres

Devuelve la lista de llaves NFC no asociadas a ningún usuario. No requiere parámetros.

• Respuesta 404: ninguna llave NFC libre encontrada

GET /api/v2/getallnfc — Lista de llaves NFC

Devuelve los datos relativos a todas las llaves NFC presentes en el panel, asociadas o no.

• Parámetros opcionales (paginación): limit, offset
• Respuesta 400: ninguna llave encontrada, o offset usado sin limit

PUT /api/v2/addkey — Insertar llave NFC

Inserta una nueva llave NFC.

• Parámetros obligatorios: nfc_key_code (código RFID leído con un lector estándar: se convertirá según el estándar LabKey — no usar un código tomado de un log de accesos), nfc_key_name (nombre que se asociará a la llave)
• Parámetros opcionales: force_hex (fuerza la conversión del código desde cadena hexadecimal; si se omite, la conversión se realiza automáticamente solo si el código contiene al menos una letra)

PUT /api/v2/addkey2user — Asociar llave NFC a un usuario

Asocia una llave NFC a un usuario específico.

• Parámetros obligatorios: user_id, nfc_key_id
• Respuesta 400: llave ya asignada
• Respuesta 404: llave no encontrada, usuario no encontrado

DELETE /api/v2/deletekey — Eliminar llave NFC

Elimina una llave NFC.

• Parámetros obligatorios: nfc_key_code (código RFID convertido según el estándar LabKey, ej. 1234567890 → 210215073)
• Respuesta 404: llave no existente
• Respuesta 400: nfc_key_code ausente

GET /api/v2/getnfcdetails — Detalles de llave NFC

Devuelve los detalles relativos a una llave NFC.

• Parámetros obligatorios: nfc_key_code (código convertido según el estándar LabKey)
• Respuesta 404: ningún usuario vinculado a la llave, llave NFC no encontrada
• Respuesta 400: parámetros ausentes

POST /api/v2/editnfc — Modificar llave NFC

Modifica los detalles de una llave NFC.

• Parámetros obligatorios: nfc_key_code, name
• Respuesta 404: nfc_key_code no encontrado o ausente, name ausente

POST /api/v2/edittastierino — Modificar código de teclado

Cambia el código de un teclado (pinpad).

• Parámetros obligatorios: old_pinpad_key_code (código antiguo a sustituir), new_pinpad_key_code (código nuevo)
• Respuesta 200: código actualizado correctamente
• Respuesta 404: el código antiguo no existe
• Respuesta 400: el código debe ser numérico

POST /api/v2/updatepinpad — Actualizar código de teclado por usuario

Actualiza el código de teclado seleccionando el usuario.

• Parámetros obligatorios: user_id, new_pinpad_key_code
• Respuesta 404: usuario no existente
• Respuesta 400: el código debe ser numérico, llave ya existente

POST /api/v2/getqrcode — Generar código QR

Genera un código QR para el usuario seleccionado, utilizable a partir del “messagge string”.

• Parámetros obligatorios: user_id
• Parámetros opcionales: image (si es 1, devuelve la imagen del código QR codificada en base64), with_background (requiere image=1; si es 1, añade un fondo decorativo a la imagen)
• Respuesta 404: usuario no encontrado

POST /api/v2/getfasturl — Generar Fast URL

Genera la Fast URL para el usuario seleccionado, utilizable a partir del campo “fast_url”.

• Parámetros obligatorios: user_id
• Respuesta 404: usuario no encontrado

GET /api/v2/getallpinpad — Lista de códigos de teclado

Devuelve todos los códigos de teclado y sus detalles.

• Parámetros opcionales (paginación): limit, offset
• Respuesta 400: establecer tanto limit como offset, o dejarlos ambos vacíos; limit/offset deben ser enteros

Accesos y permisos

POST /api/v2/getGrantInfo — Detalles de un acceso

Devuelve los datos relativos al acceso especificado.

• Parámetros obligatorios: involved_associations (uno o más ID devueltos por la llamada grantaccess)
• Respuesta 200: información sobre el usuario y, para cada LabKey asociada, los detalles del acceso
• Respuesta 400: es necesario enviar al menos un involved_associations válido
• Respuesta 404: fila con ese involved_associations no encontrada

POST /api/v2/automategetGrantInfo — Detalles de acceso simplificado

Llamada de conveniencia para simplificar el uso de getGrantInfo.

• Parámetros opcionales: user_id (puede ser un array), unique_name (puede ser un array — nombre de la LabKey seleccionada)

GET /api/v2/getuservarcodetails — Detalles de accesos del usuario

Devuelve todos los detalles sobre los accesos asociados al usuario seleccionado.

• Parámetros obligatorios: user_id

POST /api/v2/grantaccess — Habilitar acceso

Habilita el acceso de un usuario. Para configurar una combinación de varias tecnologías (NFC, teclado, código de barras) es posible invocar esta API varias veces cambiando la key_id.

• Parámetros obligatorios: user_id, key_id (ID de la llave de acceso asociada al usuario: usar nfc_key_id para NFC/Pocket, pinpad_key_id para teclado/código de barras), data (cadena JSON con los parámetros de cada acceso: intervalo de fechas datei/datef, horarios houri/hourf, días de la semana mo,tu,we,th,fr,sa,su, días festivos tv, command_device_id, id_rele, technology)
• Parámetros opcionales: check_overalapping, force_same_idrele_commanddeviceid

POST /api/v2/editaccess — Modificar acceso

Llamada de conveniencia que ejecuta en secuencia dropaccess y grantaccess, devolviendo un nuevo involved_associations para el usuario. No es una operación atómica: si dropaccess finaliza correctamente pero grantaccess falla, las asociaciones quedan igualmente eliminadas.

• Parámetros obligatorios: involved_associations (puede ser un array), user_id, key_id, data (cadena JSON, mismo formato que GrantAccess)

DELETE /api/v2/dropaccess — Revocar acceso

Revoca los permisos de acceso.

• Parámetros obligatorios: involved_associations (código obtenido de la respuesta de grantaccess)

POST /api/v2/isAccessible — Verificar accesibilidad de un acceso

Verifica si un acceso es accesible en un intervalo de tiempo determinado.

• Parámetros obligatorios: unique_name, from_date (timestamp), to_date (timestamp), id_rele

Gestión de contadores (antipassback)

GET /api/v2/antipassback/ — Detalles del contador

Devuelve los detalles sobre la gestión de contadores para el usuario y el acceso indicados. La respuesta es un array con el detalle de cada relé.

• Parámetros: user_id, unique_name
• Campos de la respuesta: is_active (1/0, contador activo o no), has_total/number_total (límite total de accesos), has_day/number_day (límite diario), has_week/number_week (límite semanal), has_month/number_month (límite mensual)

POST /api/v2/antipassback/update_or_create — Configurar contador

Crea o actualiza la configuración del contador para uno o más relés.

• Parámetros: user_id, data (cadena JSON con, para cada LabKey y relé, los campos is_active, has_total/number_total, has_day/number_day, has_week/number_week, has_month/number_month)
• Nota: si is_active está configurado, solo se puede activar uno entre has_total, has_day, has_week o has_month — no es posible activarlos simultáneamente.

General

GET /api/v2/getlabkeys — Lista de LabKey

Devuelve los detalles de las centralitas/LabKey.

• Parámetros opcionales: unique_name, labkey_id, key_tipe
• Respuesta 400: ninguna LabKey encontrada

GET /api/v2/getbuildings — Lista de instalaciones

Devuelve la información sobre las instalaciones asociadas al panel.

• Parámetros opcionales: structure_id, structure_name, referent

GET /api/v2/getlogs — Log de accesos

Devuelve los logs de los accesos.

• Parámetros opcionales: from (fecha de inicio), to (fecha de fin), unique_name (nombre de la LabKey), labkey_id, user_id, limit (paginación), offset (paginación)

POST /api/v2/sendemail — Enviar email

Envía un email a un cliente, por ejemplo con los detalles de acceso.

• Parámetros obligatorios: user_id (destinatario), operator_email (remitente)
• Parámetros opcionales: message (mensaje personalizado; si se omite se envía un mensaje predeterminado), cc_emails (array de direcciones en copia), show_sender_name, send_permissions_list, send_fast_url, send_qr_code

WebHooks

Alerts — Notificaciones en tiempo real

Permite recibir notificaciones automáticas hacia tu propio endpoint cada vez que se produce un evento (ej. un acceso). El webhook se configura desde el panel de Manage, en la sección Alert → Alert Standard.

• Parámetros enviados en query string a tu endpoint: user_id, full_name, id_log, key_code, result_boolean (acceso permitido o no), timestamp, is_log_offline, unique_name, labkey_id, tags, event_type

Campos adicionales

Gestión de los campos personalizados que se pueden asociar a la ficha del usuario (ver también Inserción de nuevo usuario).

GET /api/v2/customfields — Lista de campos

Devuelve la lista de campos adicionales con sus atributos.

• Parámetros opcionales (paginación): limit, offset

GET /api/v2/customfields/{id_field} — Detalle de campo

Devuelve los detalles de un campo adicional específico.

GET /api/v2/customfields/count — Conteo de campos

Devuelve el número de campos adicionales guardados.

POST /api/v2/customfields/create — Crear campo

Crea un nuevo campo adicional.

• Parámetros obligatorios: type_field (text o date), name_field (máx. 255 caracteres)
• Parámetros opcionales: order (numérico), is_required (1 = obligatorio al completar el usuario), can_disable_user (1 = sí; utilizable solo con type_field=date — el sistema deshabilita automáticamente al usuario a medianoche si la fecha introducida ya ha pasado)

POST /api/v2/customfields/{id_field}/update — Modificar campo

Actualiza un campo adicional existente. Mismos parámetros que create.

Campos adicionales de usuario

GET /api/v2/customfieldsuser/{id_user}/ — Lista de campos por usuario

Devuelve todos los campos adicionales con valor para un usuario.

• Parámetros opcionales (paginación): limit, offset

GET /api/v2/customfieldsuser/{id_user}/{id_field} — Valor de campo por usuario

Devuelve el valor de un campo adicional específico para el usuario indicado.

POST /api/v2/customfieldsuser/{id_user}/{id_field}/create — Establecer valor de campo

Crea el valor de un campo adicional para el usuario.

• Parámetros obligatorios: value (máx. 255 caracteres)
• Parámetros opcionales: can_disable_user (0 = no, 1 = sí)

POST /api/v2/customfieldsuser/{id_user}/{id_field}/update — Actualizar valor de campo

Actualiza el valor de un campo adicional para el usuario. Mismos parámetros que create.

Plantillas

Gestión de las plantillas predefinidas para los accesos recurrentes (ver también Plantillas).

GET /api/v2/templates/count — Conteo de plantillas

Devuelve el número de plantillas guardadas.

GET /api/v2/templates/ — Lista de plantillas

Devuelve la lista de plantillas.

• Parámetros opcionales (paginación): limit, offset

GET /api/v2/templates/detail — Detalle de plantilla

Devuelve el detalle de una plantilla específica.

• Parámetros: template_id

POST /api/v2/templates/addAccessUser — Aplicar plantilla a usuario

Aplica una plantilla de acceso a un usuario. Se puede usar de dos maneras: indicando tanto timestamp_start como timestamp_end (el sistema establece el inicio y el fin del acceso en esos valores), o indicando solo timestamp_start y dejando que el sistema calcule automáticamente el fin según la configuración de la plantilla.

• Parámetros obligatorios: user_id, template_id
• Parámetros opcionales: timestamp_start (por defecto: ahora), timestamp_end

Festividades

Gestión de festividades (ver también Festividades): durante los intervalos configurados, los accesos seleccionados se abren solo a los usuarios autorizados.

GET /api/v2/festivita — Lista de festividades

Devuelve todas las festividades, o una específica si se pasa el ID.

• Parámetros opcionales: id
• Respuesta 404: festividad no encontrada

GET /api/v2/festivita/count — Conteo de festividades

Devuelve el número de festividades configuradas.

• Parámetros opcionales: id
• Respuesta 400: parámetros no válidos o ausentes

GET /api/v2/festivita/is_holiday — Verificar festividad

Verifica si una fecha/hora específica cae dentro de un período festivo.

• Parámetros obligatorios: datetime (formato YYYY-MM-DD HH:MM:SS)
• Parámetros opcionales: unique_name, labkey_id, rele (array), user_id
• Respuesta 200: is_holiday (booleano)
• Respuesta 400: parámetros no válidos o ausentes

POST /api/v2/festivita/create — Crear festividad

Crea una nueva festividad.

• Parámetros obligatorios: title, start_datetime (formato YYYY-MM-DD HH:MM:SS), end_datetime (formato YYYY-MM-DD HH:MM:SS)
• Parámetros opcionales: description, recurring (1 = recurrente cada año), notification_email, monday…sunday (1 = activa en ese día), varcos (array JSON de labkey_id/rele involucrados), user_ids (array de usuarios involucrados)

POST /api/v2/festivita/update — Modificar festividad

Actualiza una festividad existente. Mismos parámetros opcionales que create.

• Parámetros obligatorios: id
• Parámetros opcionales: title, start_datetime, end_datetime, recurring, active (1 = habilitada, 0 = deshabilitada), notification_email, monday…sunday, varcos, user_ids

DELETE /api/v2/festivita/delete — Eliminar festividad

Elimina una festividad.

• Parámetros obligatorios: id
• Respuesta 200: festividad eliminada con éxito
• Respuesta 400: parámetros no válidos o ausentes
• Respuesta 404: festividad no encontrada