Registrar faltas e ausências

Duas coisas diferentes moram aqui. As faltas contam para o direito a férias: faltas injustificadas num período aquisitivo reduzem os dias de férias, pela tabela da CLT. As ausências com substituto — férias, licença, viagem — repassam a um colega os cards de processo de quem está fora, e devolvem quando a pessoa volta. As duas podem vir de outro sistema.

Quando usar	As faltas são apuradas em outro sistema de ponto ou na folha; afastamentos são decididos fora da TAI e o trabalho em andamento precisa de dono
Porta	REST · Webhook
Você vai precisar	Módulo PESSOAS; permissão COLABORADOR com edição

Como funciona

faltas:    seu sistema ──► POST /falta ──► PUT /periodo-aquisitivo/{id}/atualizar-faltas
                                              └─► dias de direito recalculados

ausências: seu sistema ──► POST /colaborador-ausencia (substituto, datas)
                              └─► enquanto ativa, cards atribuídos à pessoa vão para o substituto
                              └─► no fim, os cards voltam para ela

Faltas

1. Registre cada falta. O período aquisitivo é achado pela data; informe-o só se quiser forçar outro.

   POST /falta
   Content-Type: application/json
   
   {
     "colaborador": { "id": 1043 },
     "dataFalta": "2026-09-14",
     "tipoFalta": "INJUSTIFICADA"
   }

   tipoFalta aceita JUSTIFICADA (pede motivo) e INJUSTIFICADA. Data futura é recusada com 400.

2. Justifique depois, se for o caso. O atestado chegou depois da falta lançada:

   PUT /falta/7781/justificar?motivo=Atestado%20m%C3%A9dico&aprovadoPor=RH%20-%20Carla

   Para anexar o arquivo do atestado, POST /falta/upload-documento/{id} recebe o arquivo em multipart/form-data.

3. Recalcule os dias de direito do período depois de registrar ou justificar as faltas dele.

   PUT /periodo-aquisitivo/912/atualizar-faltas

   A TAI conta as faltas injustificadas entre o início e o fim do período e grava faltasInjustificadas e diasDireito:

   Faltas injustificadas	Dias de férias
   até 5	30
   6 a 14	24
   15 a 23	18
   24 a 32	12
   mais de 32	0

Para conferir: GET /falta/colaborador/{colaboradorId}/periodo?dataInicio=…&dataFim=… lista as faltas de um intervalo, e GET /falta/periodo-aquisitivo/{periodoId}/injustificadas as injustificadas de um período.

Ausências com substituto

Na plataforma, a tela fica em Departamento Pessoal → Ausências.

1. Cadastre a ausência com o substituto e as datas.

   Começa sozinha na data

   Com "status": "ATIVO", a delegação começa quando chega a dataInicio e termina na dataFimPrevista, sem outra chamada. Uma data sem hora vale à meia-noite: para cobrir o último dia inteiro, envie a hora ("2026-12-21 23:59").

   POST /colaborador-ausencia
   Content-Type: application/json
   
   {
     "colaborador": { "id": 1043 },
     "substituto": { "id": 1102 },
     "dataInicio": "2026-12-02",
     "dataFimPrevista": "2026-12-21 23:59",
     "motivo": "Férias",
     "status": "ATIVO"
   }

   Agendada, iniciada à mão

   Sem status, a ausência nasce AGENDADO e não delega nada até ser iniciada:

   POST /colaborador-ausencia/{id}/iniciar

   Iniciar põe a ausência em ATIVO e, se o início ainda era futuro, antecipa-o para agora.

2. Enquanto ativa, todo card de processo atribuído à pessoa — à mão ou por automação — vai para o substituto, com um comentário no card registrando a substituição. Os cards que ela já tinha antes do início continuam com ela. GET /colaborador-ausencia/ativa/{colaboradorId} diz se a pessoa está ausente agora.

3. Na volta, os cards voltam para a pessoa. Isso acontece sozinho, de madrugada, depois da dataFimPrevista; para encerrar antes, use:

   POST /colaborador-ausencia/{id}/encerrar-antecipadamente

Saber quando começa e termina. Um webhook que assine Uma ausência começa (AUSENCIA_INICIADA) e Uma ausência termina (AUSENCIA_ENCERRADA) avisa o seu sistema — para redirecionar o e-mail, ajustar a escala — com ausenciaId, colaboradorId e substitutoId. Uma ausência começa sai quando a ausência é iniciada por POST /colaborador-ausencia/{id}/iniciar — a criada já com "status": "ATIVO" não o publica; Uma ausência termina, no encerramento antecipado ou no fim automático depois da dataFimPrevista.

Férias aprovadas viram ausência

Para que o trabalho de quem sai de férias não pare, crie a ausência com as datas das férias logo depois de aprová-las — o evento Férias são aprovadas (FERIAS_APROVADAS) é o sinal para o seu sistema fazer isso. Veja Solicitar e aprovar férias.

Pelo seu agente de IA

“Quantas faltas injustificadas a Ana Ribeiro tem no período atual?” e “quem está ausente hoje e quem a substitui?” são leituras que o agente conectado por MCP responde. Registrar falta ou ausência é escrita, com escopo de escrita e a sua aprovação; encerrar uma ausência é ação de confirmação forte, que o MCP recusa.

Cuidados

• Registrar falta não recalcula as férias sozinho. Chame atualizar-faltas no período, ou o saldo continua com os dias antigos.
• Faltas não têm chave externa. Nada impede duas faltas no mesmo dia: confira com GET /falta/colaborador/{colaboradorId}/periodo antes de reenviar.
• Substituto e ausente precisam ser pessoas diferentes, e a dataFimPrevista não pode ser anterior à dataInicio — fora disso, 400.
• A delegação vale para os cards de processo (BPM), na hora em que são atribuídos.
• Datas civis em yyyy-MM-dd (datas e formatos).