22 KiB
Manual do usuário — Bot de Pontos
O Bot de Pontos avisa pelo Telegram a hora de voltar do almoço e a hora de encerrar a jornada, com base nos pontos que você registra na PontoMais.
Este manual tem duas partes:
- Parte 1 — Usuário: para quem recebe os lembretes pelo Telegram.
- Parte 2 — Administrador: para quem aprova usuários e cuida do painel.
Parte 1 — Usuário
O que o bot faz
- Consulta os seus pontos do dia na PontoMais.
- Calcula a hora prevista de voltar do almoço e de sair.
- Envia um lembrete pelo Telegram alguns minutos antes de cada horário (5 minutos, por padrão).
- Responde na hora quando você pergunta (
/entrada2,/saida2).
O que o bot não faz
- Não registra ponto. Você continua batendo o ponto na PontoMais normalmente.
- Não substitui a conferência do seu espelho de ponto.
- Não controla hora extra (dias com mais de quatro pontos).
- Não funciona em grupos: só em conversa privada com o bot.
O bot é uma ajuda para lembrar. A fonte oficial continua sendo a PontoMais.
Primeiro acesso
- Abra o bot no Telegram. Peça ao administrador o nome ou o link do bot e toque em Iniciar.
- Peça acesso: envie
/cadastrar. O administrador recebe um aviso. - Credencial da PontoMais: o administrador vai configurar o seu e-mail e senha de login da PontoMais no painel.
- Combine com ele uma forma segura de passar a senha.
- Nunca envie sua senha para o bot no chat. O bot nunca pede senha.
- Aguarde a aprovação. Você recebe a mensagem "Seu cadastro foi aprovado".
- Ligue os lembretes: envie
/ativarponto. - Confira: envie
/status. Deve aparecer Cadastro: ativo e Lembretes: ligados.
Pronto. A partir do próximo dia útil você passa a receber os lembretes.
Os lembretes
Como os horários são calculados
A jornada padrão tem quatro pontos:
| Ponto | Significado |
|---|---|
| 1º | Entrada |
| 2º | Saída para o almoço |
| 3º | Volta do almoço |
| 4º | Saída do dia |
- Volta do almoço = hora em que você saiu para o almoço + tempo de almoço (60 min, por padrão).
- Saída = hora em que você voltou do almoço + o que falta da jornada (8h00, por padrão).
Exemplo: entrada às 08:00, saída para o almoço às 12:00 e volta às 13:00.
- Lembrete de volta do almoço: 12:55 (volta prevista às 13:00).
- Você trabalhou 4 horas antes do almoço; faltam 4 horas.
- Lembrete de saída: 16:55 (saída prevista às 17:00).
Tempo de almoço, jornada e antecedência podem ser diferentes para você. Quem ajusta é o administrador.
Como as mensagens chegam
⏰ Lembrete: seu retorno do almoço está previsto para 13:00.
⏰ Lembrete: sua saída está prevista para 17:00 (jornada de 8h00).
Se o lembrete chegar depois do horário previsto, a frase muda para "estava previsto para 13:00". Assim você sabe a hora certa mesmo com atraso.
Quando os lembretes não chegam (e está tudo certo)
- Fim de semana e feriado: não há consultas nem lembretes.
- Você já bateu o ponto seguinte: se voltou do almoço antes do lembrete, ele é cancelado. O mesmo vale para a saída.
- Lembrete muito atrasado: se o bot só percebe o seu ponto com mais de 10 minutos de atraso em relação ao horário do aviso, o lembrete não é enviado, porque já não ajudaria. Isso pode acontecer se você sair para o almoço muito cedo, antes do horário em que o bot começa a consultar.
- Hora extra: com mais de quatro pontos no dia, o bot para de acompanhar.
Horário em que o bot acompanha seus pontos
O bot consulta a PontoMais apenas numa janela do dia: por padrão, das 11:30 às 19:00.
- Antes das 11:30 o bot ainda não olha seus pontos. Isso é normal: o primeiro lembrete do dia (volta do almoço) quase sempre é depois disso.
- Se o seu horário for bem diferente (por exemplo, almoço às 10:30), peça ao administrador uma janela personalizada.
Dia sem pontos
Se às 11:30 e às 11:45 o bot não encontrar nenhum ponto seu, ele entende que você pode não estar trabalhando hoje (férias, folga, atestado). Ele passa a conferir de hora em hora até as 15:00 e, se continuar sem pontos, encerra as consultas do dia.
Você não recebe mensagem quando isso acontece (para não receber aviso todo dia nas férias). Se começou a trabalhar mais tarde, faça uma destas coisas e as consultas voltam:
- envie
/ativarponto; ou - envie
/entrada2ou/saida2depois de bater o ponto.
Comandos
| Comando | Para que serve |
|---|---|
/cadastrar |
Pedir acesso ao bot (só na primeira vez) |
/status |
Ver a situação do seu cadastro, da credencial, dos lembretes e do dia |
/entrada2 |
Perguntar agora a hora prevista de voltar do almoço (precisa de pelo menos 2 pontos no dia) |
/saida2 |
Perguntar agora a hora prevista de saída (precisa de pelo menos 3 pontos no dia) |
/ativarponto |
Ligar os lembretes automáticos (ou religar depois de uma pausa) |
/desativarponto |
Pausar os lembretes. Os comandos /entrada2 e /saida2 continuam funcionando |
/ajuda |
Ver a lista de comandos |
Entendendo o /status
Cadastro: ativo
Credencial PontoMais: validada
Lembretes: ligados
Janela de consulta: 11:30 às 19:00 (global)
Hoje: acompanhando (2 ponto(s) até a última consulta)
| Linha | O que significa |
|---|---|
| Cadastro | aguardando aprovação, ativo ou desativado |
| Credencial PontoMais | se o administrador já configurou e validou seu login. Se houver falhas recentes, aparece quantas |
| Lembretes | ligados ou pausados, com o motivo da pausa |
| Janela de consulta | horário em que o bot acompanha seus pontos; personalizada se for só sua |
| Hoje | o que o bot sabe do seu dia: aguardando, acompanhando, sem pontos, jornada encerrada ou dia não útil |
Situações comuns
"Pausei os lembretes por falha na PontoMais"
O bot tentou consultar seus pontos 3 vezes seguidas (cerca de 30 minutos) e não conseguiu, então pausou seus lembretes e avisou você e o administrador. O motivo mais comum é senha da PontoMais alterada.
- Se você trocou a senha da PontoMais, informe a nova ao administrador (de forma segura, fora do bot).
- Depois que ele atualizar, envie
/ativarponto.
"A PontoMais está fora do ar"
Quando a PontoMais cai para todo mundo, ninguém é pausado. O administrador é avisado, e os lembretes voltam ao normal quando ela responder de novo. Enquanto isso, pontos novos podem não ser percebidos a tempo.
Esqueci de bater a entrada
O bot calcula pela ordem dos pontos. Se a entrada estiver faltando, ele vai confundir os horários (vai achar que a saída para o almoço é a entrada). Faça o ajuste do ponto na PontoMais. Enquanto isso, desconsidere os lembretes do dia.
Vou sair antes / fazer hora extra
- Saída antecipada: se você bater o ponto de saída antes do lembrete, ele é cancelado. Se bater pouco antes do aviso, o lembrete ainda pode chegar.
- Hora extra: a partir do quinto ponto o bot para de acompanhar o dia.
Férias ou afastamento longo
Envie /desativarponto antes de sair e /ativarponto na volta. Mesmo sem isso o bot para de consultar sozinho nos dias sem pontos, mas pausar evita consultas desnecessárias.
Mudei de horário
Peça ao administrador para ajustar o tempo de almoço, a jornada, a antecedência dos avisos ou a janela de consulta.
Privacidade e segurança
- Sua senha da PontoMais fica cifrada no servidor. Ninguém, nem o administrador, consegue vê-la depois de salva.
- O bot só lê seus pontos; ele não altera nada na PontoMais.
- O bot só responde em conversa privada.
- Nunca envie senhas no chat do bot. Ele nunca vai pedir.
Perguntas frequentes
O lembrete chegou depois da hora prevista. Por quê? O bot confere seus pontos de tempos em tempos (a cada 15 minutos na maior parte do dia) e envia os lembretes a cada 2 minutos. Pequenos atrasos são normais. Atrasos maiores acontecem quando a PontoMais demora a mostrar o ponto. Por isso a mensagem sempre traz o horário previsto.
Não recebi nenhum lembrete hoje.
Envie /status e confira, nesta ordem:
- Cadastro: ativo e Lembretes: ligados.
- Hoje é dia útil.
- A linha Hoje não mostra "sem pontos".
- Seus pontos aparecem na PontoMais na ordem certa.
Se tudo estiver certo, envie /entrada2 para testar. Se der erro, procure o administrador.
Posso usar o bot em um grupo? Não. Ele só responde em conversa privada.
Parte 2 — Administrador
Papéis
O painel tem três tipos de conta. Usuários comuns não acessam o painel; eles usam só o Telegram.
| Ação | Leitura | Admin | Owner |
|---|---|---|---|
| Ver início, usuários, lembretes, auditoria, feriados e configurações | ✓ | ✓ | ✓ |
| Ativar/desativar usuários, ligar/pausar lembretes | ✓ | ✓ | |
| Alterar jornada, janela personalizada e credencial; testar a PontoMais | ✓ | ✓ | |
| Cancelar e reenviar lembretes | ✓ | ✓ | |
| Cadastrar feriados e alterar a janela global | ✓ | ✓ | |
| Criar contas, mudar papéis, redefinir senhas | ✓ |
Conta de leitura ligada a um usuário
Uma conta de leitura pode ser ligada a um usuário do Telegram (feito pelo owner em Contas). Ela serve para a pessoa acompanhar e ajustar só o que é dela, sem ver nada dos outros.
| Tela | O que a conta ligada vê e faz |
|---|---|
| Início | Os avisos do sistema (PontoMais fora do ar, feriados indisponíveis) e os próprios lembretes de hoje, só para consulta (sem link). Não há contadores gerais. |
| Usuários | Abre direto na própria ficha. Pode salvar e testar a credencial PontoMais, alterar a jornada e a janela de consulta, e ligar ou pausar os próprios lembretes. Não ativa nem desativa o cadastro, não define admin do bot e não retoma consultas. |
| Lembretes | Só os próprios, somente leitura (não cancela nem reenvia). |
| Feriados | Somente visualização. |
| Auditoria, Configurações e Contas | Não aparecem no menu e a API recusa o acesso. |
Uma conta de leitura sem usuário ligado continua como antes: vê todas as telas, menos Contas, e não altera nada. Um usuário do Telegram só pode estar ligado a uma conta do painel.
Existe ainda o admin do bot: um usuário do Telegram que recebe os avisos operacionais e pode usar os comandos administrativos no Telegram. Ser admin do bot é independente de ter conta no painel.
Acessar o painel
- Abra o endereço do painel (ex.:
https://botpontos.lan) num computador da rede. - Entre com seu usuário e senha.
Regras de acesso:
- A sessão dura no máximo 8 horas e expira após 30 minutos sem uso.
- 5 senhas erradas seguidas bloqueiam a conta por 15 minutos.
- Use Sair ao terminar, principalmente em computadores compartilhados.
- Esqueceu a senha? Peça a um owner para redefinir (em Contas).
Início (dashboard)
Mostra o resumo do sistema:
- usuários aguardando aprovação e ativos;
- quantos estão com lembretes ligados;
- quantos foram pausados por falha na PontoMais;
- falhas de envio e lembretes expirados nos últimos 7 dias;
- quantos usuários têm janela personalizada;
- lembretes de hoje por situação.
Faixas de alerta aparecem no topo quando:
- a PontoMais está fora do ar: ninguém é pausado; aguarde;
- os feriados do ano não foram obtidos: segunda a sexta estão valendo como dias úteis. Cadastre os feriados manualmente se precisar.
Os números são clicáveis e levam à lista filtrada.
Aprovar um novo usuário
Quando alguém envia /cadastrar, os admins do bot recebem um aviso no Telegram.
- Em Usuários, filtre por Aguardando aprovação e abra o cadastro.
- Em Credencial PontoMais, informe o e-mail e a senha de login da pessoa e clique em Validar e salvar.
- A credencial é testada na PontoMais na hora. Se for recusada, nada é gravado.
- Depois de salva, a senha nunca mais aparece.
- Ajuste a jornada, se for diferente do padrão (ver adiante).
- Clique em Ativar. A pessoa recebe a mensagem de aprovação.
- Peça para ela enviar
/ativarponto.
Sem credencial validada não é possível ativar, nem pelo painel nem pelo Telegram.
Tela do usuário
Cadastro e lembretes
| Botão | O que faz |
|---|---|
| Ativar | Aprova o cadastro (exige credencial validada) |
| Desativar | Bloqueia o uso do bot e cancela os lembretes agendados. Não apaga o histórico |
| Ligar lembretes | Liga os lembretes, zera o contador de falhas e retoma o dia, se ele estava "sem pontos" |
| Pausar lembretes | Desliga os lembretes e cancela os agendados. O /status do usuário mostra "pausado pelo painel" |
| Tornar admin do bot / Remover admin do bot | Define quem recebe os avisos operacionais no Telegram |
| Retomar consultas de hoje | Aparece quando o dia está "sem pontos". Volta a consultar até o fim da janela |
A linha Hoje mostra a situação do dia, quantos pontos foram vistos na última consulta e quando será a próxima.
Credencial PontoMais
Mostra o e-mail, se a credencial está validada, as falhas seguidas e o último erro. Para trocar a senha (por exemplo, depois que o usuário mudou a senha na PontoMais), preencha de novo e clique em Validar e salvar.
Jornada e janela de consulta
| Campo | Padrão | Regras |
|---|---|---|
| Almoço | 60 min | entre 15 e 180 |
| Jornada | 480 min (8h00) | entre 60 e 720 |
| Antecedência do retorno | 5 min | entre 0 e 60 |
| Antecedência da saída | 5 min | entre 0 e 60 |
| Fuso horário | America/Sao_Paulo |
nome no formato IANA |
Regra importante: almoço − antecedência do retorno precisa ser pelo menos 15 minutos. Assim o bot tem tempo de perceber a saída para o almoço antes da hora do aviso. Exemplo: almoço de 20 min com antecedência de 5 min passa; almoço de 15 min com antecedência de 5 min é recusado.
Janela personalizada: desmarque Usar padrão global para definir uma janela só para este usuário. Os quatro horários aparecem preenchidos com os valores globais, como ponto de partida:
| Horário | Significado |
|---|---|
| Início da janela | primeira consulta do dia |
| Confirmação sem pontos | segunda verificação sem pontos; depois dela, o bot passa a conferir de hora em hora |
| Fim das reverificações | depois desse horário, um dia sem pontos é encerrado |
| Fim da janela | última consulta do dia |
Os horários precisam ser múltiplos de 15 minutos (:00, :15, :30, :45), estar nessa ordem e somar pelo menos 4 horas de janela. Para voltar à janela global, marque Usar padrão global e salve.
Mudanças valem a partir da próxima consulta. Lembretes que já foram agendados hoje não mudam.
Pontos de hoje
- Consultar PontoMais agora: mostra os pontos do dia e os horários previstos. Não é automático, para não gastar consultas à toa.
- Testar credencial: igual, mas também marca a credencial como validada se der certo.
Lembretes
Lista os lembretes com filtros por dia, situação, tipo e usuário.
| Situação | Significado |
|---|---|
| agendado | aguardando a hora do aviso |
| enviando | envio em andamento |
| enviado | entregue ao Telegram |
| falhou | o Telegram recusou ou não respondeu |
| cancelado | não será enviado (ponto seguinte já batido, pausa ou cancelamento manual) |
| expirado | o atraso passou de 10 min e o lembrete não foi enviado |
Ações:
- Cancelar: só para lembretes agendados.
- Reenviar: só para lembretes que falharam e são do dia de hoje.
- O usuário precisa estar ativo e com os lembretes ligados.
- Se o ponto seguinte já foi batido, o reenvio é bloqueado.
- Atenção: se a falha foi um travamento no meio do envio, a pessoa pode já ter recebido a mensagem original. O painel pergunta antes de reenviar.
Lembretes expirados não podem ser reenviados.
Auditoria
Registra quem fez o quê e quando: cadastros, ativações, mudanças de jornada e de credencial, envios, falhas, pausas, logins, alterações de configuração etc.
Filtre por período, origem (Telegram, painel, worker, terminal), tipo de evento e resultado. A partir da tela de um usuário, o link Auditoria deste usuário já abre filtrado. Use Mais antigos → para paginar.
Senhas e tokens nunca aparecem na auditoria.
Feriados
O bot não consulta nem envia lembretes em fins de semana e feriados.
- Sincronizar com a feriadosapi.com: baixa os feriados do ano para a cidade configurada. O sistema também faz isso sozinho no primeiro uso de cada ano.
- Cadastrar feriado manual: para pontos facultativos, recessos ou feriados que a API não trouxe.
- Remover: só feriados manuais.
Se a API de feriados estiver fora do ar e o ano ainda não tiver sido sincronizado, segunda a sexta contam como dias úteis. Os admins do bot recebem um aviso por dia enquanto isso durar.
Configurações
Janela de consulta global
Vale para todos os usuários sem janela personalizada. O padrão é 11:30 às 19:00, com confirmação às 11:45 e reverificações até as 15:00.
- Ajuste os horários.
- Clique em Pré-visualizar efeito para ver:
- quantas consultas por usuário a janela gera (máximo, dia típico e dia de folga);
- quantos usuários teriam tido lembretes atrasados nos últimos 30 dias;
- quantos usuários têm janela personalizada e não serão afetados.
- Clique em Salvar.
Parâmetros do servidor
Só leitura: intervalo das consultas, do envio, tolerância de atraso e limite de falhas. Alterá-los exige mudar a configuração do servidor.
Contas do painel (owner)
- Nova conta: usuário (3 a 50 caracteres: letras, números, ponto, hífen ou sublinhado), senha (mínimo 12 caracteres) e papel.
- Papel: troque no seletor da linha.
- Usuário do Telegram: ao criar a conta, ou depois no seletor da linha, escolha o usuário ao qual ela fica ligada (ou "Sem usuário ligado" para remover o vínculo). Com papel de leitura, isso restringe a conta aos dados desse usuário (ver Papéis). A troca vale na próxima requisição, sem precisar sair e entrar de novo.
- Redefinir senha: define uma nova senha e encerra as sessões abertas daquela conta.
- Desativar / Reativar: desativar encerra as sessões; ninguém pode desativar a própria conta.
Sempre precisa existir pelo menos um owner ativo. O sistema recusa rebaixar ou desativar o último.
Comandos de admin no Telegram
Disponíveis para quem é admin do bot e está ativo:
| Comando | O que faz |
|---|---|
/usuarios |
Lista os usuários com ID, situação, credencial e lembretes |
/ativarusuario <id> |
Ativa (exige credencial validada, configurada no painel) |
/desativarusuario <id> |
Desativa e cancela os lembretes agendados |
Exemplo: /ativarusuario 12.
Avisos que o admin do bot recebe
| Aviso | Quando | O que fazer |
|---|---|---|
| Novo pedido de cadastro | alguém enviou /cadastrar |
configurar a credencial e ativar |
| Usuário pausado após falhas | 3 falhas seguidas na PontoMais para aquela pessoa | testar a credencial no painel; se a senha mudou, atualizar; pedir /ativarponto |
| PontoMais fora do ar / voltou | todas as consultas de um ciclo falharam / alguma voltou a funcionar | aguardar; ninguém é pausado |
| Feriados não obtidos | API de feriados indisponível (no máximo 1 aviso por dia) | sincronizar depois ou cadastrar manualmente |
| Jornadas fora da regra | ao reiniciar o servidor, se alguma jornada ficou com almoço − antecedência menor que o intervalo das consultas | ajustar a jornada na tela do usuário |
Se não houver nenhum admin do bot ativo, esses avisos ficam só na auditoria. Mantenha pelo menos um admin do bot.
Rotina sugerida
Diariamente (1 minuto, pela tela Início):
- alguém aguardando aprovação?
- alguém pausado por falha na PontoMais?
- falhas de envio hoje?
Mensalmente:
- revisar usuários desativados e contas do painel que não são mais usadas;
- conferir se os feriados do ano estão cadastrados;
- confirmar com o operador que os backups estão sendo copiados para fora do servidor.
Problemas comuns (administrador)
| Situação | Causa provável | O que fazer |
|---|---|---|
| "Configure e valide a credencial da PontoMais antes" ao ativar | credencial ausente ou nunca validada | salvar a credencial na tela do usuário |
| "A PontoMais recusou o e-mail ou a senha" | dados errados ou senha alterada | conferir com o usuário; a credencial anterior foi mantida |
| "Não foi possível validar na PontoMais agora" | PontoMais lenta ou fora do ar | tentar mais tarde |
| Usuário diz que não recebe lembretes | lembretes pausados, dia sem pontos, fora da janela ou feriado | tela do usuário (linha Hoje), Lembretes filtrado pela pessoa e Auditoria |
| Muitos lembretes expirados de um usuário | sai para o almoço antes do início da janela | dar a ele uma janela personalizada que comece mais cedo |
| Lembrete falhou | Telegram recusou (ex.: o usuário bloqueou o bot) ou instabilidade | pedir para o usuário desbloquear/abrir o bot; reenviar se for do dia |
| "Origem da requisição não permitida" ou "Token CSRF inválido" | painel acessado por endereço diferente do configurado, ou cookies antigos | usar sempre o endereço oficial; apagar os cookies do site e entrar de novo |
| Conta de leitura vê "Seu papel não permite esta ação" | tentou abrir tela ou ação fora do que a conta ligada permite | esperado; para ver tudo, usar uma conta sem vínculo ou admin |
| Conta bloqueada | 5 senhas erradas | aguardar 15 minutos ou pedir a um owner para redefinir a senha |