API Integratec

Clientes

Activos

Dispositivos

Tuneles VPN

Clientes

Peers

En linea

Fuera de linea

WireGuard Peers

Dispositivos

En linea

Fuera de linea

Sin verificar

Monitoreo de Salud

WhatsApp — Servicio de Notificaciones

Verificando...

Usuarios

Mi Cuenta

Dispositivos

API Keys

VPN

req/min

Informacion del plan

Cargando...

Notificaciones

Reciba alertas cuando un dispositivo se desconecte o vuelva en linea.

Email para alertas

WhatsApp (formato internacional)

Notificaciones activas

Zona horaria

Las fechas y horas se muestran en esta zona horaria.

Estado de dispositivos

Cargando...

Actividad reciente

Cargando...

Mis API Keys

Mis Tuneles VPN

Dashboard

Estado de Dispositivos

Cargando...

Accesos vigentes

Permanentes

Temporales

Expirados

Expiran en 48h

Cargando...

Ultimos accesos creados

Cargando...

Panel de Puertas

Cargando...

Mis Dispositivos

QR Access

Generar QR de Acceso

Dispositivos (seleccione uno o varios)

Cargando...

Nombre

Valido desde

Valido hasta

Tipo de acceso

Puertas

Puerta 1 Puerta 2 Puerta 3 Puerta 4

Codigo de coaccion (alarma silenciosa)

Enviar QR al visitante (opcional)

Registros QR

Cargando...

Reportes

Reporte de Accesos

Desde

Hasta

Dispositivo

Reporte de Personas

Documentacion del API

Abrir Swagger UI ↗

Todos los endpoints requieren autenticacion: Authorization: Bearer <api_key>
Base URL:

Compatibilidad por Modelo

Funciones disponibles por tipo de dispositivo

Cargando...

Nota: Esta tabla se genera desde los perfiles del sistema. Al registrar un dispositivo, la API detecta el modelo y habilita solo las funciones compatibles.

Conceptos Generales

Errores, Rate Limiting, Webhooks

Formato de errores
Todos los errores retornan JSON con el campo detail:

// HTTP 400/401/403/404/429/502 { "detail": "Descripcion del error" } // Codigos comunes: // 400 - Datos invalidos o IP publica no permitida // 401 - Token faltante o invalido // 403 - Sin permisos o limite del plan alcanzado // 404 - Recurso no encontrado // 429 - Rate limit excedido // 502 - Dispositivo no responde o error ISAPI

Rate Limiting
Cada cliente tiene un limite de requests por minuto (default: 120/min). Los headers de respuesta incluyen:

X-RateLimit-Limit: 120 // Max requests por minuto X-RateLimit-Remaining: 98 // Requests restantes // Si excedes el limite: // HTTP 429 Too Many Requests // { "detail": "Rate limit exceeded. Try again later." }

Verificacion de Webhooks
Cada webhook incluye una firma HMAC-SHA256 en el header X-Integratec-Signature. Verifica asi:

# Python - verificar firma del webhook: import hmac, hashlib, json def verify_webhook(secret, body_bytes, signature): expected = hmac.new( secret.encode(), body_bytes, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) # En tu endpoint: signature = request.headers["X-Integratec-Signature"] is_valid = verify_webhook(webhook_secret, request.body, signature)

Eventos disponibles para webhooks: door.open, door.close, person.created, person.deleted, access.event, device.online, device.offline, * (todos)

Dispositivos

6 endpoints

POST/devices

Registrar un nuevo dispositivo de seguridad.

{ "name": "Biometrico Lobby", "device_type": "hikvision", "ip_address": "172.20.20.100", "port": 80, "username": "admin", "password": "Integratec20", "location": "Entrada principal" }

GET/devices

Listar todos los dispositivos registrados.

GET/devices/{device_id}

Obtener informacion de un dispositivo por ID.

GET/devices/{device_id}/status

Verificar si el dispositivo esta en linea. Retorna modelo, serial y firmware.

POST/devices/{device_id}/scan

Escanear las capacidades del dispositivo. Retorna que operaciones soporta (user_search, card_search, events_search, door_control, event_stream, card_create, qr, door_count). Importante: Controladoras (DS-K2600) no soportan busqueda de personas/eventos; biometricos (DS-K1T) soportan todo.

DELETE/devices/{device_id}

Eliminar un dispositivo del registro.

HikVision - Personas

5 endpoints

POST/hikvision/{device_id}/persons

Agregar una persona al dispositivo. Asigna acceso a puertas con rango de fechas.

