Mostrar tus puestos en tu página de empleo

Actualizado 6 de septiembre de 2026

La razón por la que existe la API: tus puestos en tu dominio, con las personas candidatas postulándose a través del formulario alojado que registra su consentimiento. Esta página es el patrón, con las decisiones que importan señaladas.

Consulta en el servidor y de forma programada

Lee la API desde tu paso de compilación o desde tu servidor, nunca desde el navegador de quien visita, y nunca en cada carga de página. Una página de empleo cambia unas pocas veces por semana; consultarla cada quince minutos es generoso.

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

Una sincronización mínima en 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;
}

Cachea, y sabe cuándo volver a consultar

• Cachea la lista entera y reconstruye tu página desde la caché. No caches por visitante.
• Vuelve a consultar con un temporizador, no bajo demanda. Si tu sitio se compila de forma estática, lanza una compilación con ese mismo temporizador.
• updatedSince limita una reconsulta a los puestos editados, publicados o cerrados desde tu última sincronización. No detecta un puesto que caducó, porque caducar es un reloj pasando por una fecha y no se escribe nada cuando ocurre. O lees tú el expiresAt de cada puesto cacheado, o pides status=published y tratas como desaparecido todo lo que falte en la respuesta.

Muestra la lista y el detalle

Usa el vocabulario del propio anuncio y mapéalo una vez. employmentType es full_time o part_time; contractType es uno de permanent, part_time, fixed_term, contract, casual; el level de una competencia es required o nice_to_have. Estos valores son los mismos en todas las superficies de Wipperoz, así que un mapeo que escribas hoy seguirá funcionando.

url es la página del puesto en Wipperoz, cuando la tiene. Puedes enlazarla, pero el sentido de esta guía es que no tienes por qué.

Envía a las personas candidatas a applyLink

Cada vacante lleva un applyLink. Haz que tu botón “Postularse” lleve ahí.

El src=careers&account=… del enlace es como la página de postulación registra el origen de entrada. Déjalo intacto; es lo que te permite ver, en Orbit, qué candidaturas vinieron de tu sitio.

Puestos cerrados y caducados

Un puesto que ya has enlazado puede cerrarse. La API lo sigue devolviendo con status: closed o status: expired para que tu página pueda:

• mantener viva la URL y mostrar “este puesto se ha cerrado”, o
• quitar el puesto de la lista y redirigir su URL a la portada de tu página de empleo.

Cualquiera de las dos está bien. Devolver un 404 en silencio es el único resultado que hay que evitar, y el campo de estado existe para que nunca tengas que hacerlo.

Datos estructurados

Si emites JSON-LD de JobPosting, los campos se corresponden directamente:

Referencia