Quiosque de ponto

O quiosque é o ponto compartilhado: um tablet ou totem na entrada da empresa onde os colaboradores batem ponto sem login. A TAI oferece o quiosque pronto em https://app.taitecnologia.com/ponto/quiosque; as rotas desta página servem para quem quer construir a própria tela — um totem com leitor dedicado, um app de chão de fábrica — sobre o mesmo REP-P. A batida vale como qualquer outra: gera comprovante, entra no espelho e no AFD.

Quando usar	Um aparelho compartilhado registra o ponto de várias pessoas, sem o login de cada uma
Porta	Página pública (o aparelho) · REST (a preparação)
Você vai precisar	Módulo PONTO; permissão PONTO para cadastrar e parear o dispositivo, emitir crachás e cadastrar rostos; no aparelho, só o token do dispositivo

Como funciona

RH (autenticado)                              aparelho (sem login)
POST /ponto/dispositivo ──► dispositivo
POST /ponto/dispositivo/{id}/pareamento ──► código de 6 dígitos (10 min)
                                              POST /public/ponto/quiosque/parear ──► token
                                              GET  /public/ponto/quiosque/estado
                                              POST …/marcar  ou  …/identificar + …/marcar-identificado
                                                   ──► comprovante da batida

O token identifica o aparelho, não uma pessoa. Quem bate se identifica a cada marcação: CPF e PIN, crachá com QR ou rosto, conforme o que o dispositivo aceita.

Preparar o dispositivo

1. Cadastre o dispositivo na empresa do ponto (o empregador REP cujo AFD recebe as batidas — GET /ponto/empregador) e escolha as formas de identificação aceitas:

   POST /ponto/dispositivo
   
   {
     "nome": "Tablet da recepção",
     "local": "Portaria principal",
     "empregadorId": 3,
     "permiteCpfPin": true,
     "permiteCracha": true,
     "permiteFacial": false,
     "verificacaoCracha": "FOTO_AUDITORIA"
   }

   Pelo menos uma forma precisa ficar ligada. Com crachá, o tablet sempre tira uma foto do rosto: FOTO_AUDITORIA só guarda a foto, VALIDACAO_FACIAL exige que ela confira com o rosto cadastrado. Para o reconhecimento facial, limiarSimilaridade vai de 80 a 99.

2. Gere o código de pareamento. O código tem 6 dígitos, vale 10 minutos e é mostrado uma vez só:

   POST /ponto/dispositivo/27/pareamento

   { "codigo": "418273", "validadeMinutos": 10, "url": "/ponto/quiosque" }

3. No aparelho, troque o código por um token permanente:

   POST /public/ponto/quiosque/parear
   
   { "codigo": "418273" }

   { "token": "tai_rep_…", "estado": { "…": "…" } }

4. Guarde o token no aparelho e envie-o em todas as chamadas seguintes, sempre no cabeçalho:

   X-Dispositivo-Token: tai_rep_…

Cuidado

Guarde o token como segredo. Se o aparelho for perdido ou trocado, revogue-o (PUT /ponto/dispositivo/{id}/revogar, ou Departamento Pessoal › Ponto › Configurações › Tablets de ponto na plataforma): as chamadas do aparelho passam a responder 410. Um dispositivo revogado não volta — cadastre outro.

Preparar as pessoas

Forma	O que a pessoa precisa	Pela API
CPF e PIN	Um PIN de 4 a 6 dígitos	A pessoa define em Perfil › Segurança; o RH define ou redefine com PUT /ponto/colaborador-config/colaborador/{colaboradorId}/pin
Crachá	Um crachá com QR emitido	POST /ponto/cracha/colaborador/{colaboradorId}/emitir, ou em lote (até 200) com POST /ponto/cracha/lote/emitir; o PDF para imprimir sai em GET /ponto/cracha/lote/pdf (8 por folha A4)
Rosto	Um rosto cadastrado	A partir da foto do cadastro, em lote (até 25 por chamada): POST /ponto/biometria/lote/da-foto-cadastro

GET /ponto/biometria/situacao diz quem já tem crachá e rosto cadastrado. Reemitir um crachá (POST /ponto/cracha/colaborador/{colaboradorId}/reemitir) invalida o QR anterior.

Estado do dispositivo

GET /public/ponto/quiosque/estado
X-Dispositivo-Token: tai_rep_…

Devolve o dispositivo, o empregador (razão social, CNPJ, local), os métodos habilitados (cpfPin, cracha, facial, validaRostoCracha) e horaServidor em ISO 8601 com fuso. Use a hora do servidor no relógio da tela: a hora legal da batida é a do servidor, nunca a do aparelho.

Marcar por CPF e PIN

POST /public/ponto/quiosque/marcar
X-Dispositivo-Token: tai_rep_…

{ "cpf": "12345678909", "pin": "4821", "chaveIdempotencia": "b3f1c6e2-…" }

A resposta traz o comprovante da marcação (comprovante), o primeiro nome da pessoa (primeiroNome) e se o comprovante foi enviado por e-mail (emailEnviado).

Envie sempre chaveIdempotencia (um UUID por tentativa): se a rede cair depois do envio e a marcação for repetida com a mesma chave, ela não é registrada duas vezes.

Marcar por crachá ou rosto

Dois passos: identificar e confirmar.

POST /public/ponto/quiosque/identificar
X-Dispositivo-Token: tai_rep_…

{ "tipo": "CRACHA", "qr": "…" }          ← ou { "tipo": "FACIAL", "foto": "<base64>" }

A resposta traz um desafio (válido por 90 segundos), o nome da pessoa e exigeFoto — se é preciso enviar a foto do rosto para confirmar. Mostre o nome na tela antes de confirmar: é a chance de a pessoa dizer “não sou eu”. Em seguida:

POST /public/ponto/quiosque/marcar-identificado
X-Dispositivo-Token: tai_rep_…

{ "desafio": "…", "foto": "<base64>", "chaveIdempotencia": "…" }

Comprovante

GET /public/ponto/quiosque/comprovante/{codigo}/pdf devolve, no próprio aparelho, o comprovante em PDF de uma batida feita nele nas últimas 48 horas. Qualquer pessoa pode conferir um comprovante a qualquer tempo, sem login — veja Validar comprovante de ponto.

Respostas de erro

Status	Significado
400	Identificação expirada, foto ausente ou rosto que não confere com o dono do crachá
401	Credencial inválida (a mensagem é genérica de propósito: não diz se o CPF existe)
403	O dispositivo não aceita essa forma de identificação, ou a pessoa não registra ponto
404	Código de pareamento inválido ou vencido
410	Dispositivo revogado — descarte o token e volte à tela de pareamento
423	PIN bloqueado por 15 minutos após 5 erros
429	Limite excedido

Limites

Rota	Limite por minuto
parear	10
estado	120
marcar, marcar-identificado	60 por IP
marcar	5 por dispositivo e CPF
identificar	60 por IP e 40 por dispositivo
Comprovante em PDF	60

Cuidados

• Sem fila off-line. O quiosque não guarda batida para enviar depois: sem rede, a marcação não acontece, e a tela deve dizer isso. Uma batida que “entrou” sem resposta do servidor não existe.
• O token nunca vai na URL. Mande-o só no cabeçalho X-Dispositivo-Token, para não aparecer em logs de acesso.
• Uma empresa por aparelho. O dispositivo registra o ponto do empregador em que foi cadastrado; uma pessoa de outra empresa recebe 403.
• As rotas /public/ponto/quiosque/* são descritas só nesta página; a referência do ponto cobre as rotas autenticadas.