Solicitar e aprovar férias

O pedido de férias pode nascer fora da TAI — no portal do colaborador, no sistema de escalas, na planilha do gestor. Esta jornada leva o pedido para a TAI, que confere as regras da CLT e desconta o saldo do período aquisitivo na aprovação, e avisa o gestor, o colaborador e os seus sistemas.


Quando usar	Férias são pedidas ou planejadas em outro sistema e a TAI deve ser a fonte do saldo
Porta	REST · Webhook
Você vai precisar	Módulo `PESSOAS`; permissão `COLABORADOR` com edição; um usuário de integração

Como funciona

portal ──► GET /periodo-aquisitivo/colaborador/{id}   (escolhe o período com saldo)
portal ──► POST /ferias                               (status SOLICITADO) ──► FERIAS_SOLICITADAS
gestor ──► PUT /ferias/{id}/aprovar?aprovadorId=…     (status APROVADO)   ──► FERIAS_APROVADAS
            │                                                                   │
            ▼                                                                   ▼
   dias saem do saldo do período;                                  webhook ──► seu sistema
   status vira EM_ANDAMENTO e CONCLUIDO nas datas

Passo a passo

Escolha o período aquisitivo. Liste os períodos do colaborador e use o mais antigo que esteja completo, com diasDisponiveis maior que zero e periodoConcessivoVencido falso.

GET /periodo-aquisitivo/colaborador/1043

[
  {
    "id": 912,
    "dataInicio": "2025-03-04 00:00:00",
    "dataFim": "2026-03-03 00:00:00",
    "dataLimiteConcessao": "2027-03-03 00:00:00",
    "diasDireito": 30,
    "diasGozados": 0,
    "diasDisponiveis": 30,
    "completo": true,
    "concedido": false,
    "periodoConcessivoVencido": false
  }
]

Lista vazia quer dizer que o colaborador ainda não tem períodos — veja Levar férias para a folha externa.

Programe as férias. Informe o início e a quantidade de dias; a TAI calcula o fim e o retorno.

curl -X POST https://api.taitecnologia.com/ferias \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "colaborador": { "id": 1043 },
    "periodoAquisitivo": { "id": 912 },
    "dataInicio": "2026-12-02",
    "quantidadeDias": 20,
    "diasAbonoPecuniario": 10,
    "observacoes": "Pedido pelo portal, protocolo 5521"
  }'

A resposta traz as férias com status: "SOLICITADO", dataFim e dataRetornoPrevisto. Guarde o id. Para fracionar, envie fracionada: true, numeroFracao e totalFracoes.

Aprove. aprovadorId é o id do colaborador que aprova (o gestor ou alguém do RH).
```
PUT /ferias/5521/aprovar?aprovadorId=88
```
As férias passam a APROVADO e os dias saem do saldo do período. Para recusar ou desfazer, use PUT /ferias/{id}/cancelar?motivoCancelamento=…: em férias já aprovadas, os dias voltam para o saldo.

As regras que a TAI confere

O POST /ferias responde 400 com Validação falhou: seguido de cada regra violada:

o período aquisitivo precisa estar completo e ter saldo para os dias pedidos;
o prazo para tirar as férias daquele período não pode ter vencido;
o início precisa estar a 30 dias ou mais de hoje;
o abono pecuniário vai até 1/3 dos dias de direito;
não pode haver outras férias do colaborador no mesmo intervalo;
o período não pode estar totalmente concedido;
o início respeita a regra do descanso semanal remunerado da CLT.

A aprovação exige férias em SOLICITADO e 2 dias ou mais até o início.

Automatize

Avisar o colaborador e o gestor. O modelo de fluxo automatizado Férias aprovadas, em Processos › Fluxos › Novo processo › Fluxo automatizado, avisa o colaborador no sino quando as férias são aprovadas e, no primeiro dia das férias, o gestor. Nasce como rascunho: revise e clique em Publicar. Aprovações em lote esperam na fila e rodam uma de cada vez.

Avisar o seu sistema. Crie um webhook em Processos › Central de Automações › Webhooks e marque os eventos do ciclo que o seu sistema acompanha:

Evento	Quando
Alguém pede férias (`FERIAS_SOLICITADAS`)	O `POST /ferias` grava as férias em `SOLICITADO` — o sistema de escalas fica sabendo antes da aprovação
Férias são aprovadas (`FERIAS_APROVADAS`)	A aprovação desconta o saldo
Férias são canceladas (`FERIAS_CANCELADAS`)	O `cancelar` devolve os dias ao saldo; traz `motivo`
Um colaborador volta das férias (`FERIAS_RETORNO_REGISTRADO`)	O retorno é registrado — à mão (`origem` `MANUAL`) ou pelo Guardião de férias (`AUTOMATICO`)

A cada aprovação chega, assinado:

{
  "id": "evt_54102",
  "tipo": "FERIAS_APROVADAS",
  "descricao": "Férias são aprovadas",
  "versao": 1,
  "ocorridoEm": "2026-10-20T13:15:40.602Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "solicitacaoId": 5521,
    "colaboradorId": 1043,
    "colaboradorNome": "Ana Ribeiro",
    "gestorId": 88,
    "dataInicio": "2026-12-02",
    "dias": 20
  }
}

solicitacaoId é o id das férias e dataInicio sai como yyyy-MM-dd. Com ele, o seu sistema lê o registro completo em GET /ferias/{id} — ou marque Enviar também o registro completo no webhook.

Para avisar um canal no formato dele, use um fluxo automatizado com o evento e o bloco Chamar outro sistema — veja Da TAI para o seu sistema.

Repassar o trabalho de quem sai. Um fluxo pode ouvir Férias são aprovadas para que alguém cadastre a ausência com substituto com as mesmas datas.

Pelo seu agente de IA

“Programe 20 dias de férias para a Ana Ribeiro a partir de 2 de dezembro” é uma escrita que o agente conectado por MCP faz com escopo de escrita e a sua aprovação no cliente de IA. Aprovar e cancelar não: são ações de confirmação forte, que o MCP recusa — ficam com a plataforma, a Tali ou a API REST. Veja Escrita e segurança.

Cuidados

Use /ferias, não /solicitacao-ferias. É em /ferias que as regras são conferidas, o saldo é descontado e os eventos são publicados.
Idempotência. Repetir o POST /ferias com as mesmas datas responde 400 (já existem férias no período). Guarde o id retornado em vez de reenviar.
Datas civis em yyyy-MM-dd (datas e formatos).
Os eventos saem uma vez por fato. As novas tentativas cobrem quedas de horas; para o que não pode faltar, concilie lendo GET /ferias/status/APROVADO ou GET /ferias/programadas — veja Levar férias para a folha externa.

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