Protocolo Facial API WebService

Esse é o único comando que não necessita de senha.

Requisição:

{ 
  "cmd": "getlang" 
}

Resposta:

{
  "ret": "getlang",
  "sn": "SN123456",
  "result": true,
  "lang": "English"
}

Requisição:

{
  "cmd": "reg",
  "password": "xxx"
}

Exemplo de Resposta:

{
  "ret": "reg",
  "sn": "AYSH01090913",
  "devinfo": {
    "modelname": "AiFace",
    "manufacturer": "",
    "deviceid": 1,
    "usersize": 15000,
    "facesize": 5000,
    "fpsize": 0,
    "palmsize": 0,
    "cardsize": 15000,
    "pwdsize": 15000,
    "logsize": 500000,
    "useduser": 16,
    "usedface": 15,
    "usedfp": 0,
    "usedpalm": 0,
    "usedcard": 15,
    "usedpwd": 0,
    "usedlog": 936,
    "usednewlog": 936,
    "usedrtlog": 14,
    "netinuse": 1,
    "usb4g": 0,
    "fpalgo": "thbio3.0",
    "firmware": "ai518_fp26v_v2.16",
    "time": "2026-06-01 09:58:54",
    "intercom": 0,
    "elevator_control": 0,
    "floors": 48,
    "base_floor": 0,
    "have_g_floor": 0,
    "acces_stimes": 0,
    "charid": 1,
    "useosdp": 0,
    "facetemplate": 0,
    "usequestion": 1,
    "onlinedebug": 0,
    "dislanguage": 524417,
    "curip": "010.000.040.009",
    "ntp": 0,
    "timezone": "UTC-3",
    "mac": "00-01-A9-1A-FC-AB"
  }
}

Campos do devinfo

Requisição:

{
  "cmd": "getdevinfo",
  "password": "xxx"
}

Resposta:
Retorna todos os parâmetros de configuração DI_ no formato chave-valor.

Exemplo de Resposta

{
  "ret": "getdevinfo",
  "sn": "SN123456",
  "result": true,
  "deviceid": 1,
  "language": 0,
  "managers": 1,
  "verifymode": 0,
  "volume": 80,
  "netipaddress": "192.168.1.100",
  "serverip": "192.168.1.200",
  "wlan_ssid": "MyWiFi",
  "door_opentime": 5,
  "live_detect": 1,
  "fcmatch_level": 60
}

Lista Completa de Parâmetros de Configuração

Configurações Gerais

Configurações Biométricas

Configurações Seriais e de Rede

Configurações do Servidor

Requisição:

{
  "cmd": "setdevinfo",
  "password": "xxx",
  "nowtime": 1700000000,
  "deviceid": 1,
  "volume": 80,
  "live_detect": 1,
  "fcmatch_level": 60
}

Regras de Tipo

• Campos do tipo IP (netipaddress, serverip, etc.) aceitam strings de IP como "192.168.1.100"
• Campos string (wlan_ssid, excel_password, cpucard_key, etc.) aceitam texto
• Todos os demais campos aceitam valores numéricos

Requisição:

{
  "cmd": "getdevcap",
  "password": "xxx"
}

Resposta:

{
  "ret": "getdevcap",
  "sn": "SN123456",
  "result": true,
  "usersize": 10000,
  "facesize": 10000,
  "avatarsize": 10000,
  "fpsize": 30000,
  "palmsize": 30000,
  "cardsize": 10000,
  "pwdsize": 10000,
  "logsize": 100000,
  "useduser": 150,
  "usedface": 148,
  "usedavatar": 100,
  "usedfp": 10,
  "usedpalm": 0,
  "usedcard": 50,
  "usedpwd": 20,
  "usedlog": 5000,
  "usednewlog": 100,
  "usedrtlog": 5
}

Requisição:

{
  "cmd": "getuserlist",
  "password": "xxx",
  "stn": 1
}

