Intégration partenaire avec un site d'emploi

Guide technique destiné aux sites d'emploi qui souhaitent intégrer Kit par API, flux XML, liens de candidature, webhooks de cycle de vie ou dépôt natif de candidatures.

Objet de ce guide

Kit est un ATS multi-tenant qui publie déjà des offres sur des sites d’emploi publics, fournit des flux XML et Atom par employeur, expose une API publique et reçoit des candidatures. Si votre site dispose déjà d’une API employeur, d’un importateur de flux XML, d’un parcours OAuth, d’un point de terminaison de taxonomie, d’un rappel de modération ou d’un contrat de candidature externe, nous nous y adapterons.

Ce guide est une liste de contrôle pour la découverte, pas une spécification imposée aux partenaires. Il vise à raccourcir le premier échange technique : il présente les capacités actuelles de Kit, les décisions habituelles et nos marges d’adaptation à votre processus.

Important

Votre contrat de production fait autorité. Nous mapperons Kit sur les champs, l’authentification, le cycle de vie, les règles de crédit et le parcours candidat documentés par le site. Les exemples ci-dessous décrivent les capacités actuelles de Kit sans présumer qu’un site donné accepte ces formats.

Formes d’intégration

La plupart des partenariats utilisent une ou plusieurs formes :

Forme	Cas idéal	Ce que fournit Kit
Envoi vers l’API du site	Le site possède déjà une API employeur ou de multidiffusion	Création, mise à jour, suspension ou fermeture et synchronisation des statuts par un adaptateur propre au site
Lecture d’un flux par le site	Le site importe régulièrement des flux d’employeur ou d’ATS	Flux XML public et cacheable par employeur ; nous ajoutons le dialecte du site selon son schéma officiel
Lien vers une candidature externe	Le site renvoie les candidats vers l’ATS de l’employeur	URL stable de l’offre ou lien direct de candidature avec attribution de la source
Candidature native transmise à Kit	Le site collecte la candidature et peut la transmettre	API serveur limitée au tenant, téléversement présigné du CV, schéma du formulaire et accusé de réception sans PII

Nous pouvons commencer par la forme la plus simple prise en charge, puis ajouter la synchronisation des statuts ou des candidatures. Un flux tiré n’oblige pas le site à adopter le modèle d’envoi de Kit. Une intégration par envoi n’impose pas non plus l’un de nos dialectes de flux existants.

Formats déjà fournis par Kit

Flux publics XML et Atom

Chaque portail carrière hébergé dispose d’un flux par employeur contenant uniquement les offres qui acceptent des candidatures :

https://startupkit.app/careers/example/jobs.xml
https://startupkit.app/careers/example/jobs/atom

Les domaines carrière personnalisés exposent les mêmes flux sous /jobs.xml et /jobs/atom. Kit produit actuellement les dialectes Adzuna, Atom 1.0, Jooble, Jobrapido, Talent.com et Uitzendbureau. Ils illustrent les données disponibles, sans supposer qu’un autre site les accepte. Dès qu’un partenaire fournit son schéma et des exemples de charge utile, Kit peut produire un dialecte dédié à une URL stable. Les employeurs qui utilisent Talent.com peuvent suivre Publier des offres sur Talent.com.

Une entrée utilise un identifiant public stable et peut contenir :

le titre et la description HTML ;
le nom de l’employeur, le service ou la catégorie, le lieu et le statut de télétravail ;
les dates de publication et de mise à jour ;
le type d’emploi ;
le salaire minimal et maximal, la devise et la période lorsqu’ils sont publiés ;
l’URL publique et le lien direct de candidature, avec une attribution UTM propre au partenaire.

Suspendre ou fermer un poste le retire du flux. Le rouvrir restaure le même identifiant stable. Une modification du contenu actualise l’entrée existante au lieu de créer un doublon.

API REST publique des offres

L’API publique des offres fournit du JSON sur HTTPS :

GET /api/public/v1/jobs
GET /api/public/v1/jobs/:public_token
POST /api/public/v1/jobs/:public_token/applications

La liste ne renvoie que les offres publiées. Le détail ajoute la description HTML nettoyée et le schéma du formulaire de candidature de l’employeur. Chaque employeur crée une paire de clés limitée à son tenant. Les intégrations serveur utilisent la clé secrète sk_…. Aucune des deux clés ne permet de lire les dossiers candidats.

La transmission native des candidatures fait l’objet d’un accord distinct, car le site doit préserver les questions obligatoires, les contraintes du CV, les mentions de consentement, la protection contre les robots et la véritable source du candidat. Si un site accepte déjà une URL d’ATS externe, rediriger les candidats vers Kit constitue souvent la première version la plus rapide et la plus propre.

Données structurées JobPosting

