Abrir vagas e mover candidatos pela API

A vaga nasce no seu quadro de posições ou no ERP, quando uma requisição de pessoal é aprovada. Pela API, o seu sistema abre a vaga na TAI já com a posição (empresa, departamento, cargo), ajusta as etapas do processo seletivo e acompanha — ou conduz — o candidato de etapa em etapa.


Quando usar	Requisição de vaga aprovada em outro sistema; ATS externo que conduz o funil e espelha na TAI
Porta	REST · Webhook · Agente (MCP) para criar vaga e mover candidato
Você vai precisar	módulo `CONTRATACOES`; permissão `VAGA` (edição) para vagas e etapas; `CANDIDATO` (edição) para mover e reprovar; JWT de um usuário de integração

Como funciona

seu sistema ──► POST /vaga  {modeloNome?}       vaga em RASCUNHO + etapas do modelo de processo
            ──► GET/PATCH /etapa-processo         ajusta as etapas (prazo, tipo, nome)
            ──► PUT /ats-pergunta/vaga/{id}       perguntas do formulário de candidatura
            ──► POST /vaga/{id}/publicar          PUBLICADA · ganha urlPublica · VAGA_PUBLICADA
                          │
             candidaturas chegam (portal, site, hunting) na 1ª etapa · CANDIDATURA_CRIADA
                          │
            ──► POST /candidatura/{id}/mover-etapa?etapaId=…   CANDIDATURA_MOVIDA_ETAPA
            ──► POST /candidatura/{id}/reprovar  {motivo…}     CANDIDATURA_REPROVADA
            ──► POST /candidatura/{id}/contratar {…}           CANDIDATURA_CONTRATADA + admissão
            ──► POST /vaga/{id}/encerrar {situacao, motivo…}   VAGA_FECHADA

Passo a passo

Crie a vaga.
Terminal window
```
curl -X POST https://api.taitecnologia.com/vaga \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Analista Financeiro",
    "descricao": "Contas a pagar e a receber, conciliação bancária e fechamento mensal.",
    "requisitosObrigatorios": "Superior em Administração, Contábeis ou Economia.",
    "tipoContratacao": "CLT",
    "modalidadeTrabalho": "HIBRIDO",
    "localizacao": "Belo Horizonte - MG",
    "faixaSalarial": "R$ 5.000 a R$ 6.500",
    "empresa": { "id": 3 },
    "departamento": { "id": 40 },
    "cargo": { "id": 77 },
    "codigoPosicao": "POS-118",
    "modeloNome": "Financeiro",
    "recrutadorResponsavel": { "id": 1043 },
    "gestorResponsavel": { "id": 1021 }
  }'
```
A vaga nasce em RASCUNHO. Guarde o id e, se quiser, grave o codigoPosicao do seu quadro — ele serve de chave de correspondência. Os ids de empresa, departamento, time (subDepartamento), cargo e centro de custo precisam existir na conta, e o time precisa ser do departamento informado.

modeloId (de GET /ats-modelo-processo) ou modeloNome escolhe o modelo de processo de que a vaga copia as etapas; sem ele, vale o modelo padrão da empresa. A vaga também nasce com as perguntas padrão da empresa. Vaga afirmativa: vagaAfirmativa (NAO, EXCLUSIVA_PCD, PREFERENCIAL_PCD, OUTRA + vagaAfirmativaTexto) e oferecerAutodeclaracaoPcd.

A posição (empresa, departamento, time, cargo, centro de custo, código) não aparece no anúncio: ela preenche o vínculo do colaborador quando a admissão do aprovado for finalizada.
Confira as etapas. A vaga nasce com as etapas do modelo (o modelo padrão de cada empresa começa com Triagem, Entrevista RH, Entrevista Técnica, Entrevista Gestor e Proposta). Cada etapa traz prazoDiasUteis (vencido, a pessoa leva o selo de parada) e tipo (NORMAL ou APROVACAO_GESTOR).
Terminal window
```
curl https://api.taitecnologia.com/etapa-processo/vaga/512 \
  -H "Authorization: Bearer $TAI_TOKEN"
```
Para acrescentar uma etapa:
```
POST /etapa-processo
Content-Type: application/json

{ "vagaId": 512, "nome": "Teste prático", "prazoDiasUteis": 3 }
```
Sem ordem, a etapa entra no fim. Para reordenar, POST /etapa-processo/vaga/{vagaId}/ordem com {"etapaIds": [...]} (todas, na ordem nova). Para mudar uma etapa, PATCH /etapa-processo com o id e só o que muda (prazoDiasUteis: 0 e nomePublico: "" limpam). Candidaturas novas entram na etapa de ordem 1.

