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.
|
Baixe o arquivo de prompt Escolha sua linguagem na próxima seção e baixe o arquivo de prompt em .txt. |
|
|
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. |
|
|
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.
|
|
|
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.