Skip to main content

Introdução

Visão Geral da Arquitetura de Integração API RESTful​

Este documento descreve os padrões de comunicação e integração da API RESTful dos terminais de reconhecimento facial da WEG. A arquitetura foi desenhada para oferecer flexibilidade de implantação, suportando ambientes locais e em nuvem através de um modelo unificado de comunicação.

A nova arquitetura pode coexistir com o modelo Push legado, permitindo que os integradores escolham a melhor abordagem para seus requisitos de implantação.

A arquitetura da API RESTful é estritamente padronizada para toda a linha de terminais de reconhecimento facial, garantindo que o sistema de negócio utilize a mesma base de código, rotas e estruturas de JSON para se comunicar com qualquer modelo. Essa unificação reduz significativamente o esforço de desenvolvimento e manutenção. Contudo, é importante ressaltar que a execução lógica e bem-sucedida de determinados endpoints está condicionada às capacidades físicas do dispositivo alvo. Funcionalidades específicas da API operarão normalmente e retornarão sucesso apenas se o hardware do terminal consultado possuir suporte nativo e os componentes necessários para executar tais recursos.

Dispositivos Compatíveis​

Terminal FacialFirmware
Terminal Facial Go WA02-FWZAM70-WEG24HA-Ver3.3.15 ou posterior
Terminal Facial Go WA03C-WZAM70-WEG28VA-Ver3.3.15 ou posterior
Terminal Facial Core WA04C-WZAM70-WEG43VA-Ver3.3.15 ou posterior
Terminal Facial Core WA07C-WZAM70-WEG70VA-Ver3.4.15 ou posterior
Terminal Facial Pro WA05C-WZAM180-WEG50VA-Ver4.1.8 ou posterior
Terminal Facial Pro WA08C-WZAM180-WEG80VA-Ver4.1.8 ou posterior

Modos de Comunicação Suportados​

O dispositivo opera de forma multithread e suporta dois canais principais para recebimento de comandos, ambos compartilhando o mesmo Motor de Execução de Comandos (Command Execution Engine). Isso garante que formatos de dados, interfaces e lógicas sejam idênticos, independentemente da topologia de rede.

  • Conexão Direta em LAN (WebServer API): O sistema de negócio comunica-se diretamente com o dispositivo na mesma rede local. Oferece latência mínima, sem necessidade de servidores intermediários. A autenticação é feita diretamente no dispositivo para a obtenção do Token.
Arquitetura em LAN
  • Modo Cloud PUSH (Push Command Channel) - Em Desenvolvimento ⚙️: Projetado para sistemas em nuvem ou cenários onde o dispositivo está em uma rede restrita (sem IP público ou portas abertas). O dispositivo mantém uma conexão proativa (Heartbeat) com um Push Server remoto. O sistema de negócio interage com o Push Server, que repassa os comandos ao dispositivo e devolve os resultados da execução.
Arquitetura em Cloud

Entrega de Eventos em Tempo Real (Webhooks)​

Independentemente de o dispositivo estar operando via LAN ou Cloud PUSH, os eventos de acesso (leitura de cartões, reconhecimento facial, etc.) são enviados ativamente para o sistema de negócio através de um canal Webhook.

  • Proativo: O dispositivo faz um POST direto para a URL configurada pelo sistema de negócio. Não é necessário fazer polling (consultas contínuas).
  • Resiliência: Em caso de falha na entrega, o sistema realiza tentativas automáticas (1s, 3s, 9s) e, se a falha persistir, armazena o evento em uma fila local para posterior resgate.

Especificação das Requisições​

Como o Motor de Execução é unificado, a estrutura das requisições e respostas é exatamente a mesma para comunicação direta (LAN) ou através do Push Server (Cloud).

Estrutura Geral​

Endereço do Serviço​

AmbienteBase URL
LAN Direta (Dispositivo)http(s)://{device_ip}:{device_port}
Cloud PUSH (Push Server)http(s)://{push_server_ip}:{port}

Parâmetros Comuns (Headers)​

Estes parâmetros devem ser incluídos uniformemente no cabeçalho HTTP de cada requisição para garantir a autenticação e o roteamento correto da carga útil.

ParâmetroTipoObrigatórioDescrição
AuthorizationStringSimToken de acesso no formato Bearer. Exemplo: Bearer <access_token_jwt>
Content-TypeStringSimTipo de conteúdo do corpo da requisição. Deve ser fixado como application/json

Padrões do Sistema​

  • Codificação: O sistema utiliza exclusivamente a codificação UTF-8.
  • Limite de Tamanho: O corpo (payload) de uma única requisição não deve exceder 2 MB.

Estrutura do Corpo da Requisição (Request Body)​

As chamadas aos endpoints de negócio devem seguir a estrutura JSON padronizada:

{
"param1": "val1",
"param2": "val2"
}
ParâmetroTipoObrigatórioDescrição
param1StringNãoValor do parâmetro especificado no endpoint.

Estrutura do Corpo da Resposta (Response Body)​

Todas as execuções retornam um formato unificado, processado pelo Motor de Execução, facilitando o tratamento de exceções pelo integrador.

{
"code": 0,
"mid": "req_1234567890abcdef",
"message": "success",
"data": {}
}
ParâmetroTipoDescrição
codeInteger / StringCódigo de status da operação. O processamento foi bem-sucedido se o valor indicar sucesso (ex: 0 ou "00000000" dependendo da configuração). Consulte a Referência de Códigos de Erro.
midStringIdentificador Único da Mensagem (Message ID). Gerado para cada transação e repassado em toda a cadeia para auditoria e troubleshooting.
messageStringDescrição textual da resposta. Utilizada para depuração.
dataObjectObjeto contendo os dados de retorno específicos da requisição.

Autenticação e Segurança (Token JWT)​

A segurança das chamadas de API é garantida através da emissão e validação de tokens JWT (JSON Web Tokens). No modo LAN, o dispositivo atua como o emissor. No modo Cloud PUSH, o servidor Push gerencia a autenticação perante o sistema de negócio.

AtributoRegra de Negócio / Descrição
Algoritmo de AssinaturaDefinido pelo firmware (padrão do dispositivo).
Tempo de ValidadeO padrão do terminal é de 3600 segundos (1 hora), customizável nas configurações.
Mecanismo de RenovaçãoObtenha um novo token sem interrupção solicitando ao endpoint /api/v1/auth/refresh.
Emissor (iss)Serviço de Autenticação da API (customizável no dispositivo).
Assunto (sub)Número de Série (SN) do terminal facial.
Emitido Em (iat)Timestamp Unix do momento de geração.
Expiração (exp)Timestamp Unix limitando a validade do token.
Função (role)Perfil do usuário (ex: admin, operator) - Opcional.