Remover etapa com gente exige destino: DELETE /etapa-processo/{id} só remove etapa vazia; com pessoas, use POST /etapa-processo/{id}/remover com {"destinoEtapaId": …}. Para trocar o processo inteiro pelo de um modelo, GET /vaga/{id}/previa-modelo?modeloId=… mostra o que fica, entra e sai (e quantas pessoas estão em cada etapa que sai), e POST /vaga/{id}/aplicar-modelo?modeloId=… aplica, com {"destinos": [{"etapaId": …, "destino": "nome da etapa do modelo"}]} para cada etapa que sai com gente. Ninguém é avisado.

Perguntas da candidatura: GET /ats-pergunta/vaga/{vagaId} e PUT /ats-pergunta/vaga/{vagaId} com {"perguntas": [...]} (a lista inteira, na ordem). Tipos SIM_NAO, ESCOLHA (opcoes), TEXTO, NUMERO, PRETENSAO_SALARIAL, DISPONIBILIDADE; eliminatoria + respostaEsperada só em SIM_NAO e ESCOLHA. Eliminatória não reprova: marca naoAtende na lista de candidatos.
Publique.
```
POST /vaga/512/publicar
```
Publicar exige titulo, descricao, tipoContratacao e modalidadeTrabalho (sem eles, 400 com o campo que falta). A vaga passa a PUBLICADA, ganha a urlPublica e entra no portal de carreiras e nas rotas públicas, e a TAI publica Uma vaga é publicada (VAGA_PUBLICADA). POST /vaga/{id}/pausar (corpo opcional {"observacao": "…"}) tira do ar e publica Uma vaga é pausada (VAGA_PAUSADA); POST /vaga/{id}/retomar devolve ao portal com o mesmo link (VAGA_RETOMADA).
Mova candidatos. Liste as candidaturas da vaga (GET /candidatura/vaga/{vagaId}) e mova:
Terminal window
```
curl -X POST "https://api.taitecnologia.com/candidatura/9412/mover-etapa?etapaId=2309&enviarNotificacao=true" \
  -H "Authorization: Bearer $TAI_TOKEN"
```
etapaId é obrigatório e tem de ser da mesma vaga; enviarNotificacao=true põe o e-mail da mudança de etapa na fila de envio (o padrão é não mandar; atrasoMinutos opcional) e a resposta traz emailNaFila com o horário. Cada movimento publica Um candidato muda de etapa (CANDIDATURA_MOVIDA_ETAPA). Só candidatura ativa (sem desfecho) se move.

Para reprovar, mande o corpo:
```
POST /candidatura/9412/reprovar
{ "motivo": "Perfil técnico", "observacao": "sem SQL avançado", "enviarEmail": true }
```
motivo é o nome de um motivo da empresa (lista em GET /ats-motivo/tipo/REPROVACAO) ou use motivoId; nome desconhecido vira “Outro” com o texto como observação. A candidatura ganha desfecho: "REPROVADA" e sai das etapas; o feedback entra na fila com o atraso de reprovação da empresa. Publica Um candidato é reprovado (CANDIDATURA_REPROVADA). A chamada antiga ?motivo=…&enviarNotificacao=… continua aceita. Desistência do candidato é outra ação: POST /candidatura/{id}/registrar-desistencia (CANDIDATURA_DESISTIU). Para desfazer qualquer desfecho: POST /candidatura/{id}/reverter-desfecho (CANDIDATURA_REABERTA), que também tira da fila os e-mails que ainda não saíram.
Encerre a vaga.
```
POST /vaga/512/encerrar
{ "situacao": "FECHADA_PREENCHIDA", "motivo": "Posições preenchidas", "avisarCandidatos": true }
```
situacao aceita FECHADA_PREENCHIDA ou FECHADA_CANCELADA; o motivo vem de GET /ats-motivo/tipo/ENCERRAMENTO_VAGA. Quem ainda estava no processo ganha desfecho: "ENCERRADA_COM_VAGA" e, com avisarCandidatos (padrão true), recebe o aviso pela fila de envio. A TAI publica Uma vaga é fechada (VAGA_FECHADA). A chamada antiga POST /vaga/{id}/fechar?statusFechamento=… continua aceita: encerra sem motivo e sem avisar.

Automatize

O que a TAI já faz sozinha neste cenário:

Pré-entrevista automática (ats-pre-entrevista-automatica, começa ligada). Numa etapa marcada com Pré-entrevista (na vaga, aba Configurar › Processo, ou no modelo de processo), a pré-entrevista por WhatsApp começa quando o candidato entra nela — inclusive quando quem move é a sua integração, por mover-etapa. Se não der (candidato sem telefone, WhatsApp não configurado na empresa), o motivo fica nos comentários da candidatura. Editar a etapa pela API (nome, ordem) não desfaz essa marcação.
Vaga sem candidaturas (ats-funil-parado, começa desligada). Toda segunda de manhã, avisa por e-mail o recrutador da vaga publicada que passou uma semana sem candidatura nova. Ligue em Processos › Central de Automações › Rotinas dos módulos.

