Referência da API: arquitetura, campos e códigos de status

Os componentes comuns a todas as operações: fluxo de requisições, campos JSON comuns, tipos de template, códigos de status, portas e criptografia do payload.

Referência da API

Arquitetura da API

Propriedade	API de callback	API RESTful
Iniciador	Equipamento / Biometric Gateway	Seu servidor
Direção	Equipamento → Seu servidor	Seu servidor → Equipamento
Latência	Tempo real (milissegundos)	~15 segundos
Gatilho	Evento biométrico no equipamento	HTTP POST a partir do seu código
Seu papel	Receber e confirmar	Enviar o comando e consultar/aguardar a resposta
Corpo da resposta	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
Comportamento offline	Armazenado em cache pelo motor; entregue quando o servidor voltar a ficar online	Enfileirado pelo motor; entregue quando o equipamento se reconectar

Referência da API

Campos comuns

Todas as requisições, tanto de callback quanto RESTful, compartilham estes campos de nível superior.

AuthTokenString. Um token de 32 caracteres que identifica e autentica as requisições de um equipamento específico. Configurado no portal API Monitor. Valide-o em todo callback recebido.

OperationIDString. Um identificador único desta instância de operação (p. ex. "j95xfejt3vr1"). As respostas RESTful devolvem o mesmo OperationID para que você possa associar requisições e respostas.

TimeString. Carimbo de data/hora UTC de quando o evento foi processado, no formato YYYY-MM-DD HH:mm:ss GMT +0000. Os carimbos de data/hora locais do equipamento dentro do payload podem usar um deslocamento de fuso horário diferente.

stgid (parâmetro de consulta)String. Service Tag ID: identifica o equipamento de destino nas chamadas da API RESTful. Passe-o como parâmetro de consulta da URL no endpoint disponível na sua conta do API Monitor: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Tipos de template

Os dados biométricos e de credenciais são transportados em um array Template. Cada item possui um campo Type:

Comportamento de mesclagem de templates — Importante para os manipuladores de callback
Quando os dados do usuário são enviados pelo equipamento (operações de callback nº 3–9), os templates podem chegar um a um ou em grupos, ao longo de vários callbacks. Cada callback não contém o conjunto completo de templates do usuário: ele traz apenas os templates adicionados ou alterados.

Seu servidor deve mesclar (merge) os templates recebidos com os templates já armazenados desse usuário. A chave única de cada template é Type + Index. Por exemplo:
• O callback 1 chega com Fingerprint Index 0 → armazene-o
• O callback 2 chega com Face Index 0 + Card → mescle, sem sobrescrever a digital
• O callback 3 chega com Fingerprint Index 0 (dados novos) → atualize a digital existente no Index 0
Nunca substitua todos os templates em um callback: faça sempre um upsert por Type + Index.

Tipo	Descrição	Principais campos extras
`Card`	Número do cartão RFID / de proximidade	`Data` (string com o número do cartão)
`Password`	PIN numérico	`Data` (string do PIN)
`Fingerprint`	Template de impressão digital — binário codificado em Base64	`Index` (índice do dedo 0–9), `Size`, `Data`
`Face`	Template facial — JPEG ou binário codificado em Base64	`Index`, `Size`, `Data`
`Palm`	Template de veias da palma — binário codificado em Base64	`Index`, `Data`
`UserPhoto`	Foto de perfil do usuário — JPEG codificado em Base64	`Data`

Referência da API

Códigos de status da resposta

As respostas da API RESTful incluem um StatusCode numérico. As respostas da API de callback sempre usam a forma simples {"status":"done"}, independentemente do resultado.

Código	Status	Descrição
`0`	Sucesso	A operação foi concluída com sucesso.
`1`	Dados da requisição inválidos	O corpo JSON está malformado ou contém valores inválidos.
`2`	Service Tag ID inválido	O parâmetro de consulta `stgid` não corresponde a nenhum equipamento registrado.
`3`	Requisição inválida	A estrutura da requisição não corresponde ao formato esperado da operação.
`4`	Criptografia inválida	Não foi possível descriptografar o payload criptografado (AES-256). Verifique sua chave de criptografia.
`5`	Equipamento offline	O equipamento de destino não está conectado ao Biometric Gateway no momento.
`6`	Tempo limite da operação esgotado	O equipamento não confirmou o comando dentro do tempo limite.
`7`	AuthToken inválido	O `AuthToken` da requisição não corresponde ao token configurado do equipamento.
`8`	Usuário já existe	Foi tentada uma operação Add para um UserID que já existe no equipamento.
`9`	Usuário não encontrado	O UserID especificado não existe no equipamento.
`10`	Erro de template	Os dados do template biométrico estão corrompidos ou em um formato não suportado.
`11`	Memória do equipamento cheia	O equipamento atingiu a capacidade máxima de usuários ou templates.
`13`	Chave de segurança inválida	A chave de segurança configurada no API Monitor não corresponde.
`15`	Recurso não suportado	A operação solicitada não é suportada por este modelo de equipamento ou modo de comunicação.
`999`	Erro desconhecido	Ocorreu um erro inesperado. Entre em contato com o suporte da Cams informando o OperationID.

Informações adicionais

Portas compatíveis

Para receber informações de ponto em tempo real, seu servidor deve expor um endpoint HTTP(S) que o Cams Protocol Engine consiga acessar.

Porta	Protocolo	Uso
`80`	HTTP	Produção. Vincule sua URL de callback à porta 80. Configurada no API Monitor e chamada automaticamente a cada marcação.
`443`	HTTPS	Produção (seguro). HTTPS com certificado SSL válido. Recomendado para produção.
`8123`	HTTP	Somente para testes. Porta não padrão disponível temporariamente durante o desenvolvimento.

HTTPS recomendado. Use HTTPS com um certificado SSL válido em produção. Garanta a renovação automática sem reiniciar o servidor.

Informações adicionais

Dados de exemplo

Exemplos de payloads de requisição e resposta das 38 operações estão documentados acima, na seção de cada operação. Para uma visão consolidada:

Esta páginaCada seção de operação acima inclui JSON de requisição e resposta pronto para copiar, com dados de exemplo.

Página de exemplos legadabiometric-web-api-sample-request-response.html — seletor suspenso para cada operação.

Informações adicionais

Criptografia

É possível habilitar a criptografia AES-256 opcional para todos os dados trocados entre o Cams Protocol Engine e o seu servidor.

AlgoritmoAES-256 no modo ECB com padding PKCS5 (AES/ECB/PKCS5PADDING).

Configuração da chaveDefina sua chave como Security Key no API Monitor. Depois de configurada, todos os payloads JSON brutos são criptografados.

CodificaçãoOs payloads criptografados são codificados em Base64 para transporte HTTP seguro.

Exemplo em Java

Criptografar / descriptografar (Java)

// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));

// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");

Importante: Quando a criptografia está habilitada, descriptografe os payloads de callback recebidos e criptografe os corpos das requisições RESTful enviadas usando a mesma chave.