Afficher vos postes sur votre page carrières

Mis à jour 6 septembre 2026

La raison d’être de l’API : vos postes sur votre domaine, les candidats postulant toujours via le formulaire hébergé qui enregistre leur consentement. Cette page décrit le schéma, avec les décisions qui comptent mises en avant.

Récupérez côté serveur, à intervalle régulier

Lisez l’API depuis votre étape de build ou depuis votre serveur, jamais depuis le navigateur du visiteur, et jamais à chaque affichage de page. Une page carrières change quelques fois par semaine ; la récupérer toutes les quinze minutes est déjà généreux.

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

Une synchronisation minimale 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;
}

Mettez en cache, et sachez quand rafraîchir

• Mettez toute la liste en cache et reconstruisez votre page à partir du cache. Ne mettez pas en cache par visiteur.
• Rafraîchissez sur minuterie, pas à la demande. Si votre site se construit statiquement, déclenchez un build sur la même minuterie.
• updatedSince restreint un rafraîchissement aux postes modifiés, publiés ou clos depuis votre dernière synchronisation. Il ne capte pas un poste qui a expiré, car expirer c’est une horloge qui passe une date et rien n’est écrit à ce moment-là. Soit vous lisez vous-même l’expiresAt de chaque poste en cache, soit vous demandez status=published et considérez comme disparu tout ce qui manque dans la réponse.

Affichez la liste et le détail

Utilisez le vocabulaire de l’annonce et mappez-le une fois. employmentType vaut full_time ou part_time ; contractType est l’un de permanent, part_time, fixed_term, contract, casual ; le level d’une compétence vaut required ou nice_to_have. Ces valeurs sont les mêmes sur toutes les surfaces Wipperoz : un mapping écrit aujourd’hui continuera de fonctionner.

url est la page du poste sur Wipperoz, quand il en a une. Vous pouvez y faire un lien, mais tout l’intérêt de ce guide est que vous n’y êtes pas obligé.

Envoyez les candidats vers applyLink

Chaque offre porte un applyLink. Faites pointer votre bouton « Postuler » vers celui-ci.

Le src=careers&account=… du lien est ce qui permet à la page de candidature d’enregistrer l’origine. Laissez-le intact ; c’est ce qui vous permet de voir, dans Orbit, quelles candidatures viennent de votre site.

Postes clos et expirés

Un poste vers lequel vous avez déjà fait un lien peut se clore. L’API continue de le renvoyer avec status: closed ou status: expired, pour que votre page puisse :

• garder l’URL vivante et afficher « ce poste est clos », ou
• retirer le poste de la liste et rediriger son URL vers l’accueil de votre page carrières.

Les deux conviennent. Renvoyer un 404 en silence est le seul résultat à éviter, et le champ de statut existe pour que vous n’ayez jamais à le faire.

Données structurées

Si vous émettez du JSON-LD JobPosting, les champs correspondent directement :

Référence