Levar as candidaturas para o seu sistema

O time de recrutamento quer saber na hora quando chega candidato; o gestor quer ser avisado quando alguém chega à entrevista dele; a matriz espelha o funil numa planilha ou num ATS corporativo. A TAI avisa cada candidatura nova, mudança de etapa, reprovação e contratação — e o seu sistema busca o resto pela API.

Quando usar	Alerta no Slack/Teams, espelho do funil em outro ATS, planilha ou BI
Porta	Webhook · Automação · REST
Você vai precisar	módulo CONTRATACOES; dono da conta ou administrador para criar o webhook em Processos › Central de Automações e permissão de Processos para o fluxo automatizado; para ler pela API, permissão CANDIDATO (leitura) e JWT

Como funciona

candidatura nova  ──► CANDIDATURA_CRIADA       (candidaturaId, vagaId, vagaTitulo, candidatoNome)
mudança de etapa  ──► CANDIDATURA_MOVIDA_ETAPA (… etapaOrigem, etapaDestino, etapaDestinoId)
reprovação        ──► CANDIDATURA_REPROVADA    (… motivo)
contratação       ──► CANDIDATURA_CONTRATADA   (… colaboradorId, colaboradorNome, gestorId)
        │
        ├──► webhook assinando os eventos ──► seu ATS / sua planilha
        └──► fluxo automatizado "Chamar outro sistema" ──► Slack, só nas etapas que importam
        │
        ▼
seu sistema ──► GET /candidatura/{id}   (e currículo, histórico, avaliações)

Passo a passo

1. Espelhe o funil num webhook. Em Processos › Central de Automações, aba Webhooks, crie um Novo webhook com o endereço do seu ATS ou da sua planilha e marque os eventos do funil — Alguém se candidata a uma vaga, Um candidato muda de etapa, Um candidato é reprovado, Um candidato é contratado —, ou Tudo de Contratações, que inclui também vagas, pré-entrevistas, carta proposta e admissão. Veja Assinar eventos.

   A cada mudança de etapa chega, assinado:

   {
     "id": "evt_56120",
     "tipo": "CANDIDATURA_MOVIDA_ETAPA",
     "descricao": "Um candidato muda de etapa",
     "versao": 1,
     "ocorridoEm": "2026-10-06T19:41:22.015Z",
     "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
     "dados": {
       "candidaturaId": 9412,
       "vagaId": 128,
       "vagaTitulo": "Analista Financeiro",
       "candidatoNome": "Ana Ribeiro",
       "etapaOrigem": "Entrevista RH",
       "etapaDestino": "Entrevista Gestor",
       "etapaDestinoId": 2309
     }
   }

2. Avise o time no Slack. O webhook manda tudo, no envelope da TAI. Para uma mensagem no formato do Slack, crie em Processos › Fluxos › Novo processo › Fluxo automatizado um fluxo que começa por Quando algo acontece com o evento Um candidato muda de etapa e segue para o bloco Chamar outro sistema com a URL de incoming webhook do Slack. O Corpo (JSON):

   {
     "text": "{{gatilho.candidatoNome}} chegou a {{gatilho.etapaDestino}} · {{gatilho.vagaTitulo}}"
   }

   Faça outro fluxo para Alguém se candidata a uma vaga se o time quer saber de cada candidatura nova. Testar percorre o desenho sem enviar nada; Publicar liga o fluxo.

   Para avisar só algumas mudanças — quando o candidato chega a “Entrevista Gestor”, por exemplo —, filtre etapaDestino em Só quando, no bloco do gatilho. Veja Da TAI para o seu sistema.

3. Confira a assinatura no seu ATS com o segredo do webhook — veja Conferir a assinatura — e use o X-Tai-Entrega para não processar o mesmo envio duas vezes.

4. Busque o resto pela API. O aviso traz ids e nomes. Com o candidaturaId, o seu sistema lê:

   curl https://api.taitecnologia.com/candidatura/9412 \
     -H "Authorization: Bearer $TAI_TOKEN"

   A candidatura traz candidato (id, nomeCompleto, email, telefone, linkedin, origem), vaga, statusAtual, etapaAtual, cartaApresentacao e dataCandidatura. Mais:

   Rota	O que traz
   GET /candidato/{id}/curriculo	O arquivo do currículo
   GET /candidatura/{id}/timeline	Histórico completo: etapas, avaliações, comentários
   GET /candidatura-etapa/candidatura/{candidaturaId}/historico	Passagem por cada etapa, com datas
   GET /avaliacao/candidatura/{candidaturaId}	Avaliações dos entrevistadores

Reconciliação e funil

As novas tentativas cobrem quedas de horas. Para um espelho que não pode perder nada, rode também, de tempos em tempos:

GET /candidatura/page?page=0&size=100&sort=id,desc

e pare quando encontrar um id que já conhece. Para BI, GET /candidatura/funil devolve quantos candidatos há em cada etapa, de todas as vagas ou de uma (?vagaId=), numa chamada só; GET /vaga/{id}/metricas traz os números de uma vaga.

Pelo seu agente de IA

“Quantos candidatos chegaram esta semana para as vagas de vendas, e em que etapa estão?”

Leitura livre: o agente consulta candidaturas e o funil com as permissões de quem o conectou.

Cuidados

• Cada mudança de etapa é um evento novo, inclusive quando o candidato volta para uma etapa em que já esteve. Use candidaturaId + etapaDestino como chave no seu lado e trate a repetição. A reprovação também é um evento a cada vez que acontece; a contratação sai uma vez por candidatura.
• Candidaturas criadas por POST /candidatura (a rota genérica) não publicam Alguém se candidata a uma vaga; o evento sai das candidaturas pelo portal, pelo site e pelo hunting.
• Dados pessoais. Leve para outro sistema só o que ele precisa; os dados do evento, de propósito, não trazem e-mail nem telefone. Enviar também o registro completo manda a candidatura inteira — marque só se o destino precisa dela.
• Responda rápido. Responda 2xx assim que receber e processe numa fila sua — veja Entregas e novas tentativas.