Manual Integración CAIF

Criada por Juan José Gómez, Modificado em Qui, 26 Out, 2023 na (o) 6:19 PM por Juan José Gómez

Resumen

Este manual explica los requerimientos y el proceso de integración entre los sistemas de control de acceso de interlaken y el sistema de gestión de un cliente.

1. Glosario

Cliente: Empresa contratante del ERP y de CAIF.

CAIF: Sistema para gestionar el control de acceso de IntegraFácil.

ERP (Enterprise Resource Planning): Sistema de gestión usado por el cliente.

2. Comunicación (API HTTP y Webhooks)

IntegraFácil usa una API HTTP en nuestro servidor en la internet, todo es realizado con peticiones HTTP (Get, Post, etc).

Para integraFácil comunicar com su aplicación, consumimos endpoints de su API cuando sea necesario; un ejemplo de uso es cuando un usuario se identifica en uno de nuestros dispositivos, hacemos una llamada con los datos de usuario/dispositivo y esperamos una respuesta confirmando el acceso. Otro ejemplo es el envío de logs (registros) de accesos realizados.

3. Integración

La Integración entre los sistemas es realizada a través del identificador del alumno, nombre y foto. Esos datos son entregados y mantenidos por el ERP y el sistema de control de acceso (CAIF) no los altera. Todos los datos generados por CAIF son vinculados al ID del aluno.

Fig 1. Fujo de integración entre CAIF e ERP del cliente.

Fig 2. Interfaz del sistema de control de acceso - CAIF

3.1. Endpoints para consulta

El integrador debe proporcionar cuatro (4) endpoints para consulta:

Obtener lista de nombres por parte del nombre.
Obtener nombre y foto por id del alumno.
Obtener status de liberación por grupo de dispositivo.
Obtener lista de Id de alumnos por id de la unidad y del gimnasio.

3.1.1. Obtener lista de nombres por parte del nombre

Usado para obtener nombre y foto por parte del nombre.

http://suwebservice/person?name={{name}}&idUnidade={{idUnidade}}

Respuesta:

Status code: 200

[
      {personName:"user A", usuarioID: 1, "photoUrl": "http://dirección/foto.jpg"},
      {personName:"user B", usuarioID: 2, "photoUrl": "http://dirección/foto.jpg"},
      {personName:"user C", usuarioID: 3, "photoUrl": "http://dirección/foto.jpg"},
      {personName:"user D", usuarioID: 4, "photoUrl": "http://dirección/foto.jpg"},
      …
 ]

3.1.2. Obtener nombre y foto por id del alumno

Usado para obtener nombre y foto por id del alumno.

http://suwebservice/person?usuarioID={{usuarioID}}&idUnidade={{idUnidade}}

Respuesta:

Status code: 200

{
      "personName": "User name xxxx",
      "usuarioID": 100,
      "photoUrl": “http://direccion/de/la/foto.jpg”,      
 }

3.1.3. Obtener status de liberación por grupo de dispositivo

Usado para obtener status de liberación por grupo de dispositivo.

http://suwebservice/person?usuarioID={{usuarioID}}&grupoDispositivo={{gupo}}&IdAcademia={{idAcademia}}&idUnidade={{idUnidade}}

Respuesta:

Status code: 200

{
      "usuarioID": 100,
      "released": true,
      "dueDate”: "2022-12-31",
      "personName": "User name xxxx",
      "photoUrl": “http://direccion/de/la/foto.jpg”,
 }

3.1.4. Obtener lista de Id de alumnos por id de la unidad y del gimnasio

Usado para obtener lista de IDs de alumnos por id de la unidad o sede.

http://suwebservice/person?IdAcademia={{idAcademia}}&idUnidade={{idUnidade}}

Respuesta:

Status code: 200

[
      {usuarioID: 1},
      {usuarioID: 2},
      {usuarioID: 3},
      {usuarioID: 4},
      …
 ]

3.1. Endpoints para recibimiento de Logs (registros)

Aunque no sea obligatorio, es recomendable proporcionar un endpoint para recibir los logs de acceso, lo que permitirá al ERP la contabilización de los mismos. Como nuestro sistema funciona de la misma manera sin internet, el ERP tendrá acceso también a los logs generados mientras el gimnasio estaba sin internet.

Los logs son generados en la identificación biométrica o en la lectura de un dispositivo (QRCode o RFID). En caso de que el dispositivo sea un torniquete también consta en el log la información sobre el giro.

3.2.1. Log de identificación digital exitosa

Eso es lo que el cliente recibirá:

"id": "000000000000005578332020-08-19T18:22:21Z",
  "numeroSerie": "049226c597c8",
  "grupo": "turnstile",
  "identificacao": {
    "horario": "2020-08-19T18:22:21Z",
    "dispositivo": "finger",
    "numeroSerie": "557833",
    "usuarioId": "200",
    "convidado": false
  },
  "cliente": {
    "url": "http://192.168.0.5:8000/log",
    "recebimentos": [
      
    ]
  },
  "pgProcessamento": {
    "horario": "2020-08-19T18:22:21Z",
    "response": "{\"text\":\"text to turnstile\",\"clockwiseFree\":true,\"counterclockwiseFree\":false,\"accessTime\":10000,\"msgToReception\":\"msg to reception\"}",
    "cacheUsado": false
  },
  "giro": {
    "horario": "2020-08-19T18:22:26Z",
    "sentido": "antiHorario",
    "direcao": "entrada"
  },
  "motivoLiberacaoManual": "",
  "processamentos_json": null,
  "liberaCatraca": {
    "texto": "text to turnstile",
    "sentidoHorarioLiberado": true,
    "sentidoAntiHorarioLiberado": false,
    "liberacaoTempo": 10000,
    "semComando": false,
    "msgRecepcao": "msg to reception",
    "senha": null,
    "nomeCatraca": "Catraca1",
    "grupoCatracas": "turnstile",
    "nsPLC": "049226c597c8"
  }
}

