Eventos de Identificação Online

Quando uma tentativa de identificação ocorre, os eventos descritos abaixo são enviados automaticamente pelo equipamento conforme o modo de operação online em que ele estiver: Modo Pro ou Modo Enterprise. Cabe ao servidor externo tratar esses eventos.

Evento imagem biométrica

Tentativa de identificação por biometria.

O método HTTP usado é o POST. O contentType é application/octet-stream. Todos os parâmetros são enviados através da query string, exceto o binário da imagem.

Este evento é enviado quando o equipamento opera em Modo Enterprise, ou seja, quando a configuração local_identification estiver desativada, e apenas se a configuração extract_template estiver desativada.

POST /new_biometric_image.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (wiegand, RFID, biometria), vide Formatação identifier_id.
• width (int) : Largura, em pixels, da imagem enviada.
• height (int) : Altura, em pixels, da imagem enviada.
• session (string) : Número da sessão.
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.
• uuid (string) : Identificador Único Universal.
• variance (int) : Parâmetro de qualidade na identificação biométrica.
• imagem (binário (octet-stream)) : Imagem da digital em formato binário. É enviado 1 byte por pixel, em escala de cinza (Este é o único parâmetro enviado no corpo da mensagem).

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento template biométrica

Tentativa de identificação por biometria.

O método HTTP usado é o POST. O contentType é application/octet-stream. Todos os parâmetros são enviados através da query string, exceto o binário do template.

Este evento é enviado quando o equipamento opera em Modo Enterprise, ou seja, quando a configuração local_identification estiver desativada, e apenas se a configuração extract_template estiver ativada.

POST /new_biometric_template.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (wiegand, RFID, biometria), vide Formatação identifier_id.
• session (string) : Número da sessão.
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.
• uuid (string) : Identificador Único Universal.
• variance (int) : Parâmetro de qualidade na identificação biométrica.
• Template (binário (octet-stream)) : Template biométrico no formato Innovatrics (Este é o único parâmetro enviado no corpo da mensagem).

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento cartão de proximidade

Tentativa de identificação por cartão de proximidade.

O método HTTP usado é o POST. O contentType é application/x-www-form-urlencoded. Todos os parâmetros são enviados através da query string.

Este evento é enviado quando o equipamento opera em Modo Enterprise, ou seja, quando a configuração local_identification estiver desativada.

POST /new_card.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (wiegand, RFID, biometria), vide Formatação identifier_id.
• card_value (int 64) : Número do cartão.
• panic (int) : Indica se é cartão de pânico (1) ou não (0).
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.
• uuid (string) : Identificador Único Universal.
• block_read_error (int 64) : Quando diferente de 0, indica que um erro de leitura do bloco ocorreu. Só será preenchido quando mifare->read_block for não vazio.
• block_read_data (string) : Dados lidos do bloco em hexadecimal (Não é possível incluir base64 em uma URL sem escapar alguns caracteres). Só será preenchido quando mifare->read_block for não vazio.

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento QR Code

Tentativa de identificação por QR Code.

O método HTTP usado é o POST. O contentType é application/x-www-form-urlencoded. Todos os parâmetros são enviados através da query string.

Este evento é enviado quando o equipamento opera em Modo Enterprise, ou seja, quando a configuração local_identification estiver desativada.

Observação: O equipamento irá enviar o evento de QR Code quando o parâmetro qrcode_legacy_mode_enabled (do módulo barras para linha V5 e face_id da linha V6) estiver configurado em 0. Caso qrcode_legacy_mode_enabled esteja definido em 1, leituras de QR Code serão interpretadas da mesma forma como leituras de cartão.

POST /new_qrcode.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (Wiegand, RFID, biometria, etc), vide Formatação identifier_id.
• qrcode_value (string) : Número do QR Code.
• uuid (string) : Identificador Único Universal.
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento UHF tag

Tentativa de identificação por UHF tag.

O método HTTP usado é o POST. O contentType é application/x-www-form-urlencoded. Todos os parâmetros são enviados através da query string.

Este evento é enviado quando o equipamento opera em Modo Enterprise, ou seja, quando a configuração local_identification estiver desativada.

POST /new_uhf_tag.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (Wiegand, RFID, biometria, etc), vide Formatação identifier_id.
• uhf_tag (string) : Valor lido pela tag UHF
• uuid (string) : Identificador Único Universal.
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento id e senha

Tentativa de identificação por id e senha.