Chaque page publique d’offre contient du JSON-LD schema.org/JobPosting rendu côté serveur. Il comprend la description, les dates, l’employeur, le lieu ou les exigences de télétravail, le type d’emploi, le salaire lorsqu’il est présent, le statut de candidature directe et l’URL canonique.

Le JSON-LD facilite la découverte et la validation. Il ne remplace pas une API de publication convenue, un schéma de flux, un statut de modération ni un rappel de cycle de vie.

Webhooks signés du cycle de vie

Kit peut envoyer des webhooks signés lors de la publication, de la mise à jour, de la suspension, de la fermeture ou de la réouverture d’une offre. Chaque livraison comporte :

un identifiant d’événement stable pour l’idempotence ;
un horodatage et une signature HMAC ;
l’identifiant stable de l’offre et son état actuel ;
une logique de nouvelle tentative avec l’état visible dans Kit.

Si le partenaire fournit ses propres statuts ou rappels de modération, nous les mappons sur le cycle de vie de Kit. Ne déduisez jamais qu’une publication est acceptée du seul succès HTTP : certains sites reçoivent d’abord la charge utile puis la soumettent à une revue asynchrone.

Contrat de données de base

Kit dispose de ce noyau :

Champ	Remarques
Identifiant stable de l’offre	Le jeton public ne change pas après modification, suspension ou réouverture
Titre et description	Titre brut et description HTML nettoyée
Employeur	Nom du tenant ; logo et site provenant du profil de l’employeur
Service ou catégorie	Valeur saisie par l’employeur, mappée sur la taxonomie du site si nécessaire
Lieu et télétravail	Lieu en texte libre, ville, région et code pays structurés, indicateur de télétravail et pays où les candidats en télétravail peuvent être basés
Emploi	Type d’emploi ; les valeurs contractuelles propres au partenaire sont collectées au moment du mapping
Rémunération	Minimum, maximum, devise ISO et période heure/jour/mois/année lorsque publiés
Dates	Horodatages de publication et de dernière mise à jour ; les offres fermées quittent les flux actifs
URL	URL canonique et URL directe de candidature
Formulaire	Champs obligatoires, questions de présélection, mention de consentement et contraintes du CV

Les sites exigent souvent d’autres données contrôlées : niveau d’expérience, compétences, langues, identifiants de catégorie, lieux multiples, taxonomies de contrat, notices de confidentialité ou options payantes. Nous les mappons ou les recueillons à l’étape de revue de l’intégration, sans les réduire à une valeur générique imprécise.

Ce dont nous avons besoin

Envoyez la documentation et le processus que vous utilisez déjà. Certains éléments de cette liste peuvent ne pas s’appliquer :

Contacts techniques et commerciaux
Documentation de l’API, du flux ou de la multidiffusion avec des exemples de requête et de réponse
Identifiants de bac à sable ou compte de test sûr
Authentification, rotation des clés, portées, limites de débit et contraintes IP
Taxonomies de catégorie, lieu, expérience, compétence, contrat et salaire
Champs obligatoires et facultatifs avec leurs règles de validation
Comportement à la création, modification, publication, suspension, fermeture, réouverture et expiration
Idempotence, nouvelles tentatives, prévention des doublons et sémantique des erreurs
Statuts de modération avec interrogation ou rappel
Règles de candidature externe ou native, attribution de la source, confidentialité et conservation
Propriété des forfaits, consommation des crédits, choix de marque et crédits de test
Processus d’approbation, de certification et d’assistance en production

Tip

Un exemple fonctionnel vaut mieux qu’un nouveau document. Une collection Postman, un fichier OpenAPI, un exemple XML ou un guide d’intégration existant suffit pour commencer. Nous y adapterons Kit et ne documenterons que les décisions propres à la connexion.

Sécurité et données des candidats

Les flux publics et les listes d’offres contiennent des données sur les postes, jamais de PII des candidats.
Les identifiants sont limités au tenant ; les secrets serveur ne sont pas exposés au navigateur.
Les webhooks sont signés. Le destinataire doit vérifier la signature et l’âge de la requête pour rejeter les rejeux.
Les candidatures ne sont acceptées que par un point d’entrée convenu ou par la page Kit de l’employeur.
Nous ne créons aucune intégration partenaire en explorant des points de terminaison privés ou non documentés.

Lancer un partenariat

Écrivez à [email protected] avec votre guide d’intégration ou le nom de la personne qui en est responsable. Nous répondrons avec un mapping concis et le plus petit pilote utile aux deux équipes.

Checklist

Choisissez l’API par envoi, le flux tiré, la candidature externe ou native, ou une combinaison
Partagez le contrat existant du site et un chemin de bac à sable
Convenez du mapping des champs et taxonomies ainsi que du fonctionnement des crédits
Testez la création, la modification, la fermeture, les erreurs et la modération
Vérifiez l’attribution de la source et la confidentialité des candidats
Lancez un petit pilote payant, puis surveillez les statuts et les candidatures