Descrição dos comandos listados no Manual do Leitor Facial.
Registro do Dispositivo
reg
Descrição: Este comando é enviado pelo dispositivo ao se conectar ao aplicativo através do WebSocket. O leitor informa ao aplicativo os dados de identificação e configurações dele.
Tipo: Recebimento (enviado pelo dispositivo).
Formato da mensagem
{
"cmd": "reg",
"sn": "1234567890",
"devinfo":
{
"modelname": "AiFace",
"usersize": 15000,
"facesize": 5000,
"fpsize": 10000,
"cardsize": 15000,
"pwdsize": 15000,
"logsize": 500000,
"useduser": 204,
"usedface": 3,
"usedfp": 0,
"usedcard": 204,
"usedpwd": 1,
"usedlog": 472,
"usednewlog": 472,
"usedrtlog": 0,
"netinuse": 1,
"usb4g": 0,
"fpalgo": "thbio3.0",
"firmware": "ai518_fp26v_v1.27",
"time": "2025-02-21 11:33:20",
"intercom": 0,
"floors": 48,
"charid": 1,
"useosdp": 0,
"dislanguage": 524417,
"mac": "00-00-00-00-00-00"
}
}Campos da mensagem
- cmd: Sempre “reg”.
- sn: Número de série único que identifica o dispositivo.
- devinfo: Objeto contendo informações detalhadas sobre o leitor facial.
- modelname: Nome do modelo do dispositivo.
- usersize: Capacidade máxima de armazenamento para usuários.
- facesize: Capacidade máxima de armazenamento para dados faciais.
- cardsize: Capacidade máxima de armazenamento para cartões.
- pwdsize: Capacidade máxima de armazenamento para senhas.
- logsize: Capacidade máxima de armazenamento para logs.
- useduser: Número de usuários cadastrados.
- usedface: Número de dados faciais armazenados.
- usedcard: Número de cartões cadastrados.
- usedpwd: Número de senhas cadastradas.
- usedlog: Número de logs armazenados.
- usednewlog: Número de novos logs desde a última sincronização.
- usedrtlog: Número de logs em tempo real
- netinuse: se está em uso rede
- usb4g: usb 4g
- firmware: Versão do firmware do dispositivo.
- time: Data e hora configuradas no leitor facial.
- charid: id do dispositivo
- dislanguage: idioma do dispositivo
- mac: endereço mac do dispositivo
- fpsize: Não aplicável.
- usedfp: Não aplicável.
- fpalgo: Não aplicável.
- intercom: Não aplicável.
- floors: Não aplicável.
- useosdp: Não aplicável
Formato da resposta
{
"ret": "reg", // Comando
"result": true,
"cloudtime": "2016-03-25 13:49:30" // Hora do servidor
} Importante:
O aplicativo deve responder ao comando “reg” obrigatoriamente para confirmar a conexão e evitar que o leitor facial envie o comando “reg” repetidamente. Caso a resposta não seja enviada, a comunicação com o leitor facial será perdida.
Campos da resposta
ret: Indica que esta é uma resposta ao comando reg.
result: Indica o sucesso ou falha da operação.
cloudtime: Horário do servidor em formato ano-mês-dia hora:minutos:segundos. Exemplo: 2016-03-25 13:49:30.
Log ou Requisição de Acesso
sendlog
Descrição: Comando enviado pelo dispositivo toda vez que algum rosto é detectado, seja ele cadastrado ou não (operando em modo online ou offline).
Para o modo online, a resposta por parte do aplicativo é obrigatória, uma vez que a liberação será feita a partir da resposta. Quando em modo offline, serve como um aviso de que houve uma tentativa ou então um acesso.
Tipo: Recebimento (enviado pelo dispositivo).
Parâmetros da mensagem
- cmd: “sendlog“, indica que é um evento de log de acesso.
- sn: Número de série do dispositivo.
- count: Número de registros de log incluídos na mensagem (geralmente 1).
- logindex: Índice do log.
- record: Um array contendo informações detalhadas sobre a tentativa de autenticação. Dentro deste array:
- enrollid: ID do usuário que tentou se autenticar.
- name: Nome do usuário.
- time: Data e hora da tentativa de acesso (“yyyy-MM-dd HH:mm:ss”).
- mode: Modo de autenticação utilizado.
- 2: reconhecimento por senha
- 3: reconhecimento por cartão
- 8: reconhecimento por facial
- inout: Sentido do acesso (Entrada/Saída).
- event: Tipo do evento.
Formato da mensagem (usuário cadastrado)
{
"cmd": "sendlog",
"sn": "1234567890",
"count": 1,
"logindex": 0,
"record":[
{
"enrollid": 300,
"name": "Nome do Usuário",
"time": "2025-02-26 11:40:19",
"mode": 8,
"inout": 0,
"event": 0
}
]
}Formato da mensagem (usuário não cadastrado)
{
"cmd": "sendlog",
"sn": "1234567890",
"count": 1,
"logindex": 124,
"record": [
{
"enrollid": 99999999, // ID especial para desconhecido
"name": "",
"time": "2023-12-27 10:05:00",
"mode": 1,
"inout": 0,
"event": 2, // Tipo de evento (ex: 2 - desconhecido)
"image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}
]
} Parâmetros da resposta
- ret: “sendlog“, indica que é uma resposta ao evento sendlog.
- result: true, indica que a resposta foi processada com sucesso.
- cloudtime: Data e hora da resposta (formato “yyyy-MM-dd HH:mm:ss”).
- message: Mensagem personalizada que pode ser exibida no leitor facial.
- access: Valor booleano que determina se o acesso deve ser concedido (true) ou negado (false). Este é o campo crucial para controlar o acesso no modo online.
Formato da resposta
{
"ret": "sendlog",
"result": true,
"cloudtime": "2025-02-26 11:40:21",
"message": "Usuário não cadastrado",
"access": false
} Importante
- Para que a validação no modo online funcione corretamente, o usuário deve estar previamente cadastrado no leitor facial (mesmo que o controle de acesso seja feito no aplicativo). O enrollid enviado no evento sendlog deve corresponder a um usuário cadastrado.
- O aplicativo é responsável por implementar a lógica de tratamento de erros e garantir que uma resposta sendlog seja sempre enviada ao leitor, mesmo em caso de falha na comunicação ou processamento.
- O texto exibido no leitor pode ser personalizado através da alteração do parametro “message”
Habilitar / Desabilitar Comunicação
enabledevice / disabledevice
Descrição: Estes comandos controlam a comunicação entre o aplicativo e o leitor facial.
Tipo: Envio (enviado pelo aplicativo).
• disabledevice (Desabilitar): Suspende o tratamento de acessos no leitor facial. O envio de comando continua sendo realizado normalmente.
• enabledevice (Habilitar): Volta a validação de acesso com o leitor facial.
Formato da requisição
{
"cmd": "enabledevice"
}
// Ou então
{
"cmd": "disabledevice"
} Formato da resposta
{
"ret": "enabledevice", // ou "disabledevice"
"result": true
} Obter a Lista de Usuários
getuserlist
Descrição: O comando getuserlist possui variações para controlar a paginação da lista de usuários, já que o dispositivo pode ter muitos usuários cadastrados.
Tipo: Envio (enviado pelo aplicativo).
O aplicativo deve utilizar o campo “stn” do comando “getuserlist” para indicar se deseja obter a próxima página da lista:
- stn: true: Inicia a busca da lista de usuários a partir do primeiro registro.
- stn: false: Solicita a próxima página da lista de usuários.
Formato da requisição
{
"cmd": "getuserlist",
"stn": true
}
// Ou então
{
"cmd": "getuserlist",
"stn": false
} Formato da resposta (exemplo com 3 usuários na primeira página)
{
"ret": "getuserlist",
"result": true,
"count": 100, // Número total de usuários no dispositivo
"from": 1, // Índice inicial da página atual
"to": 3, // Índice final da página atual
"record": [
{ "enrollid": 1, "admin": "0", "backupnum": 10 },
{ "enrollid": 2, "admin": "0", "backupnum": 10 },
{ "enrollid": 3, "admin": "1", "backupnum": 10 }
]
} Observação
O aplicativo deve continuar enviando comandos getuserlist com stn: false até que o campo “to” na resposta seja igual ao “count”, indicando que todos os usuários foram recebidos.
Obter Informações de Usuário
getuserinfo
Descrição: Este comando é usado para solicitar informações detalhadas de um usuário específico cadastrado no dispositivo, incluindo nome, nível de administrador, dados biométricos, cartão e senha.
Tipo: Envio (enviado pelo aplicativo).
Formato da requisição
{
"cmd": "getuserinfo",
"enrollid": 12345, // ID do usuário
"backupnum": 0 // Tipo de dado a ser retornado
// (0 para todos os dados)
// (10 para senha)
// (13 todos, exceto foto)
// (50 foto)
} Formato da resposta
{
"ret": "getuserinfo",
"sn": "SN_Dispositivo", //Número de série do dispositivo
"enrollid": 1,
"name": "Nome do Usuário",
"admin": 0,
"card": 1234,
"pwd": 1234,
"faceflag": 1, // Possui dados faciais (1 - Sim, 0 - Não)
"enable": 1, // Habilitado no dispositivo (1- Sim, 0 - Não)
"result": false, // Indica se a operação foi bem sucedida ou não
"backupnum": 0,
"reason": 1, //Código do motivo da falha
"msg": "have no data" //Mensagem da falha
} Observações
- Os campos faceflag e enable podem estar presentes ou não dependendo da versão do dispositivo.
- O campo record conterá o valor específico solicitado, como a senha (para backupnum: 10) ou os dados da foto (para backupnum: 50).
- Em caso de erro (result: false), utilize os campos reason e msg para entender o motivo da falha.
Enviar Dados de Usuário
setuserinfo
Descrição: O comando setuserinfo é usado para enviar dados de um usuário para o dispositivo (cadastrar ou atualizar), incluindo nome, nível de administrador, senha, cartão e foto. Este comando possui variações controladas pelo campo backupnum para especificar qual tipo de informação está sendo enviada.
Tipo: Envio (enviado pelo aplicativo).
Forma Recomendada de Envio:
Para enviar um usuário completo, incluindo todos os dados, use as seguintes opções:
backupnum: 0 (Enviar usuário sem foto): Envia o nome, nível de administrador, senha e número de cartão do usuário. O campo record deve ser 0 (zero).
backupnum: 50 (Enviar usuário com foto): Envia o nome, nível de administrador, senha, número de cartão e a foto do usuário. O campo record deve conter a foto do usuário codificada em Base64.
Formato da requisição
{
"cmd": "setuserinfo",
"enrollid": 12345,
"name": "Nome do Usuário",
"backupnum": 0,
"admin": 1, // 1 para administrador
"card": 12345, // Número do cartão
"pwd": 1234, // Senha
"enable": 1, // 1 habilitado, 0 desabilitado
"record": "0" // Valor 0, indicar que não há dado especifico para record
}
// Ou então
{
"cmd": "setuserinfo",
"enrollid": 12345,
"name": "Nome do Usuário",
"backupnum": 50,
"admin": 0,
"card": 12345,
"pwd": 1234,
"enable": 1, //1 habilitado, 0 desabilitado
"record": "data:image/jpeg;base64,/9j/4AAQSkABAQAD..." // Foto em Base64
} Observações importantes
- Campos opcionais: Campos como name e admin são opcionais em algumas variações do comando setuserinfo.
- Tamanho da foto: O dispositivo pode ter um limite para o tamanho da foto enviada. Recomenda-se fotos de até 150KB.
Formato da resposta
{
"ret": "setuserinfo",
"sn": "1234567890",
"result": false
}Configurar Bloqueios de Acesso Por Usuário
setuserlock
Descrição: O comando setuserlock é usado para configurar restrições de acesso para usuários específicos, definindo horários de acesso e zonas de horários semanais. Este comando permite criar restrições de acesso personalizadas para cada usuário.
Tipo: Envio (enviado pelo aplicativo).
Parâmetros do Comando
- cmd: Sempre “setuserlock”.
- count: Número de registros na lista de bloqueios de acesso.
- verifymode: Modo de verificação. Consulte a tabela abaixo para os valores e seus significados.
- record: Array contendo os registros de bloqueio de acesso por usuário. Cada registro possui as seguintes propriedades:
- enrollid: ID do usuário.
- weekzone: ID da zona de horários semanais (referencia uma zona da tabela weekzone do setdevlock).
- starttime: Horário de início do controle de acesso (formato: “yyyy-MM-dd HH:mm:ss”).
- endtime: Horário de fim do controle de acesso (formato: “yyyy-MM-dd HH:mm:ss”).
| Valor “verifymode” | Descrição |
| 0 | Face, Cartão ou Senha |
| 2 | Somente Senha |
| 3 | Somente Cartão |
| 8 | Somente Face |
| 9 | Face e Senha |
| 10 | Cartão e Face |
| 11 | Cartão e Senha |
| 14 | Face e (Cartão ou Senha) |
Formato da requisição
{
"cmd": "setuserlock",
"count": 2,
"verifymode": 0,
"record":
[
{
"enrollid": 1,
"weekzone": 1,
"starttime": "2016-03-25 01:00:00",
"endtime": "2099-03-25 23:59:00"
},
{
"enrollid": 2,
"weekzone": 2,
"starttime": "2016-03-25 08:00:00",
"endtime": "2099-03-25 18:00:00"
}
]
} Formato da resposta
{
"ret": "setuserlock",
"result": true
}Remover Usuário
deleteuser
Descrição: O comando deleteuser possui variações controladas pelo campo backupnum para determinar quais dados do usuário serão removidos do dispositivo.
Tipo: Envio (enviado pelo aplicativo).
Formato da requisição
{
"cmd": "deleteuser",
"enrollid": 12345,
"backupnum": 0 // Tipo de exclusão
// (0 Todos os dados)
// (10 Apagar senha)
// (11 Apagar cartão)
// (50 Apagar foto)
}Formato da resposta
{
"ret": "deleteuser",
"result": true
}Configurar Parâmetros
setdevinfo
Descrição: O comando setdevinfo é usado para configurar diversos parâmetros do dispositivo, como idioma, volume, tempo de tela, modo de verificação, etc. As opções disponíveis dependem do modelo do dispositivo e das configurações habilitadas.
Tipo: Envio (enviado pelo aplicativo).
Parâmetros do Comando
- door_opentime: Tempo de abertura da porta (segundos).
- door_password: Senha geral de acesso.
- verifymode: Modo de verificação. Consulte a tabela disponível no comando “setuserlock”
- access_denied_nolog: Define se o acesso negado deve ser registrado ou não no log do dispositivo.
- volume: Volume do som do dispositivo de 0 a 10.
- stranger_lock: Define se o dispositivo deve permitir a entrada de pessoas não cadastradas (0 para não permitir, 1 para permitir).
- server_verify: Define se a verificação é feita no dispositivo ou no servidor
- 0 para somente offline.
- 1 para somente online.
- 2 para alternar automaticamente entre online e offline.
Formato da requisição
{
"cmd": "setdevinfo",
"door_opentime": 5,
"door_password": "123456",
"verifymode": 1,
"access_denied_nolog": 0,
"volume": 8,
"stranger_lock": 0,
"server_verify": 0
} Formato da resposta
{
"ret": "setdevinfo",
"result": true
}Configurar Bloqueios e Horários
setdevlock
Descrição: O comando setdevlock é usado para configurar diversos parâmetros relacionados a bloqueios e horários do dispositivo, incluindo formato do cartão, horários de acesso e tabelas de horários. As opções disponíveis dependem do modelo do dispositivo e das configurações habilitadas.
Tipo: Envio (enviado pelo aplicativo).
Parâmetros do Comando
- cardformat: Formato do número do cartão que será exibido no display do leitor facial. (0: Decimal, 1: Wiegand, 2: Hexadecimal) – padrão é 1: Wiegand.
- dayzone: Lista de zonas de horários diários, contendo as seções de horários.
Cada dayzone representa um dia e pode conter até 5 seções de horário.
Podem ser cadastradas até 8 dayzones. - weekzone: Lista de zonas de horários semanais, contendo os dias da semana.
Cada weekzone representa uma semana e pode conter os dias da semana.
Podem ser cadastradas até 8 weekzones.
Formato da requisição (Configuração do Formato do Cartão)
{
"cmd": "setdevlock",
"cardformat": 1
} Formato da requisição (Configuração de Horários Diários)
{
"cmd": "setdevlock",
"dayzone":
[ {
"day": [{ "section": "06:00~07:00" },
{ "section": "08:30~12:00" },
{ "section": "13:00~17:00" },
{ "section": "22:00~23:30" }]
},
{
"day": [{ "section": "00:01~23:59" },
{ "section": "00:01~23:59" }]
}
]
} Formato da requisição (Configuração de Horários Semanais)
{
"cmd": "setdevlock",
"weekzone":
[{
"week": [
{ "day": 1 }, // segunda-feira com a faixa de dia 1
{ "day": 1 }, // terça-feira com a faixa de dia 1
{ "day": 1 }, // quarta-feira com a faixa de dia 1
{ "day": 1 }, // quinta-feira com a faixa de dia 1
{ "day": 1 }, // sexta-feira com a faixa de dia 1
{ "day": 2 }, // sábado com a faixa de dia 2
{ "day": 2 } // domingo com a faixa de dia 2
]
},
{
"week": [ // a segunda week zone
{ "day": 2 }, // segunda-feira com a faixa de dia 2
{ "day": 2 }, // terça-feira com a faixa de dia 2
{ "day": 2 }, // quarta-feira com a faixa de dia 2
{ "day": 2 }, // quinta-feira com a faixa de dia 2
{ "day": 2 }, // sexta-feira com a faixa de dia 2
{ "day": 1 }, // sábado com a faixa de dia 1
{ "day": 1 } // domingo com a faixa de dia 1
]
}
]
} Formato da resposta
{
"ret": "setdevlock",
"result": true
}Apagar Todos Usuários
cleanuser
Descrição: Este comando remove todos os usuários cadastrados no dispositivo.
Tipo: Envio (enviado pelo aplicativo).
Formato da requisição
{
"cmd": "cleanuser"
} Formato da resposta
{
"ret": "cleanuser",
"result": true
} Observações
- Utilize este comando com cautela, pois ele apagará todos os dados de usuários do dispositivo.
- Verifique a resposta do dispositivo para garantir que a operação foi bem-sucedida.
- Implemente um mecanismo de confirmação no aplicativo antes de executar o comando, para evitar a exclusão acidental de dados.
Obter Todos os Logs
getalllog
Descrição: Este comando permite ao aplicativo solicitar todos os logs de acesso do Leitor Facial, com opções de paginação e filtro por período.
Tipo: Envio (enviado pelo aplicativo).
Parâmetros do Comando
- cmd: Sempre “getalllog”.
- stn: Indica se a busca deve iniciar do primeiro registro (true) ou continuar da página seguinte (false).
- from: (Opcional) Data inicial para filtrar os logs no formato “yyyy-MM-dd”.
- to: (Opcional) Data final para filtrar os logs no formato “yyyy-MM-dd”.
Formato da requisição
Requisição:
{
"cmd": "getalllog",
"stn": true,
"from": "2018-11-1", //opcional: data inicial para o filtro
"to": "2018-12-30" //opcional: data final para o filtro
} Formato da resposta
{
"ret": "getalllog",
"result": true,
"count": 1000,
"from": 50, // Índice do primeiro log nesta página
"to": 99, // Índice do último log nesta página
"record": [
{
"enrollid": 111,
"time": "2016-03-25 13:49:30",
"mode": 0,
"inout": 0,
"event": 0
},
{
"enrollid": 112,
"time": "2016-03-25 13:49:30",
"mode": 0,
"inout": 0,
"event": 1
},
...
]
} Limpar Todos os Logs
cleanlog
Descrição: Este comando permite ao aplicativo solicitar a exclusão de todos os logs de acesso armazenados no dispositivo.
Tipo: Envio (enviado pelo aplicativo).
Formato da requisição
{
"cmd": "cleanlog"
} Formato da resposta
{
"ret": "cleanlog",
"result": true
}