O método HTTP usado é o POST. O contentType é application/x-www-form-urlencoded. Todos os parâmetros são enviados através da query string.

Este evento é enviado quando o equipamento opera em Modo Enterprise, ou seja, quando a configuração local_identification estiver desativada.

POST /new_user_id_and_password.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (wiegand, RFID, biometria), vide Formatação identifier_id.
• user_id (int) : ID informado pelo usuário.
• password (string) : Senha informada pelo usuário.
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.
• uuid (string) : Identificador Único Universal.

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento usuário identificado

Quando o usuário se identifica no equipamento, este executa a identificação de forma local e envia o ID do usuário identificado ao servidor. Então, o servidor deve processar suas regras de acesso e conceder ou não autorização.

Repare que, por este método, o servidor precisa sempre manter atualizados os usuários e seus dados biométricos no equipamento, estando sujeito à limitação de registros existente nele. Esta limitação é descrita no tópico Limitação do número de templates.

O método HTTP usado é o POST. O contentType é application/x-www-form-urlencoded. Todos os parâmetros são enviados através da query string.

Este evento é enviado quando o equipamento opera em Modo Pro, ou seja, quando a configuração local_identification estiver ativada.

POST /new_user_identified.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• identifier_id (int) : ID do identificador (wiegand, RFID, biometria), vide Formatação identifier_id.
• component_id (int) : ID do componente que realizou a identificação (exclusivo para iDBlock Next), vide Formatação identifier_id.
• event (int) : Evento do resultado da identificação, (e.g.: 3 para não identificado).
• user_id (int) : ID do usuário.
• duress (int) : Esse parâmetro retorna um inteiro que indica se é dedo do pânico ou uma simples identificação (1 ser for dedo de pânico ou 0 para identificação comum).
• face_mask (bool) : Esse parâmetro retorna "true" se o usuário identificado está usando máscara ou retorna "false" caso contrário.
• time (int) : Momento do acesso em Unix Timestamp.
• portal_id (int) : Identificador do portal.
• uuid (string) : Identificador Único Universal.
• block_read_data (string) : Valor lido do bloco indicado do cartão (apenas para MIFARE, quando habilitado).
• block_read_error (int) : Indica se houve erro na leitura do bloco do cartão (apenas para MIFARE, quando habilitado).
• card_value (int) : Valor do cartão utilizado.
• qrcode_value (string) : Valor do QR Code utilizado.
• uhf_tag (string) : Valor lido pela tag UHF
• pin_value (string) : Valor do PIN utilizado.
• user_has_image (int) : Indica se o usuário possui imagem (1) ou não (2).
• user_name (string) : Nome do usuário
• password (string) : Senha informada pelo usuário.
• confidence (int) : Parâmetro confidence da identificação facial.
• log_type_id (int) : Envia um identificador de tipo de batida sempre que houver um evento de identificação online.

Resposta

• result (Objeto JSON) : Descrito em Mensagem de Retorno.

Evento acesso por botoeira

Indica um acesso por meio de acionamento de botoeira.

O método HTTP usado é o POST. O contentType é application/json. Todos os parâmetros enviados estão disponíveis no corpo da mensagem (JSON).

Este evento é enviado quando o equipamento opera em Modo Online, ou seja, Modo Enterprise ou Modo Pro.

POST /new_rex_log.fcgi

Parâmetros

• device_id (int 64) : ID único do equipamento.
• rex_log (Objeto JSON) : Objeto com os parâmetros abaixo:
• • time (int) : Horário da ocorrência em Unix Timestamp.
• • event (int) : Evento da abertura (11 para acesso através de botoeira).
• • user_id (int 64) : ID do usuário.
• • portal_id (int 64) : ID do portal correspondente.

Resposta

É esperada uma resposta vazia (HTTP Status code OK).

Formatação identifier_id

O campo identifier_id está presente nas mensagens de evento de identificação enviadas pelo terminal de acesso. Ele contém um id que representa o mecanismo identificador (wiegand, RFID, biometria, etc) utilizado, e deve ser interpretado da seguinte forma:

O tipo do dado é inteiro de 32 bits. Os três bytes mais significativos devem ser interpretados como caracteres ASCII enquanto o último byte deve ser interpretado como valor inteiro.

Exemplo:

• "w" = 0x77 (ASCII)
• "i" = 0x69 (ASCII)
• "n" = 0x6E (ASCII)
• "0" = 0x00 (Binário)

O valor "win0" representa Wiegand zero. Sua conversão para o formato descrito acima produz o valor 0x77696E00 em hexadecimal e se torna 2003398144 em base decimal.

