Perguntas frequentes, SDK e custo

Dúvidas comuns de integradores, além de como funcionam o SDK e os preços da API.

Informações adicionais

Perguntas frequentes

Dúvidas comuns sobre a integração com a Cams Biometrics Web API 3.0.

Geral

P: O que é o Cams Biometric Gateway e sua API biométrica?
O Cams Biometric Gateway é uma plataforma universal na nuvem que expõe uma API biométrica que permite a qualquer aplicação web se comunicar em tempo real com equipamentos biométricos de ponto e controle de acesso. Ele suporta 38 operações entre APIs de callback (entrada) e RESTful (saída), sem exigir SDK de equipamento nem IP estático.
P: Preciso de um SDK para integrar?
Não. A Cams não fornece nem exige um SDK. Toda a comunicação usa requisições HTTP/HTTPS POST padrão com payloads JSON. Qualquer linguagem capaz de fazer chamadas HTTP funciona.
P: Quais linguagens de programação são compatíveis?
Qualquer linguagem que consiga enviar/receber HTTP POST com JSON — PHP, Python, Java, C#, Node.js, Go, Ruby e outras. Oferecemos prompts de IA para gerar código em 7 linguagens.
P: O que é o Cams Protocol Engine?
É o middleware na nuvem que fica entre os equipamentos biométricos e o seu servidor. Ele cuida da tradução de protocolos, da normalização de dados e do cache offline, e entrega uma API JSON consistente independentemente da marca ou do modelo do equipamento.
P: O que é o API Monitor?
O API Monitor é o seu portal de administração, onde você configura as URLs de callback, gerencia os AuthTokens, define as Security Keys, consulta o status dos equipamentos e acessa a URL do seu endpoint RESTful e os Service Tag IDs.

Compatibilidade de equipamentos

P: Quais equipamentos biométricos são compatíveis?
Todos os equipamentos da Cams Biometrics (listados em camsbiometrics.com/product) suportam a API completa com Native Push. Os equipamentos verificados em developer.camsbiometrics.com também têm suporte completo a Native Push.
P: Equipamentos que não são da Cams (ZkTeco, eSSL, BioMax etc.) podem usar esta API?
Sim, com uma Protocol Update. Equipamentos que não são da Cams e não são verificados operam via Hybrid Push. Alguns recursos podem ser limitados dependendo do modo de conexão e dos recursos do hardware.
P: Qual é a diferença entre Native Push e Hybrid Push?
Native Push: suporte completo à API, sem limitações: todas as 38 operações funcionam. Disponível para equipamentos Cams e equipamentos verificados.
Hybrid Push: para equipamentos que não são da Cams nem verificados. A disponibilidade de recursos depende do modo de comunicação (SDK, DB Pull ou processamento de arquivos). Veja os modos de conexão.
P: Quais métodos biométricos são suportados?
Impressão digital, reconhecimento facial, veias da palma, cartão RFID/de proximidade, PIN/senha numérico, leitura de íris e medição da temperatura corporal (dependendo do equipamento).
P: Alguns recursos da API não funcionam com o meu equipamento. Por quê?
Depende (a) do modo de conexão — os modos DB Pull e processamento de arquivos só suportam envio de ponto, não as APIs RESTful, e (b) das limitações de hardware — alguns modelos de equipamento podem não suportar determinados recursos no nível do firmware. Teste com o seu hardware e entre em contato com o suporte da Cams para obter ajuda.

API de callback (Equipamento → Servidor)

