Introdução à API - API Linha de Acesso
Este documento tem como finalidade apresentar as diferentes formas de integração com os equipamentos da linha de acesso da Control iD, por exemplo, para cadastro de usuários, identificação, consulta a registros etc. Os dispositivos de acesso da Control iD oferecem uma interface de comunicação moderna (API - Application Programming Interface) baseada em TCP/IP (Ethernet) com uma arquitetura REST. Sendo assim, a integração é simples e independente do sistema operacional e linguagem de programação utilizados. São oferecidos dois modos de funcionamento para a API: Autônomo(standalone) e Centralizado(Enterprise), todos em API REST.
No repositório GitHub da Control iD estão disponíveis exemplos de código nas linguagens:
https://github.com/controlid/integracao/tree/master/Controle%20de%20Acesso
A maior parte dos exemplos dessa documentação são escritos em JavaScript, utilizando a biblioteca jQuery. Para testá-los, acesse o endereço IP do equipamento em um navegador web e use as ferramentas do desenvolvedor (developer tools) deste para realizar requisições. Todos os exemplos fornecidos podem ser verificados copiando seus códigos e colando no console das ferramentas de desenvolvimento, além disso muitos exemplos de requisições estão disponíveis em nossa coleção compartilhada através do Postman:
Exemplos dos requests HTTP:
https://documenter.getpostman.com/view/7260734/S1LvX9b1?version=latest
Modo Standalone
Este é o modo de operação recomendado pelo Control iD.
Neste modo de funcionamento o equipamento precisa que a sua base de dados seja configurada com todas as informações que ele precisa para funcionar, isto é, cadastro de usuários, biometrias/cartões e regras de acesso. Para fazer isso basta realizar o request diretamente para a API do equipamento, portanto a informação é sempre enviada do servidor para o equipamento em uma única direção.
Modo Enterprise
Se a solução é desenvolvida com o modo enterprise dos equipamentos, ou seja, a lógica estará no servidor ou parcialmente no servidor, neste modo a comunicação ocorre em ambos os sentidos o equipamento aceita que seja realizado requests para ele e o equipamento também realiza POSTS no Servidor para uma URL especifica e existem duas formas de implementar esse modo:
Apenas leitura da digital no equipamento. Neste modo, quando o usuário coloca o dedo no equipamento, este envia apenas a 'foto' da digital para o servidor, cabendo a ele usar QUALQUER algoritmo biométrico de sua preferência para fazer a extração e o matching. Tratamento biométrico: totalmente no servidor
Leitura, extração e matching no equipamento. Neste modo, quando o usuário coloca o dedo no equipamento, este lê o dedo e encontra o usuário correspondente no seu banco de dados local, enviando o ID do usuário ao servidor. O servidor processa as regras de acesso e diz se deve abrir a porta ou não. Repare que neste método o servidor tem que sempre atualizar os usuários e biometrias no equipamento, tendo a limitação de templates por equipamento conforme descrito no tópico Limitação do número de templates. Tratamento biométrico: totalmente no equipamento.
Em ambos os modos de operação descritos acima, para se monitorar eventos assíncronos será necessário utilizar os serviços disponibilizados pelo Monitor.
Os eventos assíncronos que podem ser monitorados são: alteração nos logs de acesso e logs de alarme, cadastro remoto de cartão e biometria, giros de catraca, abertura de portas e mudanças no modo de operação (ex. entrar e sair em modo standalone/enterprise/contingência).
Nesse modo de funcionamento o equipamento inicia a comunicação, isto é, o equipamento faz uma requisição HTTP ao servidor para verificar se há algum comando para ser executado. Se receber uma resposta vazia, significa que não há nada para fazer, e depois de um certo período de tempo, o equipamento faz novamente a requisição. Caso contrário, o equipamento executa o comando e faz uma outra requisição enviando o resultado da operação. Essa requisição recebe uma resposta vazia, e logo em seguida faz uma outra requisição de push. Informações sobre o modo Push.