Mostrar as suas vagas na sua página de carreiras

Atualizado 6 de setembro de 2026

A razão pela qual a API existe: as suas vagas no seu domínio, com os candidatos a candidatarem-se pelo formulário alojado que regista o consentimento. Esta página é o padrão, com as decisões que importam assinaladas.

Leia no servidor, de forma agendada

Leia a API a partir do seu passo de build ou do seu servidor, nunca do navegador de quem visita, e nunca a cada visualização de página. Uma página de carreiras muda algumas vezes por semana; lê-la de quinze em quinze minutos já é generoso.

curl "https://api.wipperoz.com/v1/jobs?status=published&limit=100" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Uma sincronização mínima em Node:

const BASE = 'https://api.wipperoz.com';

export async function fetchOpenRoles(): Promise<Job[]> {
  const jobs: Job[] = [];
  let cursor: string | null = null;

  do {
    const url = new URL('/v1/jobs', BASE);
    url.searchParams.set('status', 'published');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, {
      headers: {Authorization: `Bearer ${process.env.ORBIT_API_KEY}`},
    });
    if (!response.ok) {
      throw new Error(`Orbit API ${response.status}: ${await response.text()}`);
    }

    const page = (await response.json()) as {jobs: Job[]; nextCursor: string | null};
    jobs.push(...page.jobs);
    cursor = page.nextCursor;
  } while (cursor);

  return jobs;
}

Guarde em cache e saiba quando voltar a ler

• Guarde a lista inteira em cache e reconstrua a sua página a partir dela. Não guarde cache por visitante.
• Volte a ler com um temporizador, não a pedido. Se o seu site é construído estaticamente, despolete um build no mesmo temporizador.
• updatedSince limita uma nova leitura às vagas editadas, publicadas ou fechadas desde a sua última sincronização. Não apanha uma vaga que expirou, porque expirar é um relógio a passar uma data e nada é escrito quando isso acontece. Ou lê você o expiresAt de cada vaga em cache, ou pede status=published e trata como desaparecido tudo o que faltar na resposta.

Mostre a lista e o detalhe

Use o vocabulário do próprio anúncio e mapeie-o uma vez. employmentType é full_time ou part_time; contractType é um de permanent, part_time, fixed_term, contract, casual; o level de uma competência é required ou nice_to_have. Estes valores são os mesmos em todas as superfícies da Wipperoz, por isso um mapeamento que escreva hoje continua a funcionar.

url é a página da vaga na Wipperoz, quando existe. Pode ligar para ela, mas o sentido deste guia é que não tem de o fazer.

Envie os candidatos para o applyLink

Cada vaga traz um applyLink. Faça o seu botão “Candidatar” apontar para lá.

O src=careers&account=… da ligação é como a página de candidatura regista a origem de entrada. Deixe-o intacto; é o que lhe permite ver, na Orbit, que candidaturas vieram do seu site.

Vagas fechadas e expiradas

Uma vaga para a qual já ligou pode fechar. A API continua a devolvê-la com status: closed ou status: expired para que a sua página possa:

• manter o URL vivo e mostrar “esta vaga fechou”, ou
• retirar a vaga da lista e redirecionar o seu URL para a entrada da sua página de carreiras.

Qualquer uma serve. Devolver um 404 em silêncio é o único resultado a evitar, e o campo de estado existe para que nunca tenha de o fazer.

Dados estruturados

Se emitir JSON-LD de JobPosting, os campos correspondem diretamente:

Referência