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 Facial | Firmware |
|---|---|
| Terminal Facial Go WA02-FW | ZAM70-WEG24HA-Ver3.3.15 ou posterior |
| Terminal Facial Go WA03C-W | ZAM70-WEG28VA-Ver3.3.15 ou posterior |
| Terminal Facial Core WA04C-W | ZAM70-WEG43VA-Ver3.3.15 ou posterior |
| Terminal Facial Core WA07C-W | ZAM70-WEG70VA-Ver3.4.15 ou posterior |
| Terminal Facial Pro WA05C-W | ZAM180-WEG50VA-Ver4.1.8 ou posterior |
| Terminal Facial Pro WA08C-W | ZAM180-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.

- 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.

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
POSTdireto 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
| Ambiente | Base 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | String | Sim | Token de acesso no formato Bearer. Exemplo: Bearer <access_token_jwt> |
| Content-Type | String | Sim | Tipo 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| param1 | String | Não | Valor 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âmetro | Tipo | Descrição |
|---|---|---|
| code | Integer / String | Có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. |
| mid | String | Identificador Único da Mensagem (Message ID). Gerado para cada transação e repassado em toda a cadeia para auditoria e troubleshooting. |
| message | String | Descrição textual da resposta. Utilizada para depuração. |
| data | Object | Objeto 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.
| Atributo | Regra de Negócio / Descrição |
|---|---|
| Algoritmo de Assinatura | Definido pelo firmware (padrão do dispositivo). |
| Tempo de Validade | O padrão do terminal é de 3600 segundos (1 hora), customizável nas configurações. |
| Mecanismo de Renovação | Obtenha 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. |