Levar férias para a folha externa

Quando a folha roda em outro sistema, ele precisa saber, a cada competência, quem sai de férias, por quantos dias, com quanto de abono, e se as férias são em dobro. A TAI é a fonte da programação e do saldo; esta jornada lê o que a folha precisa e mantém os prazos sob vigilância.


Quando usar	As férias são programadas e aprovadas na TAI e pagas na folha de outro sistema
Porta	REST · Webhook
Você vai precisar	Módulo `PESSOAS`; permissão `COLABORADOR` com leitura (edição para gerar períodos e registrar retorno)

Como funciona

folha externa ──► GET /ferias/status/APROVADO        (o que pagar na competência)
folha externa ──► GET /ferias/status/CANCELADO       (o que estornar)
folha externa ──► GET /periodo-aquisitivo/page       (saldos e prazos)
TAI ──► webhook (FERIAS_APROVADAS, FERIAS_CANCELADAS, FERIAS_PRAZO_CONCESSIVO) ──► folha externa

Passo a passo

Leia as férias aprovadas e filtre, no seu lado, as que começam na competência que vai ser paga.

GET /ferias/status/APROVADO

[
  {
    "id": 5521,
    "colaborador": { "id": 1043, "nome": "Ana Ribeiro" },
    "periodoAquisitivo": { "id": 912 },
    "status": "APROVADO",
    "dataInicio": "2026-12-02 00:00:00",
    "dataFim": "2026-12-21 00:00:00",
    "dataRetornoPrevisto": "2026-12-22 00:00:00",
    "quantidadeDias": 20,
    "diasAbonoPecuniario": 10,
    "pagoEmDobro": false,
    "totalFracoes": 1
  }
]

Leve para a folha quantidadeDias, diasAbonoPecuniario, dataInicio, dataFim e pagoEmDobro. Case o colaborador pela matrícula (codigoFuncionario) lendo GET /colaborador/{id}.

Leia as canceladas para estornar o que já tinha sido lançado.
```
GET /ferias/status/CANCELADO
```
O cancelamento também publica Férias são canceladas (FERIAS_CANCELADAS, com feriasId e motivo) — veja Automatize. A leitura continua sendo a conferência da competência.
Registre o retorno, se a volta foi em outra data. Sem isso, as férias passam a CONCLUIDO sozinhas depois da data de fim, quando o Guardião de férias está ligado.
```
PUT /ferias/5521/registrar-retorno?dataRetorno=2026-12-22
```

Leitura	Traz
`GET /ferias/programadas`	Férias com início futuro, aprovadas ou ainda pendentes de solicitação, em ordem de início
`GET /ferias/em-andamento`	Quem está de férias hoje
`GET /ferias/status/{status}`	Por status: `SOLICITADO`, `APROVADO`, `EM_ANDAMENTO`, `CONCLUIDO`, `CANCELADO`…
`GET /ferias/colaborador/{colaboradorId}`	Todas as férias de uma pessoa
`GET /ferias/page`	Todas, paginado — veja Padrão das rotas

Períodos aquisitivos

Cada período tem dataInicio, dataFim (12 meses), dataLimiteConcessao (o prazo para tirar as férias, 12 meses depois), diasDireito, diasGozados, diasAbonoPecuniario e o saldo em diasDisponiveis.

Pergunta	Chamada
Os períodos de uma pessoa	`GET /periodo-aquisitivo/colaborador/{colaboradorId}`
Todos, para conferir saldos	`GET /periodo-aquisitivo/page?page=0&size=200`
Prazos que vencem nos próximos 60 dias	`GET /periodo-aquisitivo/proximos-vencimento?dias=60`
Prazos já vencidos (férias em dobro)	`GET /periodo-aquisitivo/vencidos`

Quem cria os períodos. Com o Guardião de férias ligado, a TAI gera os períodos a partir da data de admissão — no cadastro e todo dia — só para os que ainda estão no prazo. Com ele desligado, crie o período pela API, informando o dia em que ele começa:

POST /periodo-aquisitivo/gerar?colaboradorId=1043&dataAdmissao=2025-03-04

A TAI calcula o fim (12 meses) e o prazo para tirar as férias (24 meses), com 30 dias de direito.

Automatize

O Guardião de férias (ferias-guardiao, começa desligado) roda todo dia de manhã: gera os períodos que faltam, marca como vencidos os períodos com saldo cujo prazo passou, move o status das férias (APROVADO → EM_ANDAMENTO → CONCLUIDO) e avisa o gestor e os donos da conta 60, 30 e 15 dias antes do prazo. Ligue em Processos › Central de Automações › Rotinas dos módulos.

Cada aviso também publica o evento O prazo para tirar férias está vencendo (FERIAS_PRAZO_CONCESSIVO).

Levar à folha externa o que mudou. Crie um webhook com o endereço da folha e assine:

Evento	Para a folha
Férias são aprovadas (`FERIAS_APROVADAS`)	Lançar as férias na competência do `dataInicio`
Férias são canceladas (`FERIAS_CANCELADAS`)	Estornar o que já tinha sido lançado
Um colaborador volta das férias (`FERIAS_RETORNO_REGISTRADO`)	Conferir a data de retorno (`dataRetorno`)
O prazo para tirar férias está vencendo (`FERIAS_PRAZO_CONCESSIVO`)	Prever as férias em dobro quando `situacao` é `VENCIDO`

O aviso de prazo chega assim:

{
  "id": "evt_54390",
  "tipo": "FERIAS_PRAZO_CONCESSIVO",
  "descricao": "O prazo para tirar férias está vencendo",
  "versao": 1,
  "ocorridoEm": "2026-10-07T09:00:03.118Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "periodoId": 874,
    "colaboradorId": 1043,
    "colaboradorNome": "Ana Ribeiro",
    "gestorId": 88,
    "situacao": "VENCENDO",
    "diasRestantes": 30,
    "dataLimite": "2026-11-06",
    "saldoDias": 30
  }
}

O evento sai nos avisos de prazo (VENCENDO) e no vencimento (VENCIDO). Para tratar só os vencidos, filtre por situacao no sistema que recebe; ou, para que o RH cobre cada caso com responsável e prazo, use um fluxo de Processos que ouça o evento e aja só nos cards cujo campo de situação seja VENCIDO — as automações de fluxo aceitam condições sobre os campos do card. Veja Da TAI para o seu sistema.

Pelo seu agente de IA

“Quem sai de férias em dezembro?” e “quais períodos vencem nos próximos 60 dias?” são leituras que o agente conectado por MCP responde. Para uma planilha, peça que ele use exportar_para_excel.

Cuidados

Feche a competência pela leitura, não só pelo evento. Os eventos saem uma vez e as novas tentativas cobrem quedas de horas; a leitura por status é a conferência que não falha.
Idempotência. Use o id das férias como chave na folha: a mesma férias aparece em várias leituras até ser paga.
Gerar período não confere duplicidade. Liste os períodos do colaborador antes de chamar /gerar.
Datas na resposta em yyyy-MM-dd HH:mm:ss, no horário de Brasília (datas e formatos).

Referência gerada do contrato da API em 30 de outubro de 2026. taitecnologia.com · Termos de uso · Privacidade