Associer les candidatures aux offres

Chaque candidature envoyée par POST /applications doit désigner une offre. Rien n'est à choisir à la création de l'intégration : c'est la requête qui décide, et les modes cohabitent sur une même intégration.

Où vivent vos offres ?	Envoyez	Mode
Dans Omogen	job_opportunity_id	Direct (recommandé)
Dans votre ATS	external_job_id + job_title + job_description	Push
Dans votre ATS, lisible par Omogen	external_job_id seul	Pull
Nulle part : Omogen choisit	ni l'un ni l'autre	Triage

job_opportunity_id et external_job_id sont exclusifs : envoyer les deux renvoie 400 INVALID_PAYLOAD.

Direct (recommandé)

Les offres sont créées et réglées dans Omogen (critères, trame d'entretien). Votre ATS envoie seulement l'ID API de l'offre dans job_opportunity_id.

Pour récupérer cet ID :

• Une offre : dans Omogen, menu ⋯ de la liste des offres → Copier l'ID API, ou onglet Paramètres de l'offre.
• Toutes les offres : GET /jobs, paginé, qui renvoie pour chaque offre son job_opportunity_id, son titre, sa date, et si elle est prête (is_ready) ou archivée.

Un job_opportunity_id d'une autre organisation renvoie 400 JOB_OPPORTUNITY_NOT_FOUND.

Push : vous envoyez l'offre

Vos offres vivent dans votre ATS. Envoyez votre identifiant dans external_job_id :

• la première fois, avec job_title et job_description dans la candidature, ou avant, par POST /jobs ;
• les fois suivantes, external_job_id suffit : Omogen retrouve l'offre.

Une offre inconnue sans description (et sans pull) renvoie 400 JOB_DETAILS_REQUIRED.

Pull : Omogen lit l'offre chez vous

Même principe que le push, mais Omogen vient lire l'offre inconnue sur votre API. Dans la fiche de l'intégration, section Récupération des offres (mode pull), renseignez URL d'une offre, par exemple https://api.votre-ats.com/jobs/{job_id}.

Quand une candidature cite une offre inconnue sans description, Omogen appelle une seule fois :

GET https://api.votre-ats.com/jobs/JOB-12345
Accept: application/json
x-api-key: <vos en-têtes configurés>

Votre API répond 200 :

{
  "job_title": "Aide-soignant(e) de nuit",
  "job_description": "EHPAD à Lyon, CDI 35h, nuits fixes..."
}

job_title est obligatoire. Envoyez aussi job_description : sans elle, Omogen ne peut pas extraire les critères de l'offre.

Erreurs renvoyées à POST /applications

Votre API répond	Code renvoyé
404	400 JOB_FETCH_NOT_FOUND
autre 4xx ou 5xx	502 JOB_FETCH_HTTP_ERROR
rien dans les 30 s, erreur réseau	502 JOB_FETCH_NETWORK_ERROR
JSON invalide	502 JOB_FETCH_INVALID_RESPONSE
200 sans job_title	502 JOB_FETCH_MISSING_TITLE

Vérifier que l'appel vient d'Omogen (signature)

Renseignez un Secret de signature. Chaque appel porte alors :

OM-OMOGEN-TIMESTAMP: 1790000000
OM-OMOGEN-REQUEST: hex(HMAC_SHA256(secret, "<timestamp>.<job_id>"))

Recalculez la signature de votre côté, et rejetez les appels dont le timestamp s'écarte de plus de 5 minutes de votre horloge.

Triage

N'envoyez ni job_opportunity_id ni external_job_id : Omogen lit le CV et affecte la candidature à l'offre la plus adaptée. Ce mode se configure avec l'équipe Omogen.