Manual Integración CAIF

Criada por Juan José Gómez, Modificado em Seg, 24 Fev na (o) 12:48 PM por Juan José Gómez

Resumen

Este manual explica os requerimentos e o processo de integração entre os sistemas de controle de acesso da interlaken e o sistema de gestão de um cliente.

1. Glosario

Cliente: Empresa contratante de ERP y de CAIF.

CAIF: Sistema para administrar el control de acesso de IntegraFácil.

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

2. Comunicación (API HTTP y Webhooks)

IntegraFácil se comunica via API HTTP, permitiendo una integración directa entre nuestros dispositivos e su aplicación.

Cuando un usuario se identifica en uno de nuestros dispositivos, enviamos una solicitud a su API que contiene los datos del usuario y del dispositivo. Esperamos una respuesta para confirmar o denegar el acceso.

Además, nuestra API también permite el envío de registros de acceso, garantizando el registro y seguimiento de las actividades.

3. Integración

La integración entre sistemas se produce a través del identificador, el nombre y la foto del asociado, los cuales son proporcionados y mantenidos por el ERP. El sistema de control de acceso (CAIF) sólo utiliza estos datos, sin modificarlos.

Todos los registros generados por CAIF están vinculados al identificador único del estudiante, garantizando la trazabilidad y consistencia en las operaciones.

Fig 1. Flujo de integración entre CAIF y el ERP del cliente

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

3.1. Endpoints para consulta

El integrador debe proporcionar cuatro endpoints para consulta:

Buscar nombres por término parcial – Retorna una lista de asociados cuyo nombre contiene el término dado.
Obtener datos del asociado por ID – Retorna nombre y foto del asociado según su identificador único
Consultar status de liberación por grupo de dispositivos – verifica si un grupo determinado de dispositivos tiene permiso de acceso.
Listar IDs de alunos por Gimnasio y unidad – Retorna los identificadores de los associados de uma unidade específica.

Nota: Las siguientes URL son sólo a modo de ejemplo, su estructura es defida por el cliente.

3.1.1. Buscar nombres por término parcial

Usado para obtener nombre y foto por término parcial.

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"
  },
...
]

3.1.2. Obtener datos del asociado por ID

Usado para obtener nombre y foto por ID del asociado.

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

Resposta:

Status code: 200

{
   "personName":"User name xxxx",
   "usuarioID":100,
   "photoUrl":"https://url-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}}

Resposta:

Status code: 200

{
   "usuarioID":100,
   "released":true,
   "dueDate":"2022-12-31",
   "personName":"User Name",
   "photoUrl":"https://url-da-foto.jpg"
}

3.1.4. Listar Ids de alumnos por Gimnasio y unidade

Usado para obtener una lista de IDs de asociados por el identificador de la sede o unidad.

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

Resposta:

Status code: 200

[      
   {
   "usuarioID":1
   },
   {
   "usuarioID":2
   },
   {
   "usuarioID":3
   },
...
]

3.2. Endpoint para para recibir registros de acceso

Aunque no es obligatorio, se recomienda proporcionar un endpoint para recibir registros de acceso. Esto permite que el ERP contabilize los registros y realice un seguimiento del historial de acceso.

Como nuestro sistema funciona normalmente sin conexión a Internet, los registros generados durante los períodos offline se sincronizarán cuando se restablezca la conexión, lo que garantiza que el ERP tenga acceso a todos los registros.

Los registros son generados para diferentes tipos de identificación, incluida la biometría, la lectura de códigos QR y RFID. En el caso de dispositivos como los torniquetes, los logs también registran la rotación del mecanismo.

3.2.1. Log de identificación digital exitoso

Esto es lo que recibirá el cliente:


{
   "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 exitoso

Esto es lo que recibirá el cliente:

{
   "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":"Catraca 1",
   "grupoCatracas":"turnstile",
   "nsPLC":"049226c597c8"
}

4. Endpoint para recepción de datos biométricos (faciales y dactilares) – opcional

Es posible recibir registros biométricos de las huellas dactilares y el rostro de un asociado. Proporcionar un endpoint para enviar estos datos permitirá que el ERP mantenga una copia de respaldo.

Esta copia de seguridad puede ser útil para restaurar datos locales en el servidor IF si es necesario, o para migrar información biométrica del usuario a otro servidor IF sin pérdida de datos.

4.1. Log de registro de template facial

Esto es lo que recibirá el cliente:

{
   "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

Esto es lo que recibirá el cliente:

{
   "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"
}