Arquitectura de Integración — SGH · OnOff · HikConnect

Mapeo de Entidades entre Sistemas

Correspondencia entre las entidades de SGH y HikConnect. Los Access Levels y TimeSchedules se pre-configuran manualmente en HCC/HCT — la API solo permite listarlos y asignarlos a personas.

SGH		HikConnect	Gestión	Notas
Cliente	→	Grupo raíz	API	Nodo padre en jerarquía de grupos
Servicio	→	Sub-grupo	API	Grupo hijo dentro del cliente
Servicio / Puesto	→	Área	API	Agrupa dispositivos del puesto
— (físico)	→	Dispositivo	API	Nombre: `[CÓD_CLIENTE]-desc`
Empleado	→	Persona	API	SGH fuente de verdad, integración sincroniza
Turno / Horario	→	TimeSchedule	Manual HCC/HCT	Pre-configurado en plataforma
Servicio + Turno	→	Access Level	Manual HCC/HCT	Pre-configurado (Área + TimeSchedule). API solo lista y asigna a personas

Jerarquía en HikConnect 📁 Grupo: "CLI-001 — Empresa ABC" (= Cliente SGH)
   ├── 📂 Sub-grupo: "Vigilancia Norte" (= Servicio SGH)
   │     ├── 📍 Área: "Puesto Acceso Principal" (= Servicio/Puesto)
   │     │     ├── 📷 CLI-001-CAM-NORTE-01
   │     │     └── 📷 CLI-001-CAM-NORTE-02
   │     └── 📍 Área: "Puesto Portón Carga"
   │           └── 📷 CLI-001-CAM-CARGA-01
   └── 📂 Sub-grupo: "Vigilancia Sur"
         └── 📍 Área: "Puesto Recepción Sur"
               └── 📷 CLI-001-CAM-SUR-01

🔑 Access Level: "Vig. Norte — Turno Mañana" (pre-configurado en HCC/HCT)
   ├── Área: Puesto Acceso Principal
   └── TimeSchedule: Lun-Vie 06:00–14:00

Restricción de API: Los Access Levels y TimeSchedules no se pueden crear vía API. Deben pre-configurarse manualmente en la plataforma HCC/HCT. La API solo expone: accesslevel/list (listar), accesslevel/person/add (asignar), accesslevel/person/delete (quitar) y accesslevel/person/modify (modificar asignación).

Diagrama de Componentes

SGH es fuente de verdad. La integración lee SGH y configura HikConnect vía API (grupos, áreas, personas). Los Access Levels se pre-configuran en HCC/HCT y la integración solo los lista y asigna.

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1e293b', 'primaryTextColor': '#e4e8f1', 'primaryBorderColor': '#4e8cff', 'lineColor': '#4e8cff', 'secondaryColor': '#1c2230', 'tertiaryColor': '#151921', 'noteBkgColor': '#1c2230', 'noteTextColor': '#e4e8f1', 'noteBorderColor': '#2a3142' }}}%%