Campo	Tipo	Descripcion
employee_no	string	ID alfanumerico (1-32 chars, sin especiales)
name	string	Nombre de la persona
user_type	string	"normal" \| "visitor" \| "blackList" (default: normal)
door_right	string	Puertas con acceso, ej: "1" o "1,2" (default: 1)
valid_begin	string	Inicio de vigencia ISO 8601 (default: 2026-01-01T00:00:00)
valid_end	string	Fin de vigencia ISO 8601 (default: 2036-12-31T23:59:59)
max_open_door_time	int	Max aperturas (0=ilimitado, 1=una sola vez)

{ "employee_no": "EMP001", "name": "Juan Perez", "user_type": "normal", "door_right": "1,2,3,4", "valid_begin": "2026-01-01T00:00:00", "valid_end": "2027-12-31T23:59:59", "max_open_door_time": 0 } // door_right: "1" = puerta 1, "1,2,3,4" = puertas 1 a 4

GET/hikvision/{device_id}/persons

Buscar personas registradas. Parametros: offset, limit. Nota: No disponible en controladoras DS-K2600 (notSupport).

PUT/hikvision/{device_id}/persons/{employee_no}

Actualizar datos de una persona (nombre, tipo, vigencia, puertas).

{ "name": "Juan Perez Rodriguez", "valid_end": "2028-12-31T23:59:59" }

DELETE/hikvision/{device_id}/persons/{employee_no}

Eliminar una persona del dispositivo.

POST/hikvision/{device_id}/persons/purge-expired

Eliminar todas las personas cuya vigencia ha expirado.

HikVision - Rostros

7 endpoints

Para agregar un rostro: primero cree una biblioteca de rostros, luego agregue el rostro con imagen (URL o archivo).

GET/hikvision/{device_id}/face-libraries

Listar todas las bibliotecas de rostros del dispositivo.

POST/hikvision/{device_id}/face-libraries

Crear una biblioteca de rostros en el dispositivo.

{ "name": "Empleados", "face_lib_type": "blackFD" }

POST/hikvision/{device_id}/faces

Agregar un rostro usando una URL de imagen.

Campo	Tipo	Descripcion
employee_no	string	ID del empleado (debe existir como persona)
name	string	Nombre de la persona
face_url	string	URL de la imagen del rostro (JPG/PNG)
fdid	string	ID de la biblioteca de rostros (default: "1")
face_lib_type	string	Tipo de biblioteca (default: "blackFD")

{ "employee_no": "EMP001", "name": "Juan Perez", "face_url": "https://ejemplo.com/fotos/juan.jpg", "fdid": "1", "face_lib_type": "blackFD" }

POST/hikvision/{device_id}/faces/upload

Agregar un rostro subiendo el archivo de imagen directamente (multipart/form-data).

# curl ejemplo: curl -X POST "{BASE_URL}/hikvision/{device_id}/faces/upload" \ -H "Authorization: Bearer {API_KEY}" \ -F "employee_no=EMP001" \ -F "name=Juan Perez" \ -F "image=@/ruta/foto.jpg"

POST/hikvision/{device_id}/faces/search

Buscar rostros en una biblioteca. Parametros: fdid, offset, limit.

PUT/hikvision/{device_id}/faces/{employee_no}

Actualizar un registro de rostro (nombre o imagen).

DELETE/hikvision/{device_id}/faces/{employee_no}

Eliminar un rostro del dispositivo.

HikVision - Tarjetas

3 endpoints

POST/hikvision/{device_id}/cards

Asignar una tarjeta a una persona.

Campo	Tipo	Descripcion
employee_no	string	ID del empleado (debe existir como persona)
card_no	string	Numero de tarjeta
card_type	string	"normalCard" \| "hijackCard" \| "superCard" (default: normalCard)

{ "employee_no": "EMP001", "card_no": "1234567890", "card_type": "normalCard" }

GET/hikvision/{device_id}/cards

Buscar tarjetas registradas. Parametros: offset, limit.

DELETE/hikvision/{device_id}/cards/{card_no}

Eliminar una tarjeta del dispositivo.

HikVision - Puertas y Sistema

5 endpoints

POST/hikvision/{device_id}/door

Abrir o cerrar una puerta de forma remota.

Campo	Tipo	Descripcion
action	string	"open" \| "close" \| "alwaysOpen" \| "alwaysClose"
door_no	int	Numero de puerta (default: 1)

// Abrir puerta 1: { "door_no": 1, "action": "open" } // Cerrar puerta 1: { "door_no": 1, "action": "close" }

GET/hikvision/{device_id}/door/{door_no}/params

Obtener configuracion de la puerta (nombre, tipo magnetico, duracion de apertura).

GET/hikvision/{device_id}/capabilities

Obtener capacidades generales del dispositivo (modelo, funciones soportadas, limites).

