API DAS VAGAS QUE A GENTE VÊ POR AQUIMAIS CONEXÕES PARA
OPORTUNIDADES

01 / Comece por aqui

Uma chave para a sua integração

O acesso à API é destinado a parceiros autorizados. Para solicitar uma chave, fale conosco pelo contato do ViUmaVaga e conte onde e como você pretende exibir as vagas.

1. 1

   Converse com a gente

   Apresente seu site, comunidade ou plataforma e a proposta de integração.

2. 2

   Receba sua credencial

   Após a autorização, você recebe um token exclusivo para o seu projeto.

3. 3

   Conecte pelo seu servidor

   Guarde a chave em um local seguro e faça sua primeira consulta seguindo o exemplo abaixo.

02 / Autenticação

Envie o token no cabeçalho

Todas as consultas precisam de uma chave válida. Use HTTPS e envie o token no cabeçalho Authorization da requisição:

Authorization: Bearer SEU_TOKEN

03 / Consulta e filtros

Busque as vagas que quer exibir

A API retorna somente vagas publicadas e disponíveis segundo as regras do Conecta. A ordenação vai da publicação mais recente para a mais antiga, com desempate por ID.

Sem week_offset, a consulta inclui todas as vagas elegíveis. As semanas vão de segunda a domingo, considerando a data de publicação e o fuso horário do site. Use inteiros sem sinais, espaços ou zeros à esquerda.

Sua primeira chamada

Defina V1V_API_TOKEN no ambiente do seu servidor. Este exemplo consulta a primeira página de vagas da semana atual:

curl --get 'https://viumavaga.com.br/conecta/wp-json/v1v/v1/vagas' \
  --header "Authorization: Bearer $V1V_API_TOKEN" \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=20' \
  --data-urlencode 'week_offset=0'

04 / Resposta

Resumos prontos para conectar

A resposta traz um array data com as vagas e um objeto pagination com os dados de navegação. O exemplo abaixo é ilustrativo:

{
    "data": [
        {
            "titulo": "Pessoa desenvolvedora PHP",
            "resumo": "Desenvolvimento PHP e WordPress em equipe remota.",
            "url": "https://viumavaga.com.br/conecta/empresa-exemplo/pessoa-desenvolvedora-php/?utm_source=comunidade-exemplo&utm_medium=api&utm_campaign=feed-vagas",
            "data_publicacao": "2026-10-30T09:00:00-03:00",
            "fonte": "ViUmaVaga",
            "empresa": "Empresa Exemplo",
            "local": "Brasil",
            "modelo_trabalho": "Remoto"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}

Como navegar entre páginas

Leia pagination.total_pages e avance o parâmetro page. O campo total informa a quantidade de vagas elegíveis no recorte, e per_page informa o tamanho solicitado para cada página.

Quando não houver resultados, data será []. Uma consulta sem nenhuma vaga elegível retorna total: 0 e total_pages: 0. Páginas além do fim também retornam uma lista vazia com HTTP 200.

05 / Limites e erros

Respeite o ritmo das consultas

Cada token permite até 60 consultas por hora, incluindo chamadas com parâmetros inválidos e respostas vindas do cache interno. A janela é fixa, alinhada à hora UTC: por exemplo, das 10:00:00 às 10:59:59.

Os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining informam a cota quando o contador é consumido. Se receber HTTP 429, aguarde os segundos indicados em Retry-After antes de tentar novamente.

Erros seguem o formato REST do WordPress, com os campos code, message e data.status.

06 / Boas conexões

Preserve a origem de cada vaga

1. Direcione à página original. Use o valor de url fornecido pela API para que a pessoa veja os detalhes e se candidate.
2. Mantenha todas as UTMs. Preserve integralmente utm_source, utm_medium, utm_campaign e os demais parâmetros recebidos.
3. Dê o crédito. Exiba “via ViUmaVaga” próximo à vaga.
4. Publique apenas o resumo. Não copie, reconstrua ou republique a descrição completa.
5. Proteja a sua chave. Não compartilhe o token com terceiros nem o exponha em aplicações frontend ou código público.

O acesso pode ser revogado em caso de uso indevido. Se a chave for exposta, fale conosco para revogar a credencial e solicitar uma nova.