Solicitar imagem de usuário ao servidor

O equipamento irá solicitar a foto do usuário para o servidor sempre que na resposta dos eventos de identificação o parâmetro user_image for true (indicando que o usuário possui foto).

O método HTTP usado é o GET. O contentType é application/octet-stream. Todos os parâmetros são enviados através da query string.

GET /user_get_image.fcgi

Parâmetros

• user_id (int) : ID do usuário.

Resposta

• imagem (octet-stream) : Foto do usuário requisitado nos formatos BMP, JPG/JPEG ou PNG;

Verifica disponibilidade do servidor

Se o equipamento não conseguir se comunicar com o servidor por três tentativas seguidas, ele entrará em modo de contingência. O número de tentativas é um parâmetro configurável.

Neste modo, todas as identificações passam a ser feitas utilizando unicamente os registros locais do equipamento, que, para tanto, devem estar atualizados.

A cada minuto, o equipamento envia uma nova requisição POST/device_is_alive ao servidor com o número de logs disponíveis no corpo da mensagem (JSON). Assim que obtiver uma resposta (HTTP status code OK), ele voltará a seu modo de operação original.

O método HTTP usado é o POST. O contentType é application/json.

POST /device_is_alive.fcgi

Parâmetros

• access_logs (int) : Número de logs disponíveis.

Resposta

É esperada uma resposta vazia (HTTP Status code OK).

Mensagem de Retorno

Mensagem de retorno do servidor para o equipamento após um evento de tentativa de identificação.

result

Resultado da análise da tentativa de identificação.

Campo	Tipo	Descrição
event	int	Tipo do evento, pode ser: Equipamento inválido Parâmetros de identificação inválidos Não identificado Identificação pendente Tempo de identificação esgotado Acesso negado Acesso concedido Acesso pendente (usado quando o acesso depende de mais de uma pessoa) Usuário não é administrador (usado quando um usuário tenta acessar o menu mas não é administrador) Acesso não identificado (quando o portal é aberto através da API e o motivo não é informado) Acesso por botoeira Acesso pela interface web Desistência de entrada (exclusivo para iDBlock) Sem resposta (nenhuma ação é tomada) Acesso pela interfonia (exclusivo para iDFace)
user_id	int	ID do usuário, em caso de identificação.
user_name	string	Nome do usuário, em caso de identificação.
user_image	bool	Usuário identificado possui ou não foto.
user_image_hash	string	Caso o usuário identificado possua imagem, envia o hash (SHA1) da mesma.
portal_id	string	ID do portal correspondente.
actions	Array de Objetos JSON	Ações que devem ser executas pelo equipamento. Exemplo: [ {"action":"door", "parameters":"door=1"}, {"action":"door", "parameters":"door=2"} ]
duress	int	Indica se é dedo do pânico ou uma simples identificação (1 ser for dedo de pânico ou 0 para identificação comum).
message	string	Mensagem a ser exibida no display no momento do acesso.

Exemplos de respostas

Resposta para os dispositivos iDAccess, iDFit e iDBox

Autoriza um acesso:

{
    "result": {
        "event": 7,
        "user_id": 6,
        "user_name": "Neal Caffrey",
        "user_image": false,
        "portal_id": 1,
        "actions":[
            {"action": "door", "parameters": "door=1"},
            {"action": "door", "parameters": "door=2"}
        ]
    }
}

Resposta para os dispositivos iDFlex, iDAccess Pro e iDAccess Nano

Autoriza um acesso:

{
    "result": {
        "event": 7,
        "user_id": 6,
        "user_name": "Neal Caffrey",
        "user_image": false,
        "portal_id": 1,
        "actions": [
            {"action": "sec_box", "parameters": "id=65793, reason=1"}
        ]
    }
}

Nota: O parâmetro reason, define o motivo de abertura (0 = Desconhecido, 1 = Autorizado, 2 = Botoeira e 3 = Comando WEB).

Resposta específica para a catraca iDBlock

Autoriza um acesso:

{
    "result": {
        "event": 7,
        "user_id": 6,
        "user_name": "Danny Boy",
        "user_image": false,
        "portal_id": 1,
        "actions": [
            {"action": "catra", "parameters": "allow=clockwise"}
        ]
    }
}

Nota: O parâmetro "clockwise" abre a catraca no sentido horário. Outros valores possíveis são "anticlockwise" ou "both" que abrem a catraca no sentido anti-horário ou ambos, respectivamente.