Devolver o andamento ao quadro de posições. Quando a vaga nasce no seu sistema, ele fica sabendo do que acontece com ela por um webhook que assine Uma vaga é publicada (VAGA_PUBLICADA), Uma vaga é fechada (VAGA_FECHADA) e Um candidato é contratado (CANDIDATURA_CONTRATADA):

{
  "id": "evt_56488",
  "tipo": "VAGA_FECHADA",
  "descricao": "Uma vaga é fechada",
  "versao": 1,
  "ocorridoEm": "2026-11-04T14:05:51.902Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "vagaId": 512,
    "vagaTitulo": "Analista Financeiro",
    "situacao": "FECHADA_PREENCHIDA",
    "gestorResponsavelId": 1021,
    "recrutadorId": 1043
  }
}

Case pelo vagaId que você guardou no passo 1 (ou leia o codigoPosicao em GET /vaga/{id}). Para o andamento de cada candidato, veja Candidaturas no seu sistema.

Pelo seu agente de IA

“Mova a Ana Ribeiro para Entrevista Gestor na vaga de Analista Financeiro e avise por e-mail.”

Com escopo de escrita, o agente acha a candidatura e a etapa e chama mover-etapa, com aprovação no seu cliente de IA; criar vaga também. Publicar, fechar e reprovar não são executados pelo MCP — são atos de confirmação forte, feitos na tela ou pela Tali.

Cuidados

A etapa precisa ser da mesma vaga. Pegue o etapaId em GET /etapa-processo/vaga/{vagaId} da vaga da candidatura; etapa de outra vaga é recusada com 400.
Etapa × desfecho. etapaAtual diz onde a pessoa está; desfecho (CONTRATADA, REPROVADA, DESISTIU, ENCERRADA_COM_VAGA) diz como terminou — vazio = ainda no processo. statusAtual é legado, derivado dos dois; não o use para decidir. PUT/PATCH /candidatura não mudam etapa, status nem desfecho (400 com a ação certa).
Quem está no processo, como a tela mostra. GET /candidatura/vaga/{vagaId}/candidatos devolve os ativos com etapa, dias na etapa, aderencia (0–100, com aderenciaBase CURRICULO ou COMPORTAMENTAL e aderenciaConfianca; nula = não medida) e selos (semDecisao, paradaDias, propostaSituacao…). Filtros etapa (nome) ou etapaId, semDecisao, aderenciaMin, aderenciaMax (abaixo de), origem, naoAtende (true = respondeu fora do esperado a uma eliminatória; false = atende), busca; ordenar, pagina, tamanho (até 1000). etapas traz, por etapa, doFiltro e total.
Várias pessoas de uma vez. POST /candidatura/vaga/{vagaId}/mover-varias (corpo etapaId) e .../reprovar-varias (corpo como o de reprovar) recebem a seleção na query: ids e/ou os mesmos filtros da lista, mais confirmarTotal (obrigatório com filtro; diferente do total atual = 409). Consulte antes GET /candidatura/vaga/{vagaId}/previa-lote com a mesma query. Até 300 pessoas por chamada. Cada pessoa é tratada à parte e itens diz quem ficou de fora e por quê. Seleção pela aderência é recusada para token de integração: a nota é calculada por IA, e esse lote só é confirmado por uma pessoa na tela ou na Tali. Pelo MCP, as ações em lote não são executadas (são de confirmação forte).
Impressão da equipe. POST /candidatura/{id}/avaliar com {"nota": 1-5} grava a impressão de quem chama (uma por pessoa; de novo substitui) e publica Um candidato recebe uma impressão (CANDIDATURA_AVALIADA).
Nenhum e-mail ao candidato sai na hora. Ele entra na fila (GET /ats-email-fila) com o horário de envio; POST /ats-email-fila/{id}/retirar cancela enquanto não saiu. O atraso é da empresa (GET/PUT /ats-configuracao); sem configuração, sai no minuto seguinte.
Para mudar um ou dois campos da vaga, use PATCH /vaga com o id: o PUT substitui o registro e apagaria status e urlPublica. No PATCH, um objeto sem id ("cargo": {}) limpa o vínculo e "codigoPosicao": "" limpa o código.
urlPublica nasce na primeira publicação e não muda ao pausar e republicar: os links divulgados continuam valendo.
Corpo acima de 8 KB é recusado pelo firewall — descrições muito longas também contam. Veja Limites.

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