GET/hikvision/{device_id}/time

Obtener la hora y zona horaria del dispositivo.

GET/hikvision/{device_id}/access-control/capabilities

Capacidades de control de acceso: max usuarios, tarjetas, puertas, rostros soportados.

HikVision - Eventos

2 endpoints

POST/hikvision/{device_id}/events

Buscar eventos de acceso del dispositivo con filtros de fecha y tipo. Nota: No disponible en controladoras DS-K2600. Usar /events/stream como alternativa.

Campo	Tipo	Descripcion
start_time	string	Fecha inicio ISO 8601 (ej: 2026-02-01T00:00:00)
end_time	string	Fecha fin ISO 8601
major	int	Tipo mayor: 0=todos, 1=alarma, 5=acceso (default: 0)
offset	int	Paginacion: inicio (default: 0)
limit	int	Paginacion: cantidad (default: 100, max: 500)

{ "start_time": "2026-02-01T00:00:00", "end_time": "2026-02-28T23:59:59", "major": 5, "offset": 0, "limit": 100 }

GET/hikvision/{device_id}/events/stream

Leer alertas en tiempo real del dispositivo (streaming). Parametro: duration (segundos, 1-60, default: 10). Funciona en todos los dispositivos HikVision. Es la unica forma de obtener eventos en controladoras DS-K2600.

HikVision - QR Access

3 endpoints

POST/hikvision/multi/qr-access

Generar un QR de acceso y registrar la persona en multiples dispositivos a la vez. Usa door_right: "1,2,3,4" para acceso multi-puerta en controladoras.

Campo	Tipo	Descripcion
device_ids	string[]	Lista de IDs de dispositivos donde registrar
name	string	Nombre de la persona
valid_begin	string	Inicio de validez (ISO 8601)
valid_end	string	Fin de validez (ISO 8601)
door_right	string	"1" o "1,2,3,4" para multi-puerta (default: "1")
max_open_door_time	int	0=ilimitado, 1=unico uso (default: 0)
access_type	string	"single", "24h", "unlimited" (auto-derivado si se omite)
card_type	string	"normalCard" (default) o "hijackCard" (coaccion: abre puerta + alarma silenciosa)

// QR normal { "device_ids": ["abc123", "def456"], "name": "Maria Lopez", "valid_begin": "2026-02-23T08:00:00", "valid_end": "2026-02-24T18:00:00", "door_right": "1,2,3,4", "max_open_door_time": 1 } // QR de COACCION (alarma silenciosa) { "device_ids": ["abc123"], "name": "Maria Lopez - Emergencia", "valid_begin": "2026-01-01T00:00:00", "valid_end": "2027-12-31T23:59:59", "door_right": "1", "card_type": "hijackCard" } // La puerta abre normalmente pero genera // evento alarma (major=1, minor=1028)

POST/hikvision/{device_id}/qr-access

Generar QR de acceso para un solo dispositivo. Mismos parametros que multi/qr-access (sin device_ids).

{ "name": "Visitante Juan", "valid_begin": "2026-02-23T08:00:00", "valid_end": "2026-02-23T18:00:00", "door_right": "1", "max_open_door_time": 1, "card_type": "normalCard" } // Retorna: { qr_base64, card_no, employee_no, ... } // card_type: "hijackCard" para codigo de coaccion

DELETE/hikvision/{device_id}/qr-access/{employee_no}

Revocar un acceso QR (elimina persona y tarjeta del dispositivo).

Codigo de Coaccion (hijackCard)

Cuando se usa card_type: "hijackCard", el QR funciona normalmente (abre la puerta) pero genera una alarma silenciosa en el controlador:

Evento de alarma: major=1, minor=1028 (Alarma de Coaccion)
La persona ingresa sin que el atacante sospeche
El evento se captura via alertStream y se almacena en la plataforma
Ideal para condominios: residente bajo amenaza presenta su QR de coaccion
La salida de alarma fisica (rele) se configura desde iVMS-4200 o la web del controlador

ZKTeco

6 endpoints

GET/zkteco/{device_id}/users

Listar todos los usuarios del dispositivo ZKTeco.

POST/zkteco/{device_id}/users

Agregar un usuario al dispositivo.

Campo	Tipo	Descripcion
user_id	string	ID del usuario (ej: "EMP001")
name	string	Nombre del usuario
uid	int	UID interno (auto-asignado si vacio)
privilege	int	0=Usuario, 2=Enroll, 6=Admin, 14=SuperAdmin (default: 0)
password	string	Contrasena (opcional)
card	int	Numero de tarjeta (0=ninguna)

{ "user_id": "EMP001", "name": "Juan Perez", "privilege": 0 }