graph TB
  subgraph SGH["🏢 SGH — Fuente de Verdad (solo lectura desde integración)"]
    direction TB
    SGH_EMP["👥 Empleados
Legajo maestro"]
    SGH_CLI["🏛️ Clientes
Códigos, contratos"]
    SGH_SVC["🏷️ Servicios / Puestos
Ubicaciones, asignaciones"]
    SGH_PLAN["📋 Planificación Diaria
Turnos, horarios, coberturas"]
    SGH_API["🔌 API SGH
Endpoints de lectura"]
    SGH_EMP --- SGH_API
    SGH_CLI --- SGH_API
    SGH_SVC --- SGH_API
    SGH_PLAN --- SGH_API
  end

  subgraph ADMIN["👤 Administrador HCC/HCT (config. manual)"]
    direction TB
    ADM_AL["🔑 Access Levels
Área + TimeSchedule
Pre-configurados manualmente"]
    ADM_TS["🕐 TimeSchedules
Franjas horarias
Pre-configuradas manualmente"]
  end

  subgraph INT["⚡ Capa de Integración (orquestador)"]
    direction TB
    INT_SYNC["🔄 Sync Manager
Lee empleados y servicios
de SGH → sincroniza a Hik"]
    INT_MAP["🗺️ Mapper / Tabla de IDs
Cliente↔Grupo, Servicio↔SubGrupo
Puesto↔Área, Empleado↔Persona
Servicio+Turno↔AccessLevelId"]
    INT_EVT["📡 Event Listener
Polling de fichajes
HikConnect → OnOff"]
    INT_CFG["⚙️ Config Manager
ABM Grupos, Áreas
Listar y asignar Access Levels"]
    INT_SYNC --- INT_MAP
    INT_SYNC --- INT_CFG
    INT_EVT --- INT_MAP
  end

  subgraph ONOFF["📊 OnOff — Gestión de Fichajes"]
    direction TB
    ON_PROC["🔀 Procesador de Fichajes
Valida y aplica fichajes
a planificación"]
    ON_DEV["⚠️ Motor de Desvíos
Tardanzas, ausencias,
horas extra, irregularidades"]
    ON_RPT["📈 Reportes & Asistencia
Dashboards, exportaciones"]
    ON_API["🔌 API OnOff"]
    ON_PROC --- ON_DEV
    ON_DEV --- ON_RPT
    ON_PROC --- ON_API
    ON_RPT --- ON_API
  end

  subgraph HIK["🔐 HikConnect — Control de Acceso"]
    direction TB
    HIK_GRP["📁 Grupos / Organizations
Jerarquía: Cliente → Servicio"]
    HIK_AREA["📍 Áreas
= Servicio/Puesto de SGH
Agrupan dispositivos"]
    HIK_DEV["📷 Dispositivos
Nombre: CÓD_CLIENTE-desc"]
    HIK_PPL["🧑 Personas & Rostros
Registro biométrico"]
    HIK_ACC["🔑 Access Levels
Solo lectura + asignación
Creados en HCC/HCT"]
    HIK_EVT["📨 Eventos de Acceso
Entradas, salidas"]
    HIK_API["🌐 OpenAPI v2.14"]
    HIK_GRP --- HIK_API
    HIK_AREA --- HIK_API
    HIK_DEV --- HIK_API
    HIK_PPL --- HIK_API
    HIK_ACC --- HIK_API
    HIK_EVT --- HIK_API
  end

  ADMIN -- "Pre-config manual:
Access Levels + TimeSchedules" --> HIK_ACC
  SGH_API -- "① Lee clientes, servicios,
empleados, planificación" --> INT_SYNC
  INT_CFG -- "② ABM Grupos y Áreas
③ Lista Access Levels existentes
④ Asigna Access Levels a personas" --> HIK_API
  INT_SYNC -- "⑤ Crear/actualizar personas
+ rostros" --> HIK_API
  HIK_API -- "⑥ Eventos de fichaje
(polling periódico)" --> INT_EVT
  INT_EVT -- "⑦ Fichajes normalizados" --> ON_API
  ON_API -- "⑧ Consulta planificación" --> SGH_API

  classDef sghStyle fill:#0f2a1f,stroke:#34d399,stroke-width:2px,color:#e4e8f1
  classDef intStyle fill:#1a1a2e,stroke:#a78bfa,stroke-width:2px,color:#e4e8f1
  classDef onoffStyle fill:#2a1a0a,stroke:#f59e0b,stroke-width:2px,color:#e4e8f1
  classDef hikStyle fill:#0f1a2e,stroke:#4e8cff,stroke-width:2px,color:#e4e8f1
  classDef adminStyle fill:#2a1520,stroke:#f87171,stroke-width:2px,color:#e4e8f1

  class SGH_EMP,SGH_CLI,SGH_SVC,SGH_PLAN,SGH_API sghStyle
  class INT_SYNC,INT_MAP,INT_EVT,INT_CFG intStyle
  class ON_PROC,ON_DEV,ON_RPT,ON_API onoffStyle
  class HIK_GRP,HIK_AREA,HIK_DEV,HIK_PPL,HIK_ACC,HIK_EVT,HIK_API hikStyle
  class ADM_AL,ADM_TS adminStyle

SGH — Fuente de verdad

Admin HCC/HCT — Config. manual

Integración — Orquestador

OnOff — Fichajes y desvíos

HikConnect — Control de acceso

Secuencia — Setup Inicial (Estructura + Empleados)

Prerequisito manual: un administrador crea los Access Levels y TimeSchedules en HCC/HCT. Luego la integración lee SGH, crea grupos y áreas, lista los Access Levels existentes, y sincroniza empleados asignándoles los permisos correspondientes.

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1e293b', 'primaryTextColor': '#e4e8f1', 'primaryBorderColor': '#4e8cff', 'lineColor': '#4e8cff', 'secondaryColor': '#1c2230', 'tertiaryColor': '#151921', 'noteBkgColor': '#1c2230', 'noteTextColor': '#e4e8f1', 'noteBorderColor': '#2a3142', 'actorBkg': '#1e293b', 'actorTextColor': '#e4e8f1', 'actorBorder': '#4e8cff', 'activationBkgColor': '#1e293b', 'activationBorderColor': '#4e8cff' }}}%%

sequenceDiagram
  autonumber
  participant ADMIN as 👤 Admin HCC/HCT
  participant SGH as 🏢 SGH
  participant INT as ⚡ Integración
  participant HIK as 🔐 HikConnect API

  rect rgba(248, 113, 113, 0.08)
    Note over ADMIN,HIK: PREREQUISITO — Configuración manual en HCC/HCT
    ADMIN->>HIK: Crear TimeSchedules
(ej: Lun-Vie 06:00-14:00, Lun-Vie 14:00-22:00)
    ADMIN->>HIK: Crear Access Levels
(Área + TimeSchedule por cada combo servicio+turno)
    Note over ADMIN: Esto NO se puede hacer vía API.
Debe hacerse desde la plataforma HCC/HCT.
  end

  rect rgba(52, 211, 153, 0.08)
    Note over SGH,INT: FASE 1 — Lectura de Clientes y Servicios
    INT->>SGH: GET /clientes — Obtener clientes activos
    SGH-->>INT: Lista de clientes (código, nombre)
    INT->>SGH: GET /servicios — Obtener servicios/puestos
    SGH-->>INT: Lista de servicios
(nombre, ubicación, clienteId, turnos)
  end

  rect rgba(167, 139, 250, 0.08)
    Note over INT,HIK: FASE 2 — Crear Jerarquía de Grupos (Cliente → Servicio)
    loop Por cada cliente
      INT->>HIK: POST /orgs — Crear grupo raíz
(nombre: "CLI-001 — Empresa ABC")
      HIK-->>INT: 200 OK — groupId (cliente)
      loop Por cada servicio del cliente
        INT->>HIK: POST /orgs — Crear sub-grupo
(parentId: groupId cliente)
        HIK-->>INT: 200 OK — groupId (servicio)
      end
    end
    INT->>INT: Guardar mapeos: clienteId ↔ groupId
servicioId ↔ groupId
  end

  rect rgba(34, 211, 238, 0.08)
    Note over INT,HIK: FASE 3 — Crear Áreas (Servicio/Puesto) + Asignar Dispositivos
    loop Por cada servicio/puesto
      INT->>HIK: POST /areas — Crear área
      HIK-->>INT: 200 OK — areaId
      INT->>HIK: POST /areas/devices — Asignar dispositivos
(CLI-001-CAM-NORTE-01, etc.)
      HIK-->>INT: 200 OK
      INT->>INT: Guardar mapeo: servicioId ↔ areaId
    end
  end

  rect rgba(248, 113, 113, 0.08)
    Note over INT,HIK: FASE 4 — Obtener Access Levels pre-configurados
    INT->>HIK: POST /accesslevel/list — Listar
todos los Access Levels existentes
    HIK-->>INT: Lista de Access Levels
(id, nombre, áreaInfo, timeSchedule)
    INT->>INT: Construir tabla de mapeo:
servicio+turno ↔ accessLevelId
(matcheando por área y schedule)
  end

  rect rgba(52, 211, 153, 0.08)
    Note over SGH,INT: FASE 5 — Lectura de Empleados
    INT->>SGH: GET /empleados — Con asignación
de servicio y cliente
    SGH-->>INT: Lista de empleados
(datos, foto, servicioId, clienteId)
  end

  rect rgba(167, 139, 250, 0.08)
    Note over INT,HIK: FASE 6 — Sincronizar Personas + Rostros + Asignar Access Levels
    loop Por cada empleado
      INT->>INT: Resolver: empleado.servicioId
→ groupId del sub-grupo
      INT->>HIK: POST /persons — Crear persona
(nombre, employeeNo, groupId)
      HIK-->>INT: 200 OK — personId
      INT->>HIK: POST /persons/faceUrl — Registrar rostro
      HIK-->>INT: 200 OK
      INT->>INT: Resolver: servicio+turno
→ accessLevelId (de la tabla del paso 4)
      INT->>HIK: POST /accesslevel/person/add
Asignar Access Level al empleado
      HIK-->>INT: 200 OK
      INT->>INT: Guardar mapeo: empleadoId ↔ personId
    end
  end

  Note over HIK: HikConnect sincroniza
credenciales faciales a dispositivos

Secuencia — Fichaje y Procesamiento de Desvíos

Desde que el empleado ficha en un dispositivo hasta que OnOff registra la asistencia o genera una novedad comparando contra la planificación de SGH.

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1e293b', 'primaryTextColor': '#e4e8f1', 'primaryBorderColor': '#4e8cff', 'lineColor': '#4e8cff', 'secondaryColor': '#1c2230', 'tertiaryColor': '#151921', 'noteBkgColor': '#1c2230', 'noteTextColor': '#e4e8f1', 'noteBorderColor': '#2a3142', 'actorBkg': '#1e293b', 'actorTextColor': '#e4e8f1', 'actorBorder': '#4e8cff', 'activationBkgColor': '#1e293b', 'activationBorderColor': '#4e8cff' }}}%%

sequenceDiagram
  autonumber
  participant DEV as 📷 Dispositivo
CLI-001-CAM-NORTE-01
  participant HIK as 🔐 HikConnect
  participant INT as ⚡ Integración
  participant ONOFF as 📊 OnOff
  participant SGH as 🏢 SGH

  rect rgba(78, 140, 255, 0.08)
    Note over DEV,HIK: FICHAJE
    DEV->>HIK: Reconocimiento facial exitoso
(evento de acceso generado)
  end

  rect rgba(167, 139, 250, 0.08)
    Note over HIK,INT: CAPTURA — Polling de eventos
    loop Cada 30 segundos
      INT->>HIK: POST /events — Consultar eventos
(eventType=196893)
      HIK-->>INT: Eventos: employeeNo, timestamp,
deviceName, dirección
    end
    INT->>INT: Resolver desde evento:
• employeeNo → empleadoId (mapper)
• deviceName "CLI-001-..." → clienteId
• deviceId → áreaId → servicioId
  end

  rect rgba(245, 158, 11, 0.08)
    Note over INT,SGH: PROCESAMIENTO en OnOff
    INT->>ONOFF: POST /fichajes
(empleadoId, timestamp,
clienteId, servicioId, dirección)
    ONOFF->>SGH: GET /planificacion/{empleadoId}/{fecha}
    SGH-->>ONOFF: Turno: 08:00–16:00
Servicio: Vigilancia Norte
Cliente: CLI-001

    ONOFF->>ONOFF: Comparar fichaje vs planificación

    alt Todo OK
      ONOFF->>ONOFF: ✅ Asistencia registrada
    else Tardanza
      ONOFF->>ONOFF: ⚠️ Llegada tardía
08:23 vs 08:00
    else Servicio/puesto incorrecto
      ONOFF->>ONOFF: ⚠️ Fichó en servicio
distinto al planificado
    else Cliente incorrecto
      ONOFF->>ONOFF: 🔴 Fichó en dispositivo
de otro cliente
    else Sin fichaje
      ONOFF->>ONOFF: 🔴 Ausencia
(proceso batch)
    end

    ONOFF-->>INT: ACK — Fichaje procesado
  end

Secuencia — Cambios (Nuevo Servicio / Reasignación)

Cuando SGH tiene cambios, la integración los refleja en HikConnect. Si el cambio requiere un nuevo Access Level, un administrador debe crearlo en HCC/HCT antes de que la integración pueda asignarlo.

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1e293b', 'primaryTextColor': '#e4e8f1', 'primaryBorderColor': '#4e8cff', 'lineColor': '#4e8cff', 'secondaryColor': '#1c2230', 'tertiaryColor': '#151921', 'noteBkgColor': '#1c2230', 'noteTextColor': '#e4e8f1', 'noteBorderColor': '#2a3142', 'actorBkg': '#1e293b', 'actorTextColor': '#e4e8f1', 'actorBorder': '#4e8cff', 'activationBkgColor': '#1e293b', 'activationBorderColor': '#4e8cff' }}}%%

sequenceDiagram
  autonumber
  participant ADMIN as 👤 Admin HCC/HCT
  participant SGH as 🏢 SGH
  participant INT as ⚡ Integración
  participant HIK as 🔐 HikConnect API

  rect rgba(52, 211, 153, 0.08)
    Note over SGH,HIK: CASO A — Nuevo servicio/puesto para cliente existente
    INT->>SGH: Sync detecta nuevo servicio
    SGH-->>INT: Servicio: "Vigilancia Sur"
de cliente CLI-001
    INT->>INT: Resolver: CLI-001 → groupId padre
    INT->>HIK: POST /orgs — Crear sub-grupo
(parentId: grupo CLI-001)
    HIK-->>INT: 200 OK — groupId (servicio)
    INT->>HIK: POST /areas — Crear área
"Puesto Recepción Sur"
    HIK-->>INT: 200 OK — areaId
    INT->>HIK: POST /areas/devices — Asignar
CLI-001-CAM-SUR-01
    HIK-->>INT: 200 OK
    INT->>INT: Guardar mapeos nuevos
  end

  rect rgba(248, 113, 113, 0.08)
    Note over ADMIN,HIK: PREREQUISITO — Admin crea Access Level para nuevo servicio
    ADMIN->>HIK: Crear Access Level en HCC/HCT
("Vig. Sur — Turno Mañana"
= nueva área + timeSchedule existente)
    Note over ADMIN: Sin este paso, la integración
no puede asignar permisos
para el nuevo servicio.
    INT->>HIK: POST /accesslevel/list — Re-listar
Access Levels actualizados
    HIK-->>INT: Lista actualizada con nuevo
Access Level para Vig. Sur
    INT->>INT: Actualizar tabla de mapeo:
servicio "Vig. Sur" + turno ↔ nuevo accessLevelId
  end

  rect rgba(167, 139, 250, 0.08)
    Note over SGH,HIK: CASO B — Empleado cambia de servicio
    INT->>SGH: Sync detecta reasignación
    SGH-->>INT: Empleado #1234:
Vigilancia Norte → Vigilancia Sur
    INT->>INT: Resolver Access Levels:
Norte → accessLevelId_A
Sur → accessLevelId_B
    INT->>HIK: POST /accesslevel/person/delete
Remover Access Level A (Norte)
    HIK-->>INT: 200 OK
    INT->>HIK: POST /accesslevel/person/add
Asignar Access Level B (Sur)
    HIK-->>INT: 200 OK
    INT->>HIK: PUT /persons — Actualizar groupId
(mover al sub-grupo del nuevo servicio)
    HIK-->>INT: 200 OK
    Note over HIK: Dispositivos de "Vigilancia Sur"
ahora reconocen al empleado
  end

Punto de atención: Cada vez que se agrega un nuevo servicio/puesto en SGH que requiere una combinación de área + horario que no existe como Access Level, un administrador debe crear ese Access Level manualmente en HCC/HCT antes de que la integración pueda asignar empleados. Se recomienda implementar una alerta en la integración cuando detecta un servicio+turno sin Access Level mapeado.