Levar o candidato aprovado até o cadastro

O candidato foi aprovado no processo seletivo. Em vez de redigitar o cadastro, você abre a admissão a partir da própria candidatura: a pessoa recebe o link do portal, preenche os dados e envia os documentos, e na finalização o colaborador nasce com o que ela informou e com a posição definida na vaga.

Quando usar	O seu fluxo (ou o seu ATS integrado) decide a contratação e quer disparar a admissão sozinho
Porta	REST · Agente (MCP) para iniciar e consultar
Você vai precisar	módulo CONTRATACOES; permissão ADMISSAO (edição) para iniciar e finalizar; CANDIDATO (leitura) para achar a candidatura; JWT de um usuário de integração

Como funciona

candidatura aprovada ──► POST /admissao/processo/iniciar-por-candidatura
                              │  e-mail com o link do portal; candidatura vira EM_ADMISSAO
                              ▼
            pessoa preenche dados e envia documentos no portal
                              │
                              ▼
            RH aprova cada documento ──► processo em APROVADO
                              │
                              ▼
     POST /admissao/processo/{id}/finalizar-e-converter
          colaborador criado · candidatura vira CONTRATADO
          eventos ADMISSAO_CONCLUIDA · COLABORADOR_CRIADO · CANDIDATURA_CONTRATADA

Passo a passo

1. Ache a candidatura. Liste as candidaturas da vaga e guarde o id de quem foi aprovado:

   curl https://api.taitecnologia.com/vaga/128/candidaturas \
     -H "Authorization: Bearer $TAI_TOKEN"

   Se a sua integração já assina Um candidato muda de etapa (CANDIDATURA_MOVIDA_ETAPA) num webhook (candidaturas no seu sistema), o candidaturaId vem nele — e a chegada à etapa Contratado (etapaDestino) pode ser o gatilho para iniciar a admissão.

2. Inicie a admissão.

   curl -X POST https://api.taitecnologia.com/admissao/processo/iniciar-por-candidatura \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "candidaturaId": 9412, "dataAdmissaoPrevista": "2026-11-03" }'

   Só candidaturaId é obrigatório. Opcionais: responsavelId (colaborador que acompanha — sem ele, é o usuário da chamada), observacoes, modeloChecklistId e documentosCustomizados.

   A resposta é o processo: guarde o id. Ele nasce em AGUARDANDO_DOCUMENTOS, com o linkPortal da pessoa, e o e-mail com o link já saiu. A candidatura passa para EM_ADMISSAO.

   Os documentos pedidos vêm do modelo do tipo de contratação da vaga (CLT, estágio, PJ…); confira qual seria com GET /admissao/checklist-modelo/resolver?tipoContrato=CLT.

3. Acompanhe até APROVADO. Consulte GET /admissao/processo/{id} (campo status, documentosEnviados, documentosAprovados). Cada documento enviado é aprovado ou rejeitado pelo RH na tela Contratações › Admissão, ou pela API:

   POST /admissao/processo/311/documento/5120/aprovar

   POST /admissao/processo/311/documento/rejeitar
   Content-Type: application/json
   
   { "documentoId": 5121, "motivo": "Comprovante de residência ilegível" }

   Com todos os obrigatórios aprovados, o processo vai sozinho para APROVADO.

4. Confira o cadastro. GET /admissao/processo/{id}/dados-cadastrais devolve o que a pessoa preencheu no portal (dados pessoais, endereço, documentos, contatos de emergência). Volta vazio se ela ainda não preencheu.

5. Finalize e crie o colaborador.

   curl -X POST https://api.taitecnologia.com/admissao/processo/311/finalizar-e-converter \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "dataAdmissaoEfetiva": "2026-11-03",
       "dadosColaborador": { "emailCorporativo": "bruno.lima@suaempresa.com.br" }
     }'

   O colaborador é montado assim:

   • base: o que a pessoa preencheu no portal;
   • por cima: os campos que você mandar em dadosColaborador (só os não nulos);
   • vínculo: empresaId, departamentoId, subDepartamentoId, cargoId, centroCustoId do corpo; o que faltar vem da posição definida na vaga;
   • data de admissão: dataAdmissaoEfetiva; sem ela, a prevista; sem as duas, o dia da chamada.

   A resposta traz colaborador (guarde o id), colaboradorCriado e assinaturasPendentes (documentos que a empresa mandou assinar e ainda não foram assinados — não impedem finalizar).

O que acontece ao finalizar

• A candidatura passa para CONTRATADO.
• Os documentos do portal, os questionários, os diagnósticos e a carta proposta da candidatura passam a pertencer ao colaborador e aparecem no perfil dele.
• A TAI publica Uma admissão é concluída (ADMISSAO_CONCLUIDA), Um colaborador é cadastrado (COLABORADOR_CRIADO) e Um candidato é contratado (CANDIDATURA_CONTRATADA, com o candidaturaId e o colaboradorId criado) — ponto de partida do onboarding automático e o sinal para o seu ATS fechar a candidatura.

Durante o processo, o seu sistema acompanha cada passo sem consultar a API assinando num webhook os eventos da admissão — documento enviado, aprovado ou rejeitado, assinatura enviada, admissão cancelada. Todos trazem processoId e candidaturaId; a lista está no guia de Admissão.

Contratar inicia a admissão

POST /candidatura/{id}/contratar dá à candidatura o desfecho: "CONTRATADA" e inicia a admissão com os dados dela (o mesmo que iniciar-por-candidatura; corpo opcional com responsavelId, modeloChecklistId, dataAdmissaoPrevista) — a resposta traz processoAdmissaoId. Fora da última etapa e sem proposta aceita, exige justificativa (400 sem ela); consulte antes GET /candidatura/{id}/contratacao. Iniciar a admissão por iniciar-por-candidatura também marca a candidatura como contratada. O evento Um candidato é contratado sai uma vez por candidatura, no primeiro desses momentos.

Atalho: colaborador primeiro

Quando você já tem todos os dados e não quer o portal, POST /candidatura/{id}/converter-colaborador cria o colaborador na hora, com o corpo de um colaborador (ColaboradorDTO): nome, e-mail e telefone que faltarem vêm do candidato, e o vínculo que faltar vem da posição da vaga. Se a configuração da admissão tiver iniciarAutomaticamenteAposAts ligado, a TAI abre em seguida um processo de admissão para esse colaborador, só para coletar os documentos.

Pelo seu agente de IA

“Inicie a admissão do candidato aprovado na vaga de Analista Financeiro, com início em 3 de novembro.”

Com escopo de escrita, o agente acha a candidatura e chama iniciar-por-candidatura — o seu cliente de IA pede aprovação antes. Consultar o andamento é leitura livre. Aprovar documento e finalizar a admissão não são executados pelo MCP: são atos de confirmação forte, feitos na tela ou pela Tali.

Cuidados

• Um processo ativo por candidatura. Iniciar de novo enquanto há um processo em andamento responde 400 citando o processo existente — renove o link dele (POST /admissao/processo/{id}/renovar-token) em vez de criar outro.
• Finalizar fora de APROVADO responde 400 com o status atual.
• CPF já cadastrado: se a pessoa informa no portal um CPF que já é de um colaborador da conta, o portal recusa — trate a readmissão pelo cadastro existente.
• Merge não apaga: campo enviado como null em dadosColaborador mantém o valor do portal. Para esvaziar um campo, ajuste depois no colaborador (PATCH /colaborador).
• Datas civis em yyyy-MM-dd — veja Datas e formatos.