P: O que é a API de callback?
A API de callback entrega ao seu servidor os eventos em tempo real dos equipamentos biométricos. Quando ocorre uma marcação ou um usuário é alterado no equipamento, o Cams Protocol Engine envia (POST) imediatamente um payload JSON para a sua URL de callback configurada.
P: O que o meu servidor deve responder?
Retorne sempre {"status":"done"} com status HTTP 200 — mesmo que o seu processamento interno falhe. Nunca bloqueie o Cams Protocol Engine. Coloque o processamento pesado em fila para execução assíncrona.
P: O que acontece se o meu servidor estiver offline quando ocorrer uma marcação?
O Biometric Gateway guarda todos os eventos em cache e os entrega automaticamente assim que o seu servidor voltar a ficar online. Nenhum dado é perdido.
P: Como trato marcações duplicadas?
Implemente no seu servidor uma lógica de detecção de duplicidade usando a combinação de UserID + LogTime. A mesma marcação pode ser reenviada durante a recuperação após uma queda de conexão ou em novas tentativas de rede.
P: Quais tipos de marcação são suportados?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. O campo InputType mostra o método biométrico utilizado: Fingerprint, Face, Palm, Card ou Password.
P: Como funcionam os templates de usuário nos callbacks?
Quando um usuário é atualizado no equipamento (operações nº 3–9), os templates podem chegar um a um ou em grupos ao longo de vários callbacks. Cada callback traz apenas os templates que mudaram, não o conjunto completo. Seu servidor deve fazer um merge/upsert usando Type + Index como chave única. Nunca sobrescreva todos os templates com um único callback.
P: Posso receber fotos de ponto?
Sim. A operação nº 10 RealTimeAttendancePhoto entrega um JPEG codificado em Base64 capturado no momento da marcação. Ela é separada do callback do registro de marcações (nº 11) e está disponível em equipamentos com câmera.
P: O callback inclui temperatura e detecção de máscara?
Sim, se o equipamento suportar. O objeto PunchLog inclui Temperature (leitura da temperatura corporal) e FaceMask (booleano — indica se uma máscara facial foi detectada).

API RESTful (Servidor → Equipamento)

P: O que é a API RESTful?
A API RESTful permite que o seu servidor envie comandos a equipamentos biométricos — adicionar/excluir usuários, carregar registros, cadastrar biometrias e controlar o acesso. Você envia (POST) JSON para a URL do endpoint disponível na sua conta do API Monitor.
P: Onde encontro a URL do meu endpoint RESTful?
Faça login na sua conta do API Monitor. A URL do seu endpoint RESTful e os Service Tag IDs (stgid) estão listados lá.
P: Qual é a latência dos comandos RESTful?
Aproximadamente 15 segundos. O Biometric Gateway enfileira o seu comando e o entrega ao equipamento na próxima vez que ele se conectar (o que é quase contínuo para equipamentos online).
P: Qual é o intervalo máximo de datas do LoadLog?
O máximo recomendado é de 30 dias por requisição. Para intervalos maiores, faça várias requisições com janelas de tempo consecutivas.
P: Posso adicionar um usuário com vários templates biométricos de uma só vez?
Sim. O array Template aceita várias entradas. Por exemplo, a operação nº 27 adiciona um usuário com Card + Fingerprint + Password + Face + Palm + UserPhoto em uma única requisição.
P: O que acontece se o equipamento estiver offline quando eu enviar um comando RESTful?
O Biometric Gateway enfileira o comando e o entrega automaticamente quando o equipamento se reconecta. Você receberá o código de status 5 (Equipamento offline) se o equipamento não responder dentro do tempo limite.
P: Como verifico o resultado de um comando?
As respostas RESTful incluem um campo StatusCode. O código 0 significa sucesso. Veja os códigos de status da resposta para a lista completa de códigos de erro e seus significados.
P: Posso iniciar o cadastro de impressão digital remotamente?
Sim. A operação nº 35 EnrollFingerPrint inicia uma sessão de cadastro no equipamento. No entanto, o usuário precisa estar fisicamente presente no equipamento para escanear o dedo.

Segurança e rede

P: Posso usar HTTPS nos callbacks?
Sim. HTTPS com certificado SSL válido na porta 443 é totalmente suportado e recomendado para produção.
P: A criptografia é obrigatória?
Não. A criptografia AES-256 é opcional. Para habilitá-la, configure uma Security Key no API Monitor. Depois de habilitada, todos os payloads JSON são criptografados/descriptografados com AES/ECB/PKCS5PADDING e codificação Base64.
P: Como valido que um callback realmente vem da Cams?
Todo callback inclui um campo AuthToken. Compare-o com o token configurado no seu API Monitor. Rejeite qualquer requisição com token divergente.
P: Quais portas devo abrir?
A porta 80 (HTTP) ou 443 (HTTPS) para produção. A porta 8123 está disponível somente para testes. Veja as portas compatíveis.
P: Como testo localmente sem publicar em um servidor?
Use um IP público com redirecionamento de portas ou uma ferramenta de túnel como o ngrok. Veja os testes locais para um passo a passo.

