Visão Geral

Bem-vindo à documentação da API pública do Recrutei. Nossa API foi desenhada para desenvolvedores que querem total controle sobre a exibição de suas vagas em portais externos, agregadores ou na própria página de carreiras da empresa.

Usando rotas REST simples e autenticadas, você pode obter os dados das vagas ativas da sua empresa em tempo real e renderizá-las de acordo com a identidade visual do seu site institucional.

Autenticação

A API exige autenticação por meio de um token de acesso seguro (Bearer Token). Cada requisição HTTP enviada para as rotas protegidas deve conter o header Authorization.

Mantenha seu Token Seguro

Nunca exponha o seu token no código público do frontend (como um repositório Git público ou no código do cliente final se não houver um proxy). Se necessário, utilize rotas de servidor (API routes ou um backend intermediário) para fazer a requisição.

Gerando seu Token de Acesso

Acesse o seu dashboard no Recrutei.
Vá para a página de Configurações.
Na seção de Tokens de API, crie um novo token fornecendo um nome descritivo (ex: "Integração Site de Carreiras").
Copie o token gerado. Ele só será exibido uma vez por questões de segurança.

GET/api/public/jobs

Listar Vagas

Este endpoint retorna uma lista contendo todas as vagas que estão ativas (`isActive: true`) e vinculadas à sua conta. A lista vem ordenada de forma decrescente pela data de publicação (`postedAt`).

Atributos do Retorno

Campo	Tipo	Descrição
id	String	Identificador único da vaga no formato CUID.
title	String	Título da vaga (ex: "Desenvolvedor Front-end").
location	String	Localidade de trabalho (ex: "Remoto" ou "São Paulo, SP").
area	String	Área da vaga (ex: "Tecnologia", "Design").
type	String	Tipo de contratação (ex: "CLT", "PJ", "Estágio").
description	String	Descrição completa da vaga em formato de texto/HTML.
applicationUrl	String	URL pública da página de candidatura da vaga.
postedAt	String (ISO)	Data e hora em que a vaga foi criada.

Chamada ExemplocURL

curl https://recrutei.app/api/public/jobs \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta JSONJSON

{
  "data": [
    {
      "id": "clx...",
      "title": "Desenvolvedor(a) Front-end",
      "location": "Remoto",
      "area": "Tecnologia",
      "type": "CLT",
      "description": "...",
      "applicationUrl": "https://recrutei.app/forms/vaga-desenvolvedor",
      "postedAt": "2026-06-15T12:00:00.000Z"
    }
  ]
}

GET/api/public/jobs/{id}

Detalhes da Vaga

Este endpoint retorna os atributos detalhados de uma única vaga ativa com base em seu ID passado no path da requisição.

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	String	Sim	O identificador (id) único da vaga.

Chamada ExemplocURL

curl https://recrutei.app/api/public/jobs/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta JSONJSON

{
  "data": {
    "id": "{id}",
    "title": "Desenvolvedor(a) Front-end",
    "location": "Remoto",
    "area": "Tecnologia",
    "type": "CLT",
    "description": "...",
    "applicationUrl": "https://recrutei.app/forms/vaga-desenvolvedor",
    "postedAt": "2026-06-15T12:00:00.000Z"
  }
}

Tratamento de Erros

Todas as rotas de API retornam códigos de status HTTP padrão do setor para indicar o sucesso ou a falha de uma requisição.

Códigos HTTP Utilizados

Código	Descrição	Estrutura do Erro
200 OK	A requisição foi bem sucedida.	-
401 Unauthorized	O token de autenticação está ausente, é inválido ou expirou.	{ "error": "Token de acesso inválido ou ausente." }
404 Not Found	A vaga específica ou recurso não pôde ser encontrado.	{ "error": "Vaga não encontrada." }

Amostras de Código

Use o cabeçalho Authorization com seu Bearer Token gerado.

Exemplo Header HTTPHTTP

Authorization: Bearer SEU_TOKEN