Support Hub/API & Integrations/Como Criar um Receptor de Callback Biométrico em Python,…
Translated from the English article and reviewed by a person. Read the English original
Developer

Como Criar um Receptor de Callback Biométrico em Python, Node.js e PHP

Como Criar um Receptor de Callback Biométrico em Python, Node.js e PHP

Um receptor de callback é a pequena parte de código que transforma cada leitura de impressão digital, facial ou de cartão em um registro no seu próprio sistema. O Cams Biometrics Gateway envia cada leitura verificada ao seu servidor como uma requisição JSON, e o seu servidor responde para confirmar que ela foi recebida. Você não precisa escrever esse receptor do zero. A Cams disponibiliza Prompts Geradores de Código com IA para Python, Node.js e PHP: cole um deles em um assistente de IA, como o Claude ou o ChatGPT, e você obtém um arquivo completo e funcional com um receptor de callback, um cliente REST e uma interface de teste. Este tutorial explica o que um receptor deve fazer, como gerar um para a sua linguagem, como configurá-lo e como testá-lo antes de colocá-lo em produção.

01 · As Seis Funções

O Que um Receptor de Callback Precisa Fazer

Independentemente da linguagem usada, todo receptor de callback biométrico desempenha as mesmas seis funções. Estas também são as itens a verificar em qualquer código que você gerar.

Função O que significa Por que é importante
1. Aceitar a requisição Receber um POST HTTP/HTTPS com um corpo JSON bruto É assim que o Gateway entrega cada evento
2. Verificar o token Comparar o AuthToken com o token de callback esperado Impede que outras pessoas enviem registros de ponto falsos para a sua URL
3. Direcionar por tipo de evento Verificar qual chave está dentro de RealTime e tratá-la de acordo Nem todo callback é uma marcação de ponto; alguns informam fotos ou alterações de usuários
4. Ignorar duplicados Usar o OperationID para ignorar eventos que você já salvou Uma entrega repetida nunca se transforma em um registro duplicado
5. Armazenar e registrar Salvar os campos de que você precisa e registrar cada callback Cria o registro que o seu HRMS, folha de pagamento ou painel irá utilizar
6. Responder com done Retornar {“status”:”done”} com HTTP 200 Informa ao Gateway que o evento chegou com segurança

02 · Conheça Seus Dados

O Payload Que Você Vai Receber

O callback mais comum é um registro de ponto, enviado sempre que alguém realiza uma leitura. Salve este exemplo como sample.json, pois você o usará para testar seu receptor mais adiante.

API de Callback, requisição PunchLog enviada ao seu receptor

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

Após processar qualquer callback, seu receptor deve responder com HTTP 200 e exatamente este corpo:

API de Callback, resposta que o seu receptor deve retornar

{ "status": "done" } (HTTP 200)

Tipos de evento de callback

Todo callback chega dentro de um objeto RealTime. Seu receptor decide o que fazer verificando qual destas chaves está presente:

Chave dentro de RealTime O que informa
PunchLog Uma leitura de ponto: quem, entrada ou saída, quando e como
UserUpdated Os dados de um usuário foram atualizados no dispositivo

Dois detalhes que pegam os desenvolvedores de surpresa

Detalhe O que observar
A chave de resposta está em minúsculas Retorne status em minúsculas com o valor done. Não copie o campo Status com inicial maiúscula das respostas da API RESTful
O formato de LogTime O LogTime tem a forma 2020-09-17 07:48:22 GMT +0530. Ele representa o horário real da leitura, com o deslocamento de fuso do dispositivo. Faça o parse considerando esse deslocamento e use-o como horário de ponto

03 · Deixe a IA Escrever o Código

Gere Seu Receptor com Prompts Geradores de Código com IA

A Cams publica um arquivo de prompt pronto para cada linguagem de servidor suportada. Cada prompt contém um resumo da especificação da Cams Web API 3.0 e instruções claras sobre o que construir. Você o cola em um assistente de IA, e o assistente gera uma implementação completa em um único arquivo para a sua stack.

1

Baixe o arquivo de prompt

Escolha sua linguagem na próxima seção e baixe o arquivo de prompt em .txt.

2

Cole em um assistente de IA