Dados e considerações de design

P: Qual formato de dados a API usa?
Todas as requisições e respostas são JSON bruto com codificação UTF-8. Use o cabeçalho Content-Type: application/json. Sem codificação de formulário.
P: Qual formato de carimbo de data/hora é usado?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (p. ex., 2020-09-17 07:48:22 GMT +0530). O campo Time está em UTC; os carimbos de data/hora locais do equipamento (como LogTime, OperationTime) podem usar um deslocamento de fuso horário diferente.
P: Como devo tratar marcações offline e dados retroativos?
Projete sua aplicação para aceitar marcações que cheguem fora de ordem cronológica. Quando um equipamento ficou offline, ele enviará as marcações em cache assim que se reconectar. Pode ser necessário atualizar retroativamente o status de presença (p. ex., mudar para "presente" um usuário que aparecia como "ausente").
P: Como determino ENTRADA/SAÍDA quando um usuário tem vários equipamentos?
Ordene todas as marcações de um usuário por LogTime entre todos os equipamentos e depois aplique a sua regra de negócio. Não confie apenas no campo Type (CheckIn/CheckOut) de um único equipamento se o usuário marca em máquinas diferentes.
P: O que é o OperationID e como devo usá-lo?
Um identificador em string único para cada operação. Nos callbacks recebidos, ele é gerado pelo Biometric Gateway. Nas requisições RESTful enviadas, você deve gerar um único por requisição (UUID ou baseado em carimbo de data/hora). A resposta o devolve para que você possa correlacionar os pares requisição/resposta.
P: Como os templates biométricos são armazenados e transmitidos?
Os dados biométricos (impressão digital, rosto, palma, foto do usuário) são codificados em Base64 no campo Data do objeto Template. Os templates de impressão digital e de rosto também incluem Size (tamanho em bytes) e Index (número da posição). Números de cartão e PINs são strings em texto simples.

Preços e licenciamento

P: Como a API é licenciada?
Por equipamento biométrico. O primeiro ano exige Ativação da API + Licença anual. Nos anos seguintes, apenas a renovação da licença anual. Veja o custo da API para os preços.
P: O que acontece se a minha licença da API expirar?
A comunicação da API desse equipamento é interrompida até que a licença seja renovada. Seus dados existentes não são afetados, mas nenhum novo callback ou comando RESTful será processado.
P: Existe uma opção local (on-premise)?
Sim. O Protocol Engine Lite pode ser instalado no seu próprio servidor (Windows/Linux) para ambientes somente LAN ou auto-hospedados. Escreva para sales@camsbiometrics.com para mais detalhes.
Informações adicionais

SDK de ponto biométrico

A Cams não fornece um SDK tradicional. Todas as operações usam as APIs padrão de callback HTTP e RESTful — não é necessário instalar nenhuma biblioteca.

Nenhum SDK necessário. A comunicação é tratada inteiramente pelo Cams Protocol Engine, por meio de URLs de callback e endpoints HTTP RESTful.

Isso simplifica a integração com qualquer plataforma web:

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooAplicações web sob medida
Informações adicionais

Custo da API

As licenças da API são cobradas por equipamento biométrico. Primeiro ano = ativação + licença; anos seguintes = somente renovação da licença.

ServiçoUSDObservações
Native Push — Equipamentos Cams e verificados
Ativação da API$120Pagamento único por equipamento.
Licença anual da API$60 – $120Renovação anual obrigatória.
Protocol Update (não Cams)$120 – $280Pagamento único. Habilita o protocolo da Cams em equipamentos que não são da Cams.
Hybrid Push — ZKTeco, eSSL e todas as marcas de terceiros
Ativação da API$150Pagamento único por equipamento.
Licença anual da API$90 – $150Renovação anual obrigatória.
Hybrid Connector (não verificado)$150 – $300Pagamento único. Obrigatório para equipamentos não verificados que usam Hybrid Push.
Hardware e outros
Hardware$220 – $720Varia conforme o modelo.
Protocol Engine Lite (on-premise) — Para ambientes somente LAN ou auto-hospedados. Custo: $500–$10,000. Fale com vendas para mais detalhes.