3.2.2. Log de identificación facial exitosa

Eso es lo que el cliente recibirá:

{
  "id": "00000000049226c597c82020-08-19T18:28:21Z",
  "numeroSerie": "049226c597c8",
  "identificacao": {
    "horario": "2020-08-19T18:28:21Z",
    "dispositivo": "interface",
    "numeroSerie": "049226c597c8",
    "usuarioId": "200",
    "convidado": false
  },
  "cliente": {
    "url": "http://192.168.0.5:8000/log",
    "recebimentos": [
      
    ]
  },
  "pgProcessamento": {
    "horario": "2020-08-19T18:28:21Z",
    "response": "{\"text\":\"text to turnstile\",\"clockwiseFree\":true,\"counterclockwiseFree\":false,\"accessTime\":10000,\"msgToReception\":\"msg to reception\"}",
    "cacheUsado": false
  },
  "giro": {
    "horario": "2020-08-19T18:28:28Z",
    "sentido": "antiHorario",
    "direcao": "entrada"
  },
  "motivoLiberacaoManual": "",
  "processamentos_json": null,
  "liberaCatraca": 
 “msg to reception",
    "senha": null,
    "nomeCatraca": "Catraca1",
    "grupoCatracas": "turnstile",
    "nsPLC": "049226c597c8"
  }
}

4. Endpoint para recibimiento de logs de registros biométricos (facial y digital) - opcional

Es posible recibir registros biométricos de huellas digitales y rostro de una persona. Para ello, se recomienda proporcionar un endpoint para recibir este tipo de registro. Esto permitirá que el ERP mantenga una copia de seguridad de los datos biométricos y, si es necesario, reutilizarlos en una posible restauración de datos locales del servidorIF, o una migración de los datos de la persona a otro servidorIF.

4.1. Log de registro de template facial

Eso es lo que el cliente recibirá:

{
  "type": "faceEnrollLog",
  "id": "a2cc0e5e-75df-4186-9a80-bcf883afc6ab",
  "personId": "2",
  "clientUrlLog": "http://localhost:8000/logs",
  "clientUrlLogHttpMethod": "post",
"clientUrlLogHeader":'{"Content-Type": "application/json;charset=utf-8;", "Authorization": "Token{{token}}","tenant": "{{tenant}}" }',
  "clientUrlLogError": null,
  "clientUrlLogReceived": null,
  "needsSync": true,
  "photoBase64": "/9j/....//Z",
  "webSrvIFReceived": null,
  "webSrvIFError": null,
  "createdAt": "2022-10-18T14:50:11.000Z",
  "updatedAt": "2022-10-18T14:50:11.000Z",
}

4.2. Log de registro de template digital

Eso es lo que el cliente recibirá:

{
  "type": "fingerEnrollLog",
  "id": "fas1d5b6-75df-4186-9a80-bcf883afc555",
  "personId": "2",
  "serialNumber": "123456",
  "fingerIdx": 6,
  "clientUrlLog": "http://localhost:8000/logs",
  "clientUrlLogHttpMethod": "post",
"clientUrlLogHeader":'{"Content-Type": "application/json;charset=utf-8;", "Authorization": "Token{{token}}","tenant": "{{tenant}}" }',
  "clientUrlLogError": null,
  "clientUrlLogReceived": null,
  "needsSync": true,
  "template": "/9j/....//Z",
  "webSrvIFReceived": null,
  "webSrvIFError": null,
  "createdAt": "2022-10-18T15:51:11.000Z",
  "updatedAt": "2022-10-18T15:51:11.000Z",
}

5. Simulador

El simulador de acceso es una opción incluída en el servidorIF, disponible en el siguiente link:

https://if-instaladores.s3.amazonaws.com/servidorIF/servidorIF.zip

Una vez descomprimido y ejecutado como ADM el servidorIF registra el puerto 8080, y es posible abrir su interfaz por el navegador en http://localhost:8080

En la esquina superior derecha están los botones, Configurações y Simulador. Clicar em Simulador.

Fig 3. Acceso al simulador de dispositivos.

En Configurações son definidos los endpoints del cliente. En Simulador es probado el tipo de control de acceso y en Resultado es mostrada la respuesta del sistema del cliente.

Configurações > URL es el endpoint del cliente a ser llamado cuando alguiem se identifica en el torniquete. Permite customizar opciones de la llamada HTTP.

Simulador > Info recibe el código del alumno a ser verificado.


Nota: El botón Executar va a mostrar las informaciones de request y response, mientras que el botón Executar (Simular Catraca) va a direccionar el response del sistema del cliente para el simulador. Caso sea liberado uno o ambos  sentidos, se va a mostrar en verde y clicando es posible simular el giro.