Abra o Claude, o ChatGPT, o Copilot ou qualquer ferramenta de codificação com IA e cole o conteúdo completo do prompt.

3

Obtenha um arquivo completo e funcional

A IA gera um único arquivo. Defina os valores de configuração, implante-o e execute-o.

Cada arquivo gerado inclui O que faz
Receptor de callback Lê o corpo bruto do POST, valida o AuthToken, direciona por tipo de evento, registra cada callback, armazena os registros de ponto, salva as fotos de presença e responde com done
Cliente REST Uma função genérica de requisição, além de funções wrapper para todas as 27 operações RESTful, como AddUser, DeleteUser, ResendAllUser e UpdateAccessTime
Interface HTML de teste Uma página no navegador com os campos de configuração, uma lista suspensa de operações, um editor JSON pré-preenchido com modelos de requisição, um visualizador de respostas e uma lista dos callbacks recentes

A documentação hospedada vem primeiro

Cada prompt instrui a IA a ler a documentação completa da Cams Web API e a tratá-la como fonte oficial para operações, esquemas JSON, nomes de campos e códigos de resposta. Se algo no resumo do prompt entrar em conflito com a documentação hospedada, a documentação prevalece.

04 · Escolha Sua Linguagem

Prompts para Python, Node.js e PHP

Cada prompt é ajustado para produzir código idiomático, com dependências mínimas para a sua linguagem.

Python

Flask, SQLite, apenas biblioteca padrão

Baixar prompt Python

Node.js

Express, armazenamento em arquivo JSON

Baixar prompt Node.js

PHP

PHP puro, SQLite, sem Composer

Baixar prompt PHP

Também há prompts disponíveis para C# (.NET 8) com Minimal API, Java com o HttpServer integrado e sem dependências, Go com net/http e apenas a biblioteca padrão, e Ruby com Sinatra e SQLite. Você pode encontrar todos eles na seção Prompts Geradores de Código com IA da documentação da Cams Web API. Obter Prompts.

05 · Três Valores a Definir

Configurando o Arquivo Gerado

O arquivo gerado possui um bloco de configuração no topo. Na versão PHP ele se parece com isto, e as outras linguagens usam os mesmos três valores:

Bloco de configuração, versão PHP

$CONFIG = [
    'base_url'            => 'https://YOUR_RESTFUL_ENDPOINT_URL',
    'stgid'               => 'YOUR_SERVICE_TAG_ID',
    'auth_token'          => 'YOUR_AUTH_TOKEN',
];
Configuração O que informar
base_url A URL do endpoint RESTful da sua conta Cams API Monitor
stgid Seu ID de Service Tag.
auth_token Seu AuthToken, incluído nas requisições RESTful de saída e verificado em relação ao AuthToken nas requisições de callback recebidas.

Mantenha os tokens fora de códigos compartilhados

Para um teste rápido, digitar os valores no bloco de configuração é aceitável. Antes da produção, mova os tokens para variáveis de ambiente ou para um gerenciador de segredos, para que nunca acabem no controle de versão ou em um arquivo compartilhado.

Depois de configurado e implantado em um endereço HTTPS público, defina esse endereço como a URL de Callback no Cams Gateway. A partir daí, cada leitura verificada chegará ao seu receptor em tempo real.

06 · Teste Antes de Conectar os Dispositivos

Testando Seu Receptor

Você não precisa de um dispositivo biométrico para testar o receptor de callback. Envie a ele o payload de exemplo com o cURL, usando um token de callback correspondente, e verifique a resposta.

Terminal, envie um callback de teste

# Salve o payload de exemplo como sample.json e envie-o ao seu receptor:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
  -H "Content-Type: application/json" \
  -d @sample.json

# Resposta esperada (HTTP 200):
# {"status":"done"}
Teste O que enviar Resultado esperado
Evento válido sample.json, com o AuthToken definido como seu auth_token HTTP 200 com done, e a marcação é salva
Evento duplicado A mesma requisição uma segunda vez HTTP 200 com done, e nenhum segundo registro é salvo
Token incorreto sample.json com um AuthToken diferente Rejeitado, e nada é salvo
Evento de entrada sample.json com Type alterado para CheckIn Salvo como entrada
Operação RESTful Use a interface HTML de teste integrada para enviar uma operação Uma resposta com Status e StatusCode

