Publicar as vagas no seu site

A página “Trabalhe conosco” do site da empresa mostra as vagas abertas e recebe candidaturas, mas quem gerencia o processo seletivo é o RH, na TAI. Com as rotas públicas do portal de vagas, o site lista as vagas publicadas e envia a candidatura (com o currículo) direto para o pipeline da vaga — sem login e sem redigitação.

Quando usar	O site institucional tem a própria página de vagas, com o layout da empresa
Porta	Página pública (rotas sem autenticação)
Você vai precisar	módulo CONTRATACOES; o subdomínio do portal configurado; nenhuma credencial nas chamadas

Prefere não construir nada? O portal de carreiras da TAI já é essa página, pronta, no subdomínio da empresa.

Como funciona

site da empresa ──► GET  /public/portal-vagas/{subdominio}/vagas            lista paginada
                ──► GET  /public/portal-vagas/{subdominio}/vagas/{urlPublica} detalhe
visitante envia ──► POST /public/portal-vagas/{subdominio}/candidatar        dados + currículo
                         │
                         ▼
        candidatura na 1ª etapa da vaga · e-mail de confirmação ao candidato
        evento CANDIDATURA_CRIADA para webhooks e automações

Passo a passo

1. Descubra o subdomínio. É o mesmo do portal de carreiras, definido em Contratações › Configurações › Portal de Vagas (ou por GET /tenant/meu-subdominio, com o token do titular). Nos exemplos, suaempresa. Todas as rotas abaixo ficam em https://api.taitecnologia.com/public/portal-vagas/{subdominio} e não pedem autenticação.

2. Cabeçalho da página. GET /empresa devolve nomeEmpresa, subdominio e logomarcaUrl.

3. Liste as vagas publicadas.

   curl "https://api.taitecnologia.com/public/portal-vagas/suaempresa/vagas?page=0&size=20&sort=createdAt,desc"

   A resposta é paginada (content, totalElements, last…). Cada vaga traz id, titulo, nomeEmpresa, localizacao, tipoContratacao, modalidadeTrabalho, descricao, responsabilidades, requisitosObrigatorios, requisitosDesejaveis, faixaSalarial, beneficios, horarioTrabalho, urlPublica e dataCriacao. Use search= para a caixa de busca e GET /vagas/count para o contador (“12 vagas abertas”).

   Só aparecem vagas com status Publicada. Pausar ou fechar a vaga na TAI a tira da lista.

4. Página da vaga. Use urlPublica no endereço da sua página (/trabalhe-conosco/analista-financeiro-3f9a1c2b) e busque o detalhe por ele:

   curl https://api.taitecnologia.com/public/portal-vagas/suaempresa/vagas/analista-financeiro-3f9a1c2b

   Guarde o id da vaga: é ele que vai na candidatura.

5. Envie a candidatura. multipart/form-data com duas partes:

   Parte	Conteúdo
   dados	JSON (com Content-Type: application/json): vagaId, nomeCompleto, email, telefone, cpf, linkedin, portfolio, cartaApresentacao, comoConheceu, respostas, pcdAutodeclarado, aceitouPrivacidade e consentiuReserva (veja abaixo)
   curriculo	Arquivo PDF, DOC ou DOCX

   cURL

   curl -X POST https://api.taitecnologia.com/public/portal-vagas/suaempresa/candidatar \
     -F 'dados={"vagaId":128,"nomeCompleto":"Diego Martins","email":"diego@gmail.com","telefone":"31999990000","comoConheceu":"Site da empresa"};type=application/json' \
     -F 'curriculo=@curriculo.pdf'

   JavaScript

   const form = new FormData()
   form.append('dados', new Blob([JSON.stringify({
     vagaId: 128,
     nomeCompleto: 'Diego Martins',
     email: 'diego@gmail.com',
     telefone: '31999990000',
     comoConheceu: 'Site da empresa',
   })], { type: 'application/json' }))
   form.append('curriculo', arquivo) // File do <input type="file">
   
   const resp = await fetch(
     'https://api.taitecnologia.com/public/portal-vagas/suaempresa/candidatar',
     { method: 'POST', body: form },
   )
   if (!resp.ok) {
     const erro = await resp.json().catch(() => null)
     mostrarErro(erro?.message) // no 400, a mensagem é para o candidato ler
   }

   Perguntas da vaga. O detalhe da vaga (GET /public/portal-vagas/{subdominio}/vagas/{urlPublica}) traz perguntas (id, texto, tipo, opcoes, obrigatoria) — mostre todas no seu formulário e mande respostas: [{"perguntaId": 31, "valor": "SIM"}]. Valores: SIM/NAO; a opção, em ESCOLHA; o número, em NUMERO e PRETENSAO_SALARIAL (“8500” ou “R$ 8.500,00”); IMEDIATA, 15_DIAS, 30_DIAS ou MAIS_DE_30_DIAS, em DISPONIBILIDADE. Com oferecerAutodeclaracaoPcd, ofereça a autodeclaração de PCD (opcional) em pcdAutodeclarado. A vaga afirmativa vem em vagaAfirmativa e vagaAfirmativaTexto.

   Consentimentos. aceitouPrivacidade: true registra o aceite da política de privacidade e consentiuReserva: true autoriza a empresa a considerar a pessoa para outras vagas por 12 meses (deixe desmarcado por padrão). Os dois são opcionais para a API, mas sem consentiuReserva a empresa não consegue “Manter na Reserva” ao reprovar essa pessoa. O cpf também é opcional: entra na admissão.

   A resposta é o recibo: id, vagaId, vagaTitulo, statusAtual (NOVO), dataCandidatura e emailMascarado (para onde foi o link de Minha candidatura, ex.: di••@gm••.com). Mostre ao visitante a confirmação com esse e-mail: o link de acompanhamento vai só por e-mail, nunca na resposta.