Resposta:

{
  "ret": "getuserlist",
  "sn": "SN123456",
  "result": true,
  "count": 100,
  "to": 50,
  "record": [
    {
      "id": "1001",
      "name": "John Doe",
      "department": "Engineering",
      "shift": 0,
      "admin": 0,
      "fingerprint": 2,
      "palm": 0,
      "face": 1,
      "password": 0,
      "card": 12345678,
      "weekzone": 0,
      "group": 0,
      "access_times": 0,
      "verifymode": 0,
      "birthday": "01-15",
      "starttime": "2024-01-01 00:00",
      "endtime": "2025-12-31 23:59",
      "photourl": "/photos/LF00001001.jpg"
    }
  ]
}

Campos da Resposta

Campos de record[]

Observações

• Cada requisição retorna no máximo 50 usuários.
• Para continuar a leitura das próximas páginas, envie:

{
  "cmd": "getuserlist",
  "password": "xxx",
  "stn": 0
}

• Continue realizando chamadas até:
  • to >= count
  • ou to == 0 (sem mais registros).

Requisição

{
  "cmd": "checkuserid",
  "password": "xxx",
  "enrollid": "1001"
}

Resposta

{
  "ret": "checkuserid",
  "sn": "SN123456",
  "result": true,
  "exists": true
}

Requisição:

{
  "cmd": "getuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 50
}

Resposta (com foto facial, backupnum=50)

{
  "ret": "getuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "name": "John Doe",
  "department": "Engineering",
  "admin": 0,
  "pwd": 0,
  "card": 12345678,
  "fpflag": 3,
  "fpcnt": 2,
  "faceflag": 1,
  "birthday": "01-15",
  "starttime": "2024-01-01 00:00:00",
  "endtime": "2025-12-31 23:59:59",
  "photourl": "/photos/LF00001001.jpg",
  "backupnum": 50,
  "record": ""
}

Resposta (usuário não encontrado)

{
  "ret": "getuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "can not find the user",
  "enrollid": "1001"
}

Campos da Resposta

Requisição:

{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "admin": 0,
  "pwd": 123456,
  "card": 12345678,
  "department": "Engineering",
  "birthday": "01-15",
  "starttime": "2024-01-01 00:00:00",
  "endtime": "2025-12-31 23:59:59",
  "verifymode": 0,
  "shiftid": 1,
  "zoneid": 1,
  "groupid": 0,
  "access_times": 0,
  "enable": 1,
  "face": ""
}

Campos

Resposta (sucesso):

{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "backupnum": 50
}

Resposta (falha):

{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 5,
  "msg": "no face",
  "enrollid": "1001"
}

Códigos de erro de cadastro facial

Requisição:

{
  "cmd": "deleteuser",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 12
}

Valores de backupnum

Resposta:

{
  "ret": "deleteuser",
  "sn": "SN123456",
  "result": true,
  "backupnum": 12,
  "enrollid": "1001"
}

Requisição:

{
  "cmd": "deleteuserface",
  "password": "xxx",
  "enrollid": "1001"
}

Resposta:

{
  "ret": "deleteuserface",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

Requisição:

{
  "cmd": "deleteusers",
  "password": "xxx",
  "list": ["1001", "1002", "1003"]
}

Resposta:

{
  "ret": "deleteusers",
  "sn": "SN123456",
  "result": true
}

Requisição:

{
  "cmd": "cleanuser",
  "password": "xxx"
}

DESTRUTIVO: Remove todos os usuários cadastrados no dispositivo.

Resposta:

{
  "ret": "cleanuser",
  "sn": "SN123456",
  "result": true
}

Requisição

{
  "cmd": "enableuser",
  "password": "xxx",
  "enrollid": "1001",
  "enflag": 1
}

Resposta

{
  "ret": "enableuser",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

Aciona a tela local do dispositivo para realizar o cadastro de biometria (digital, palma ou face).

Requisição

{
  "cmd": "adduser",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "admin": 0,
  "backupnum": 50,
  "flag": 0
}

Campos

Resposta (sucesso)

{
  "ret": "adduser",
  "sn": "SN123456",
  "result": true,
  "backupnum": 50,
  "enrollid": "1001"
}

Resposta (cancelamento)

{
  "ret": "adduser",
  "result": true,
  "cancel": true
}

Resposta (falha)

{
  "ret": "adduser",
  "sn": "SN123456",
  "result": false,
  "reason": 3,
  "msg": "device busy",
  "backupnum": 50,
  "enrollid": "1001"
}

Códigos de Erro

Requisição

{
  "cmd": "checkregstatus",
  "password": "xxx"
}

Resposta

{
  "ret": "checkregstatus",
  "sn": "SN123456",
  "result": true,
  "status": 1,
  "msg": "success",
  "image": ""
}

Campos da Resposta

Códigos de Status

Requisição

{
  "cmd": "getlog",
  "password": "xxx",
  "index": 0,
  "enrollid": "1001",
  "from": "240601",
  "to": "241231"
}

Campos

Resposta

Retorna até 50 registros por requisição.

{
  "ret": "getlog",
  "sn": "SN123456",
  "result": true,
  "count": 500,
  "from": 0,
  "to": 50,
  "record": [
    {
      "enrollid": "1001",
      "name": "John Doe",
      "time": "2024-06-01 09:00:00",
      "mode": 1,
      "inout": 1,
      "event": 0,
      "note": "remark",
      "photourl": "/logphotos/logimage123.jpg"
    }
  ]
}

Campos da Resposta

Campos de record[]

Paginação

Para continuar a leitura dos próximos registros, envie novamente o comando alterando o index.

Exemplo:

{
  "cmd": "getlog",
  "password": "xxx",
  "index": 50
}

Continue realizando chamadas até:

ou não existirem mais registros retornados.

to >= count

Requisição

{
  "cmd": "getrtlog",
  "password": "xxx",
  "index": 0
}

Campos

Resposta

{
  "ret": "getrtlog",
  "sn": "SN123456",
  "result": true,
  "count": 25,
  "from": 0,
  "to": 20,
  "record": [
    {
      "enrollid": "1001",
      "name": "John Doe",
      "time": "2024-06-01 09:00:00",
      "mode": 1,
      "inout": 1,
      "event": 0,
      "note": "remark"
    }
  ]
}

Campos da Resposta

Campos de record[]

Os campos são os mesmos utilizados no comando getlog.

Observações

• Os logs em tempo real são removidos da fila após serem lidos.
• Cada requisição retorna no máximo 20 registros.
• Continue realizando chamadas incrementando o index até:
  • to >= count

Exemplo:

{
  "cmd": "getrtlog",
  "password": "xxx",
  "index": 20
}

Requisição

{
  "cmd": "setlogs",
  "password": "xxx",
  "records": [
    {
      "id": "1001",
      "event": 0,
      "mode": 1,
      "time": "2024-06-01 09:00:00"
    }
  ]
}

Campos

Resposta

{
  "ret": "setlogs",
  "sn": "SN123456",
  "result": true
}

Requisição

{
  "cmd": "cleanlog",
  "password": "xxx"
}

DESTRUTIVO: Remove todos os logs históricos de acesso/ponto do dispositivo.

Resposta

{
  "ret": "cleanlog",
  "sn": "SN123456",
  "result": true
}

Requisição

{
  "cmd": "gettime",
  "password": "xxx"
}

Resposta

{
  "ret": "gettime",
  "sn": "SN123456",
  "time": "2024-06-01 10:00:00"
}

Campos da Resposta

Método 1 — Utilizando data/hora em texto

{
  "cmd": "settime",
  "password": "xxx",
  "cloudtime": "2024-06-01 10:00:00"
}

Método 2 — Utilizando timestamp Unix em milissegundos

{
  "cmd": "settime",
  "password": "xxx",
  "nowtime": 1717200000000
}

Campos

Utilize apenas um dos campos: cloudtime ou nowtime.

Resposta (sucesso)

{
  "ret": "settime",
  "sn": "SN123456",
  "result": true
}

Resposta (falha)

{
  "ret": "settime",
  "sn": "SN123456",
  "result": false,
  "reason": 1
}

Validações

O dispositivo valida:

• Ano maior ou igual a 2021
• Mês entre 1-12
• Dia válido
• Hora válida
• Minuto válido
• Segundo válido

Em caso de falha, será retornado:

Requisição

{
  "cmd": "reboot",
  "password": "xxx"
}

O dispositivo reinicia imediatamente.

A conexão será encerrada automaticamente pelo equipamento.

Não existe resposta HTTP.

DESTRUTIVO: Remove todos os usuários, logs e configurações do dispositivo.

Itens removidos:

• Usuários cadastrados
• Registros de acesso/ponto
• Configurações do sistema
• Agendamentos de campainha (bell schedules)
• Dados de departamentos/cargos
• Configurações de controle de ponto
• Dados de controle de acesso/fechaduras

Itens preservados:

• Idioma configurado no dispositivo
• Configurações de Wi-Fi (são armazenadas em backup)

Requisição

{
  "cmd": "initsys",
  "password": "xxx"
}

Resposta

{
  "ret": "initsys",
  "sn": "SN123456",
  "result": true
}

Restaura as configurações do sistema para os valores padrão, preservando usuários e registros.

Requisição

{
  "cmd": "initmenu",
  "password": "xxx"
}

Resposta

{
  "ret": "initmenu",
  "sn": "SN123456",
  "result": true
}

Observação

Este comando possui comportamento semelhante ao initsys, porém:

Restaura apenas as configurações do equipamento

Mantém os usuários cadastrados

Mantém os logs armazenados

DESTRUTIVO: Remove completamente o banco de dados de registros do dispositivo.

Após a execução:

• Todos os logs serão apagados
• Uma flag de reinicialização será configurada
• O equipamento será reiniciado automaticamente

Requisição

{
  "cmd": "cleandatebase",
  "password": "xxx"
}

Resposta

{
  "ret": "cleandatebase",
  "sn": "SN123456",
  "result": true
}

Remove privilégios administrativos de todos os usuários cadastrados no dispositivo.

Requisição

{
  "cmd": "cleanadmin",
  "password": "xxx"
}

Resposta

{
  "ret": "cleanadmin",
  "sn": "SN123456",
  "result": true
}

Permite realizar a abertura remota da porta controlada pelo dispositivo. Opcionalmente, é possível associar a operação a um usuário específico, acionar um andar em sistemas de controle de elevador e exibir uma mensagem temporária na tela do equipamento.

Requisição

{
  "cmd": "opendoor",
  "password": "xxx",
  "enrollid": "1001",
  "msg": "Bem-vindo"
}

Campos

Resposta

{
  "ret": "opendoor",
  "sn": "SN123456",
  "result": true
}

Campos da Resposta

Observações

A mensagem informada em msg é exibida temporariamente no display do equipamento e não é armazenada.

A abertura da porta depende das configurações de controle de acesso do dispositivo.

Permite configurar os parâmetros de controle de acesso do dispositivo, incluindo tempos de abertura, sensores, alarmes, regras de acesso, configurações Wiegand e tabelas de horários.

Requisição

Todos os parâmetros são opcionais. Envie apenas aqueles que deseja alterar.

{
  "cmd": "setdevlock",
  "password": "xxx",
  "opendelay": 5,
  "doorsensor": 1,
  "alarmdelay": 30,
  "InputAlarm": 0,
  "antpass": 0,
  "interlock": 0,
  "mutiopen": 0,
  "tryalarm": 5,
  "access_times": 0,
  "punchtimes": 0,
  "tamper": 0,
  "wgformat": 26,
  "wgoutput": 0,
  "cardformat": 0,
  "dayzone": [],
  "weekzone": [],
  "lockgroup": [],
  "nopentime": [],
  "visitortime": []
}

Campos

Resposta

{
  "ret": "setdevlock",
  "sn": "SN123456",
  "result": true
}

Retorna todas as configurações de controle de acesso atualmente aplicadas ao dispositivo.

Requisição

{
  "cmd": "getdevlock",
  "password": "xxx"
}

Resposta

{
  "ret": "getdevlock",
  "sn": "SN123456",
  "result": true,
  "opendelay": 5,
  "doorsensor": 1,
  "alarmdelay": 30,
  "InputAlarm": 0,
  "antpass": 0,
  "interlock": 0,
  "mutiopen": 0,
  "tryalarm": 5,
  "access_times": 0,
  "tamper": 0,
  "wgformat": 26,
  "wgoutput": 0,
  "cardformat": 0,
  "dayzone": [],
  "weekzone": [],
  "lockgroup": [],
  "nopentime": [],
  "visitortime": []
}

Campos da Resposta

Os campos retornados possuem os mesmos significados descritos no comando setdevlock.

Retorna as configurações de controle de acesso atribuídas a um usuário específico.

Requisição

{
  "cmd": "getuserlock",
  "password": "xxx",
  "enrollid": "1001"
}

Campos

Resposta (usuário encontrado)

{
  "ret": "getuserlock",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "birthday": "01-15",
  "verifymode": 0,
  "weekzone": 0,
  "group": 0,
  "access_times": 0,
  "starttime": "2024-01-01 00:00:00",
  "endtime": "2025-12-31 23:59:59"
}

Resposta (usuário não encontrado)

{
  "ret": "getuserlock",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "can not find the user",
  "enrollid": "1001"
}

Campos da Resposta

Códigos de Erro

Permite definir ou atualizar as configurações de controle de acesso de múltiplos usuários em uma única requisição.

Requisição

{
  "cmd": "setuserlock",
  "password": "xxx",
  "count": 2,
  "record": [
    {
      "enrollid": "1001",
      "birthday": "01-15",
      "verifymode": 0,
      "weekzone": 0,
      "group": 0,
      "access_times": 0,
      "starttime": "2024-01-01 00:00:00",
      "endtime": "2025-12-31 23:59:59"
    },
    {
      "enrollid": "1002",
      "birthday": "06-20",
      "verifymode": 1,
      "weekzone": 1,
      "group": 0,
      "access_times": 5,
      "starttime": "2024-01-01 00:00:00",
      "endtime": "2025-12-31 23:59:59"
    }
  ]
}

Campos

Resposta (Sucesso)

{
  "ret": "setuserlock",
  "sn": "SN123456",
  "result": true
}

Resposta (Falha)

{
  "ret": "setuserlock",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "setuserlock fail"
}

Códigos de Erro

Remove as configurações de controle de acesso associadas a um usuário específico.

Requisição

{
  "cmd": "deleteuserlock",
  "password": "xxx",
  "enrollid": "1001"
}

Campos

Resposta

{
  "ret": "deleteuserlock",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

Campos da Resposta

Remove todas as configurações de controle de acesso personalizadas associadas aos usuários cadastrados no dispositivo.

Requisição

{
  "cmd": "cleanuserlock",
  "password": "xxx"
}

Resposta

{
  "ret": "cleanuserlock",
  "sn": "SN123456",
  "result": true
}

Observações

Apenas as regras de acesso associadas aos usuários são removidas.

Este comando remove as configurações individuais de acesso dos usuários.

Os usuários cadastrados não são excluídos.

Os dados biométricos, cartões e registros permanecem armazenados no dispositivo.