A interface HTML de teste gerada facilita a experimentação do lado RESTful: abra o arquivo em um navegador, escolha uma operação na lista suspensa, ajuste o JSON pré-preenchido e envie-o. O visualizador de callbacks recentes na mesma página confirma que seus callbacks de teste foram recebidos.

07 · Lista de Verificação para Produção

Revise Antes de Entrar em Operação

O código gerado por IA é um ponto de partida rápido e confiável, mas, como qualquer código, deve ser revisado antes de tratar dados reais de funcionários.

Item Concluído quando
Código revisado Um desenvolvedor leu o arquivo gerado e entende a função de cada seção
Somente HTTPS O receptor só é acessível via HTTPS, com um certificado válido
Tokens protegidos Os AuthTokens são armazenados em variáveis de ambiente ou em um gerenciador de segredos
Duplicados tratados O OperationID é armazenado e verificado para que entregas repetidas sejam ignoradas
Armazenamento adequado O armazenamento em arquivo JSON atende instalações pequenas; implantações maiores podem migrar para um banco de dados de produção
Interface de teste protegida A página HTML de teste é protegida por senha ou desativada em servidores públicos
Fotos tratadas com cuidado As fotos de presença salvas em disco têm acesso controlado e são mantidas apenas pelo tempo necessário
Monitoramento implantado Erros e volumes incomuns de callbacks são registrados e geram alertas no seu próprio monitoramento

Mantenha as regras de negócio em outro lugar

A função do receptor é aceitar, verificar, direcionar, armazenar e confirmar. Decidir quem chegou atrasado, calcular horas extras ou enviar avisos cabe aos sistemas que leem os eventos armazenados, como o seu HRMS, ERP ou ferramentas de automação. Um receptor focado é mais fácil de proteger e manter.

Perguntas Frequentes

Preciso escrever algum código por conta própria?

Normalmente não. Os Prompts Geradores de Código com IA produzem um arquivo completo e funcional. Você define três valores de configuração, implanta o arquivo e o testa. Um desenvolvedor ainda deve revisar o código antes da produção.

Quais assistentes de IA funcionam com os prompts?

Qualquer assistente de codificação com IA capaz, incluindo Claude, ChatGPT e Copilot. Cole o conteúdo completo do prompt de uma só vez, para que o assistente tenha a especificação inteira.

Onde encontro a URL do endpoint RESTful e o ID da Service Tag?

Ambos vêm da sua conta Cams API Monitor. As requisições RESTful são enviadas à URL do endpoint com ?stgid= seguido do seu ID de Service Tag.

Por que responder com done para um evento duplicado?

Porque o evento de fato chegou com segurança, mesmo que você já o tivesse salvo. Responder com done informa ao Gateway que ele não precisa enviá-lo novamente.

Posso usar uma linguagem que não está listada?

Sim. O receptor de callback só precisa aceitar um POST HTTPS e retornar JSON. Os prompts são um atalho, e a mesma API funciona com qualquer linguagem que consiga fazer isso.

Conclusão: Do Prompt à Presença em Tempo Real em Uma Tarde

Um receptor de callback biométrico é pequeno, mas é a peça que transforma cada leitura verificada em dados em tempo real para o seu HRMS, folha de pagamento, painéis e automações. Com os Prompts Geradores de Código com IA da Cams, você não precisa mais construí-lo a partir de uma página em branco. Baixe o prompt para Python, Node.js ou PHP, cole-o no seu assistente de IA, defina três valores e teste. Depois, revise-o, proteja-o e deixe que os dados de presença em tempo real comecem a fluir.

O Cams Biometrics Gateway entrega os eventos de que o seu receptor precisa. Sua API de Callback envia cada leitura verificada em tempo real, em um formato JSON consistente, a partir de dispositivos de mais de 15 marcas, e sua API RESTful oferece 27 operações que o cliente gerado pode chamar. Toda a comunicação ocorre via HTTP/HTTPS, com validação de auth token e criptografia AES-256 opcional. Conheça a plataforma em CamsBiometrics.com e leia a documentação completa da Web API, incluindo todos os Prompts Geradores de Código com IA: Obter Prompts.

 

Was this article helpful?