6. (Opcional) Preencha o formulário pelo currículo. POST /public/portal-vagas/{subdominio}/curriculo/ler com a parte curriculo (PDF ou DOCX, até 5 MB) devolve o que achou no arquivo — nome, email, telefone, linkedin — para o visitante conferir. O arquivo não é guardado; até 10 leituras por minuto por IP.

7. (Opcional) “Já me candidatei”. POST /public/candidato/novo-link com {"email": "...", "subdominio": "suaempresa"} manda ao candidato um link novo de Minha candidatura (o anterior deixa de valer). Responde 204 exista ou não a candidatura.

O que a TAI confere

Antes de gravar o currículo, a candidatura é recusada com 400 e uma mensagem legível quando:

Situação	Mensagem
Sem vagaId	Informe a vaga
Sem nomeCompleto ou sem email	Informe o nome completo / Informe o e-mail
Sem currículo, ou fora de PDF, DOC e DOCX	Envie o currículo / O currículo precisa ser PDF, DOC ou DOCX
A vaga não é da empresa do subdomínio	Vaga não encontrada neste portal
A vaga não está Publicada	Vaga não está aberta para candidaturas
O e-mail já se candidatou a esta vaga	Candidato já se candidatou para esta vaga
Pergunta obrigatória sem resposta	Responda: texto da pergunta
Resposta fora do tipo (texto onde vai número, opção que não existe)	Responda com um número: … / Escolha uma das opções: …

Subdomínio inexistente responde 404. Mostre a mensagem do 400 no formulário: ela foi escrita para o candidato ler.

O que acontece depois

• O candidato é identificado pelo e-mail, que vale em toda a TAI: se ele já se candidatou a outra vaga, a candidatura nova usa o cadastro existente.
• A candidatura entra na primeira etapa da vaga, e o candidato novo fica com origem SITE_CARREIRA. Ela aparece para o recrutador em Contratações › Vagas › Ver Candidatos.
• A TAI publica Alguém se candidata a uma vaga (CANDIDATURA_CRIADA) — para avisar o time ou outro sistema, veja Candidaturas no seu sistema.

Automatize

• Guarde as vagas em cache no seu site (alguns minutos bastam): elas mudam pouco e a lista não depende de quem está visitando. Para atualizar o cache na hora certa, assine num webhook Uma vaga é publicada (VAGA_PUBLICADA) e Uma vaga é fechada (VAGA_FECHADA) e releia a lista quando chegarem — ambos trazem vagaId e vagaTitulo. Pausar uma vaga não publica evento: mantenha também a expiração do cache.
• A rotina Vaga sem candidaturas (começa desligada) avisa o recrutador quando uma vaga publicada passa uma semana sem candidatura nova.

Cuidados

• Use sempre /public/portal-vagas/{subdominio}. As rotas /carreiras/vagas listam as vagas publicadas de todas as empresas da TAI — é o agregador de vagas, não o site da sua empresa.
• A parte dados precisa do tipo application/json. Sem ele, o servidor não reconhece o JSON.
• Duplicidade é por e-mail e vaga. Um segundo envio do mesmo formulário responde 400 — trate como “você já se candidatou”, não como erro do site.
• O envio da candidatura é rota de upload: o limite de 8 KB de corpo não se aplica a ela, mas o dos arquivos sim — veja Limites.
• Ponha no formulário o aviso de privacidade da empresa: os dados do candidato passam a ser tratados pelo RH na TAI.