PUT/zkteco/{device_id}/users/{user_id}

Actualizar un usuario. Solo enviar campos a modificar.

{ "name": "Juan P. Rodriguez", "privilege": 6 }

DELETE/zkteco/{device_id}/users/{user_id}

Eliminar un usuario.

GET/zkteco/{device_id}/attendance

Obtener registros de asistencia/acceso.

POST/zkteco/{device_id}/door/unlock

Desbloquear la puerta del dispositivo.

{ "duration": 5 }

Reportes

3 endpoints

GET/reports/access

Obtener registros de acceso de todos los dispositivos del cliente.

Query Param	Tipo	Descripcion
from_date	string	Fecha inicio ISO 8601 (default: hoy 00:00)
to_date	string	Fecha fin ISO 8601 (default: ahora)
device_id	string	Filtrar por dispositivo especifico
limit	int	Max registros (default: 500)

GET /reports/access?from_date=2026-02-01T00:00:00&to_date=2026-02-28T23:59:59&limit=100

GET/reports/access/csv

Descargar registros de acceso en formato CSV.

GET/reports/summary

Resumen rapido de la cuenta (dispositivos, eventos recientes).

Webhooks

5 endpoints

Los webhooks envian notificaciones HTTP a tu servidor cuando ocurren eventos (apertura de puerta, nuevo acceso, etc).

POST/webhooks

Registrar un webhook. Retorna el secret para verificar firmas (se muestra una sola vez).

Campo	Tipo	Descripcion
url	string	URL HTTPS destino (no permite localhost ni IPs privadas)
events	string[]	Eventos a suscribir (default: ["*"] = todos)

{ "url": "https://mi-servidor.com/webhook", "events": ["door.open", "access.event"] } // events: ["*"] para recibir todos

GET/webhooks

Listar mis webhooks.

PUT/webhooks/{webhook_id}

Actualizar un webhook (URL, eventos, estado).

DELETE/webhooks/{webhook_id}

Eliminar un webhook.

POST/webhooks/{webhook_id}/test

Enviar un evento de prueba al webhook.

Mi Cuenta (Self-Service)

7 endpoints

GET/account/info

Obtener perfil, limites del plan y uso actual.

POST/account/api-keys

Crear una API key nueva (la key completa se muestra una sola vez).

{ "name": "produccion" } // Retorna: { "id", "name", "key_prefix", "api_key", "is_active", "created_at" }

GET/account/api-keys

Listar mis API keys (sin mostrar el valor).

DELETE/account/api-keys/{key_id}

Revocar una API key.

PUT/account/devices/{device_id}

Actualizar nombre, IP, puerto, credenciales o ubicacion de un dispositivo. Solo enviar campos a modificar.

{ "name": "Biometrico Recepcion", "ip_address": "172.20.20.101", "location": "Recepcion" } // IP debe ser privada (10.x, 172.16-31.x, 192.168.x)

POST/account/peers

Solicitar un nuevo peer VPN (dentro del limite del plan). Retorna private key y config MikroTik una sola vez.

{ "name": "Oficina Central", "lan_subnet": "172.20.23.0/24" }

GET/account/peers

Listar mis peers VPN con estado en vivo.

QR (Generador standalone)

2 endpoints

POST/qr/generate

Generar una imagen QR como base64. No requiere autenticacion.

{ "code": "HELLO123", "size": 10 }

POST/qr/generate/image

Generar imagen QR como PNG directamente (Content-Type: image/png).

Clientes

WireGuard Peers

Monitoreo de Salud

WhatsApp — Servicio de Notificaciones

Usuarios

Mi Cuenta

Mis API Keys

Mis Tuneles VPN

Dashboard

Panel de Puertas

Mis Dispositivos

QR Access

Generar QR de Acceso

Registros QR

Reportes

Documentacion del API

Compatibilidad por Modelo

Conceptos Generales

Dispositivos

HikVision - Personas

HikVision - Rostros

HikVision - Tarjetas

HikVision - Puertas y Sistema

HikVision - Eventos

HikVision - QR Access

Codigo de Coaccion (hijackCard)

ZKTeco

Reportes

Webhooks

Mi Cuenta (Self-Service)

QR (Generador standalone)

Nuevo Cliente

Editar Plan del Cliente

Nuevo Peer WireGuard

Importar Peer Existente

Configuracion del Peer

Nuevo Usuario

Editar Usuario

Agregar Dispositivo

Agregar Dispositivo al Cliente

Editar Dispositivo

Agregar Persona

Editar Persona

Importar Personas (CSV)

Nueva API Key

API Key Creada

Editar Dispositivo

Solicitar Peer VPN

Peer VPN Creado

Actividad