La diffusion d’une offre d’emploi par connecteur API peut être utilisée pour une connexion à un jobboard ou un site carrière. Nous ne proposons pas d'endpoint pour une requête GET
Introduction
Contexte
Diffusion des offres d’emploi sur un jobboard par « API » ou similaire à un webhook : l’API est à créer sur le jobboard et sera appelée par Beetween.
Les offres d’emploi sont rédigées sur Beetween et diffusées sur le jobboard de destination grâce à un système de « connecteur » sur mesure intégré au système de multidiffusion d’offres d’emploi du logiciel Beetween.
Le connecteur décrit ici est un connecteur API, dans lequel Beetween envoie des requêtes REST HTTP vers le jobboard, suivant un format prédéfini, pour chaque opération de publication/mise hors-ligne d’une offre. Le jobboard doit donc développer une API qui respecte les spécifications de cette documentation.
Par rapport au fonctionnement par flux XML, ce système offre l’avantage d’une publication en quasi temps réel, ainsi qu’une meilleure remontée des informations au recruteur. Elle est également beaucoup moins demandeuse de ressources.
Elle demande en contrepartie un développement spécifique du côté du jobboard.
Pré-requis
La mise en place d’un connecteur diffusion API nécessite que le jobboard développe un point d’entrée API permettant d’alimenter les offres. Avant tout développement des spécificités du contenu des offres pour l’envoi par Beetween par API, la personne chargée des développements côté jobboard doit avoir pris connaissance de ce document.
Le jobboard doit intégrer un formulaire de candidature pour chaque offre d’emploi permettant aux candidats de postuler : une adresse mail spécifique sera associée à chaque offre d’emploi pour l’envoi des candidatures via ce formulaire (ou rediriger vers l’URL présente pour chaque offre dans fichier JSON).
Il est possible, si nécessaire, de pouvoir envoyer les candidatures par API également, solliciter votre contact Beetween privilégié si intérêt.
Le connecteur API
Principe général
Chaque offre d’emploi est identifiée par son ID public Beetween, qui est une suite de lettres ascii minuscules et de chiffres, d’une longueur comprise entre 10 et 20 caractères. Cet ID est généré automatiquement par Beetween lors de la mise en ligne d’une offre et ne peut être modifié. On le notera $ID dans la description des requêtes HTTP.
Les requêtes HTTP envoyées depuis Beetween vers le jobboard permettent la publication et la mise hors-ligne de l’offre. Les données seront formatées en JSON.
Lors de la publication d’une offre vers le site de destination, une requête HTTP POST, contenant les informations de l’offre d’emploi, est envoyée sur le ENDPOINT. L’appel pour la création ou la mise à jour est identique : c’est au site de destination de vérifier la présence de l’offre grâce à l’ID fourni en paramètre.
Lorsqu’une offre est retirée de la publication côté Beetween, une requête HTTP DELETE est envoyée, contenant l’ID de l’offre.
Requêtes HTTP
La racine du point d’entrée est définie par le jobboard, on utilisera par la suite l’écriture $ENDPOINT pour la désigner.
Par exemple :
ENDPOINT = https://point-d-entree-choisit-par-le-jobboard.fr/api/jobs
Un point d’entrée en HTTPS (et non pas HTTP simple) est fortement recommandé.
Ce point d’entrée doit être accessible à Beetween via Internet, sans configuration VPN ou autre.
Pour éviter les appels abusifs, voir le chapitre Authentification
Création ou mise à jour d'une offre d'emploi
Voici les champs présents dans le JSON :
Pour la mise à jour d’une offre, la requête est similaire à la mise en ligne d’une offre : il s’agit d’une requête POST avec un ID d’annonce existant.
Requête d’envoi (Beetween -> ENDPOINT jobboard)
Vous trouverez un exemple de requête API à cet endroit.
Concernant application_email, cette valeur est l’adresse mail de réception des candidatures. Par défaut, il s’agit d’une adresse générée par Beetween et propre à cette offre, permettant l’intégration des candidatures directement dans Beetween. Voir la partie Gestion des candidatures par email pour plus de détails, notamment le format des mails à envoyer pour une récupération optimale des informations du candidat.
Pour connaître le détails des valeurs possibles pour chaque champ, rendez-vous en annexe de cet article.
Requête de retour attendue (Jobboard -> ENDPOINT Beetween)
- Status 200 en cas de succès
- Tous les autres statuts seront interprétés comme un statut d’erreur
- Body :
{
url:"",
userMessage:"",
developerMessage:""
}
Explication des attributs du retour attendu :
- url (obligatoire) : il permet d’afficher dans Beetween l’URL de l’offre d’emploi sur le jobboard, afin que le recruteur puisse la consulter
- userMessage : message à l’intention de l’utilisateur (le recruteur), par exemple pour indiquer une cause d’échec (« Titre trop long »)
- developerMessage : similaire à userMessage mais à l’attention du support Beetween en charge de la surveillance des opérations de publication. Permet de donner une information plus technique que userMessage. Note : le support Beetween a également accès au userMessage.
Mise hors-ligne d'une offre
DELETE $ENDPOINT/$ID
ex: DELETE https://point-d-entree-choisit-par-le-jobboard.fr/api/jobs/a1b2v3d4e5f6
Retour attendu :
- aucun body
- en cas de succès : status 204 (200 également accepté)
- si l’offre n’était pas en ligne ou n’existait pas, l’opération est considérée comme un succès
- tous les autres statuts seront interprétés comme un échec de la dépublication
Un header Authorization: Basic xxxxx sera dans chaque requête, contenant un token fourni par le jobboard et lui servant à restreindre l’accès aux API de publication qu’il met en place. Cette contrainte n’est pas obligatoire mais est fortement recommandée pour éviter des abus potentiels.
Le token sera encodé en base64 UTF-8. La taille du token encodé en base64 ne doit pas dépasser 64 caractères.
Par exemple, si le token est login:password, le header d’authentification sera :
Authorization: Basic bG9naW46cGFzc3dvcmQ=
Il faudra bien utiliser le format login:password en s’assurant de ne pas utiliser le caractère « : » dans le login ou le password.
Nous avons également la possibilité de supporter un token Bearer qu’il faudra nous communiquer lors de la mise en place de l’API
Authorization: Bearer bG9naW46cGdsljksmkdFzc3dvcmQ=
Annexe
Description d'une offre
| Élément | Description | Type | Spécificité | Valeurs |
| id | Champ à 10 caractères alpha-numériques imposé par Beetween servant de référence et généré automatiquement | Text | Autogenerated | – |
| clientId | Identifiant du client sur le jobboard cible | Text | Optionnel | – |
| title | Titre de l’offre d’emploi | Text | Required | – |
| recruiter | Raison sociale de l’entreprise qui recrute | Text | Required | – |
| creationDate | Date de la première publication | Datetime | Autogenerated | – |
| LastModificationDate | Date de la dernière publication (modification, republication…) | Datetime | Autogenerated | – |
| applicationEmail | Adresse email à laquelle envoyer les candidatures | Text | Autogenerated | – |
| applicationUrl | Url d’une page de candidature Beetween pour l’annonce avec formulaire de candidature intégré | Text | Autogenerated | – |
| jobDescription | Inclut les balises de contenu de l’offre | – | – | – |
| ― company | Description de la société | HTML | Required | – |
| ― mission | Description des missions | HTML | Required | – |
| ― profile | Description du profil recherché | HTML | Required | – |
| location | Inclut les balises de localisation géographique du poste à pourvoir, générées à partir de l’adresse sélectionnée par l’utilisateur | – | – | – |
| ― display | Valeur affichable pour la localisation | Text | Required | – |
| ― city | Ville | Text | Required | – |
| ― post_code | Code postal | Text | Required | – |
| ― region2Code | Code du département | Text | Required | – |
| ― region2 | Nom du département | Text | Required | – |
| ― region1 | Nom de la région | Text | Required | – |
| ― countryCode | Code du pays | Text | Required | – |
| ― countryNameFr | Nom du pays en français | Text | Required | – |
| ― longitude | Coordonnées GPS : longitude | Number | Required | – |
| ― latitude | Coordonnées GPS : latitude | Number | Required | – |
| logoUrl | URL du logo lié à la raison sociale enregistrée et configuré dans Beetween | Text | Autogenerated | – |
| contract | Inclut les balises liées au contrat de travail proposé | – | – | – |
| ― type | Type de de contrat proposé, valeurs fixes proposées dans une liste déroulante | – | Required | Liste des valeurs |
| ― ― code | Code associé au type de contrat | Text | Required | – |
| ― ― displayValue | Valeur affichable pour le type de contrat | Text | Required | – |
| ― duration | Durée du contrat pour les contrats à durée déterminée | – | Required pour Stage, CDD et Intérim | Liste des valeurs |
| ― ― value | Valeur de la durée du contrat pour les contrats à durée déterminée | Number | Required pour Stage, CDD et Intérim | – |
| ― ― unit | Unité de la durée (Mois, semaines…) | Text | Required pour Stage, CDD et Intérim | – |
| ― ― displayValue | Concatenation des deux éléments précédents, valeur affichable | Text | Required pour Stage, CDD et Intérim | – |
| ― rhythm | Nombre d’heures par semaine sélectionné Contient des attributs hours_per_weekdisplay_value (type Text) |
– | – | Liste des valeurs |
| ― ― hoursPerWeek | Nombre d’heures travaillées par semaine | Number | Required | – |
| ― ― fullTime | Temps plein ou temps partiel (true ou false) | Text | Required | – |
| ― ― displayValue | Nombre d’heures par semaine | Text | Required | – |
| ― starting_date | Date de début de mission | – | – | Liste des valeurs |
| ― ― asap | Date de démarrage le plus tôt possible | Boolean | Required | true ou false |
| ― ― value | Date de début de mission | Date | Required si asap = « false » | – |
| job_language | Langue d’écriture de l’annonce (liste déroulante) | Text | – | Liste des valeurs |
| salary | Salaire proposé – 2 types d’affichages : salaire, et fourchette de salaire Contient des attributs value, currency, unit ; et pour l’affichage en fourchette min et max |
– | – | Liste des valeurs |
| ― min | Fourchette minimum du salaire | Number | – | – |
| ― max | Fourchette maximum du salaire | Number | – | – |
| ― value | Valeur fixe du salaire | Number | – | – |
| ― currency | Monnaie du salaire (EUR, USD …) | Text | Valeurs multiples | – |
| ― unit | Valeur temporelle du salaire (mensuel, annuel …) | Text | Valeurs multiples | – |
| ― displayValue | Concatenation des champs précédents | Text | Autogenerated | – |
| skills | Compétences nécessaires pour le poste (texte libre) | [ Text1, Text2,…] | – | – |
| jobTitle | Domaine d’activité correspondant au poste | – | – | Liste des valeurs |
| ― code | Code associé au domaine d’activité | Text | – | – |
| ― displayValue | Valeur affichable du domaine d’activité | Text | – | – |
| mainActivityArea | Secteur d’activité primaire | – | Required | Liste des valeurs |
| ― code | Code associé au secteur d’activité primaire | Text | Required | – |
| ― displayValue | Valeur affichable du secteur d’activité primaire | Text | Required | – |
| secondaryActivityArea | Secteur d’activité secondaire | – | – | Liste des valeurs |
| ― code | Code associé au secteur d’activité secondaire | Text | – | – |
| ― displayValue | Valeur affichable du secteur d’activité secondaire | Text | – | – |
| qualification | Niveau de qualification | – | – | Liste des valeurs |
| ― code | Code associé au niveau de qualification | Text | – | – |
| ― displayValue | Valeur affichable du niveau de qualification | Text | – | – |
| experience | Expérience requise : nombre d’années d’expérience requises et nombre d’années en management | – | Required | Détails |
| ― experienceYear | Nombre d’années d’experience requises | Text | – | – |
| ― includingManagementYears | Nombre d’années d’experience en management requises | Number | – | – |
| ― displayValue | Valeur affichable du niveau d’experience | Text | – | – |
| studyLevels | Niveau de qualification accepté un élément est ajoutée pour chaque niveau de qualification renseigné |
Tableau d’objet | Valeurs multiples | Liste des valeurs |
| ― code | Code correspondant au diplôme | Text | – | – |
| ― displayValue | Valeur affichable du niveau d’étude | Text | – | – |
| school_types | Type d’école, un élément est ajouté pour chaque type d’école renseigné | Tableau d’objet | Valeurs multiples | Liste des valeurs |
| ― code | Code associé au type d’école demandée | Text | – | – |
| ― displayValue | Valeur affichable du type d’école demandée | Text | – | – |
| educationDomain | Domaine d’études | Text | – | – |
Les valeurs possibles pour les balises <contract>/<type> sont indiquées dans le tableau ci-après. Il est préférable d’exploiter les valeurs “code” pour faire un mapping et ainsi éviter tout problème de mise à jour.
| Code | displayValue |
| PERMANENT | CDI |
| TEMPORARY | CDD |
| INTERIM | Intérim |
| INTERNSHIP | Stage |
| APPRENTICESHIP | Contrat d’apprentissage |
| CONTRAT_DE_PROFESIONNALISATION | Contrat de professionnalisation |
| FRANCHISE | Franchise |
| FREELANCE | Freelance |
| COLLABORATION_AGREEMENT | Contrat de collaboration |
| SUMMER_JOB | Job d’été |
| FAMILY | Emplois familiaux |
Les valeurs possibles pour l’element « unit » de l’objet duration du contrat sont indiquées dans le tableau suivant:
De la même manière, il est préférable d’exploiter les valeurs “unit” pour faire un mapping et ainsi éviter tout problème de mise à jour.
| Attribut Unit | Valeur (en français) |
| YEAR | an(s) |
| MONTH | mois |
| WEEK | semaine(s) |
| DAY | jour(s) |
| HOUR | heure(s) |
L’objet rhythm (rhythm et non rythm) contient 3 éléments : « hoursPerWeek » qui contient le nombre d’heures travaillées par semaine, fullTime qui contient « true » ou « false » et displayValue qui contient le nombre d’heure travaillées sous la forme xx.xh/semaine.
Exemple:
"rhythm": {
"hoursPerWeek": "35.0",
"fullTime": "true",
"displayValue": "35.0h/semaine"
},
L’objet startingDate indique la date de début de contrat. Quand une date est choisie pour le début du contrat, l’element asap="false" et la valeur dans l’element « value » est égale à la date saisie par l’utilisateur.
Si l’utilisateur choisi « dès que possible », l’attribut asap="true" et la date dans « value » correspond à la date de publication de l’annonce.
Language
JobLanguage peut prendre deux valeurs : « Anglais » ou « Français ».
L’objet salary peut se présenter de 2 manières différentes (fourchette ou valeur fixe) en fonction des choix de l’utilisateur :
Valeur fixe :
"salary": {
"value": "100000.0",
"currency": "EUR",
"unit": "YEAR",
"displayValue": "100000 € (Euros) par an"
}
Fourchette :
"salary": {
"min": "100000.0",
"max": "150000.0",
"currency": "EUR",
"unit": "YEAR",
"displayValue": "De 100000 à 150000 € (Euros) par an"
}
Les valeurs possibles pour les elements « unit » et « currency » sont indiquées dans les tableau ci-après :
| Unit | Valeur (en français) |
| YEAR | par an |
| MONTH | par mois |
| WEEK | par semaine |
| DAY | par jour |
| HOUR | par heure |
| Currency | Valeur (en français) |
| EUR | € (Euros) |
| GBP | £ (Livre britannique) |
| MAD | DH (Dirham marocain) |
| USD | $ (Dollar américain) |
| CAD | $ (Dollar canadien) |
| JPY | ¥ (Yen japonais) |
| CHF | CHF (Franc suisse) |
Job title
| code | displayValue |
| Craft / Worker | Artisan / Ouvrier |
| Craft / Shop | Artisan / Commerce de proximité |
| Worker | Ouvrier / BTP |
| Technician | Technicien |
| Hospitality / Travel | Hôtellerie / Restauration / Tourisme / Loisirs |
| Sales | Commerce / Vente |
| MLM Commission | VDI |
| Computer | Informatique / Internet / Télécom |
| Marketing / Communication | Marketing / Communication |
| House help | Services à domicile |
| Cleaning / Help | Ménage / Entretien |
| Nurse / Babysitting / School help | Services à la personne |
| Management | Direction / Encadrement |
| Entity management | Direction générale / Responsable d’un centre de profit |
| Project management | Gestion de projet |
| Engineering | Études / Recherches / Ingénieries |
| HR / Formation / Teaching | RH / Formation / Enseignement |
| HR | Ressources Humaines / Formation |
| Formation / Teaching | Éducation / Enseignement |
| Health Care | Santé / Médecine / Social |
| Multi services | Services généraux |
| Administration | Administration |
| Assistant | Assistanat / Secrétariat / Accueil |
| Accounting / Finance | Comptabilité / Gestion / Finance |
| Legal / Tax | Juridique / Fiscal |
| Security / Help | Sécurité / Défense / Gardiennage |
| Logistic | Transport / Logistique / Achat |
Activity area
| code | displayValue |
| Bank | Banque |
| Finance | Finance |
| Assurance | Assurance |
| Accounting | Comptabilité |
| Gestion | Gestion |
| Legal | Juridique |
| Tax | Fiscal |
| Agriculture | Agriculture / Pêche |
| Agri | Agroalimentaire |
| Building | BTP & second œuvre |
| Building / infrastucture | BTP Usines / Routes / Canalisation |
| Installation / Maintenance / Repair | Installation / Maintenance / Réparation |
| Architecture | Architecture |
| Design | Design |
| Town planning | Urbanisme |
| Real estate | Immobilier |
| Craft | Commerce / Artisanat |
| Retail | Commerce de détail / Vente |
| Distribution | Grande distribution |
| Export | Commerce international / Export |
| Customer service | Service client / après-vente |
| Call center | Centre d’appel |
| Hostelry | Hôtellerie |
| Food | Restauration |
| Tourism | Tourisme |
| Hobbies | Loisirs |
| Sport | Sport |
| Equipment manufacturer | Automobile / Aéronautique / Transport |
| Metallurgy | Métallurgie |
| Mechanical / Robotics | Mécanique / Automatisme / Robotique |
| Materials processing | Transformation des matériaux |
| Electrical and electronic equipment | Equipements électriques et électroniques |
| Quality | Qualité / Inspection |
| High technologies | Hautes technologies |
| Raw materials | Extraction et transformation de matières premières |
| Chemicals | Chimie – Caoutchouc – Plastique |
| Pharmaceutical | Industrie pharmaceutique / Biotechnologie |
| Manufacturing / Production | Industrie / Production, autres (meubles, textiles, imprimerie) |
| Health | Santé |
| Social | Social |
| Veterinary | Vétérinaire |
| Web | Sites Web / SEO / Webdesign |
| Software | Développement logiciel |
| Telecom | Télécommunications |
| E-business | E-business |
| IT Services | Société de Services en Ingénierie Informatique |
| ConsultingProject management | ConsultingProject management |
| Cleaning | Ménage / entretien en entreprise |
| Other company services | Autres services aux entreprises |
| Individual services | Services à la personne |
| Public service | Service public / Administrations |
| Fashion | Mode |
| Luxury | Luxe |
| Beauty | Beauté |
| Transport | Transport |
| Logistic | Logistique |
| Handling | Manutention |
| HR | RH |
| Recruitment firm | Cabinet de recrutement |
| Interim firm | Cabinet d’intérim |
| Marketing | Marketing |
| Communication | Communication / Médias / Presse |
| Advertising | Publicité |
| Journalism | Journalisme |
| Edition | Édition et Écriture |
| Engineering | Ingénierie |
| RnD | R&D / Haute technologie |
| Consultancy | Bureau d’études |
| Private research | Recherche privée |
| Public research | Recherche publique |
| Security | Sécurité / Défense |
| Art | Art / Spectacle / Culture |
| Teaching | Teaching |
| Public teaching | Enseignement public |
| Private teaching | Enseignement privé |
| Formation | Formation professionnelle |
| Apprenticeship Formation | Formation en alternance |
| Water | Eau |
| Electricity | Électricité |
| Oil and gas | Pétrole / Gaz |
| Nuclear | Nucléaire |
| Environment | Environnement / Nature |
| Waste | Gestion des déchets |
| Humanitarian | Humanitaire |
Qualification
| Code | displayValue |
| MANOEUVRE | Manoeuvre |
| OUVRIER_SPECIALISE | Ouvrier spécialisé |
| P1_P2 | Ouvrier qualifié (P1,P2) |
| P3_P4_OHQ | Ouvrier qualifié (P3,P4,OHQ) |
| ENQ | Employé non qualifié |
| EQ | Employé qualifié |
| TECHNICIEN | Technicien |
| AGENT_DE_MAITRISE | Agent de maîtrise |
| CADRE_PRIVE | Cadre du secteur privé |
| CADRE_PUBLIC | Cadre du secteur public / Armées |
Experience
L’objet experience contient 3 éléments :
- experienceYear : contient le nombre d’années d’expérience nécessaires.
- includingManagementYears : nombre d’années d’expériences requises en tant que manager.
- displayValue, valeurs affichable.
Exemple :
"experience": {
"experienceYear": "-2",
"includingManagementYears": "10.0",
"displayValue": "Tous niveaux d'expérience"
},
| experienceYear | displayValue |
| <0 | Tous niveaux d'expérience |
| 0.0 | Débutant |
| <6 | Expérimenté |
| >=6 | Chef de projet |
Study levels
| Code | displayValue |
| ALL | Aucun |
| BEP_CAP | BEP/CAP |
| BAC | Bac |
| BAC_1_2 | Bac+1/Bac+2 |
| BAC_3 | Bac+3 |
| BAC_4 | Bac+4 |
| BAC_5 | Bac+5 |
| BAC_6_PLUS | Bac+6 et plus |
Exemple :
"studyLevels": [
{
"code": "BEP_CAP",
"displayValue": "BEP/CAP"
},
{
"code": "BAC",
"displayValue": "Bac"
}
]
School Types
| Code | displayValue |
| ALL | Peu importe |
| UNI | Université |
| RESEARCH_LAB | Laboratoire de recherche |
| BUSINESS_SCHOOL | Grande école de commerce |
| ENGINEER_SCHOOL | École d’ingénieur |
| A | A |
| A_PLUS | A+ |
Exemple :
"schoolTypes": [
{
"code": "UNI",
"displayValue": "Université"
},
{
"code": "ENGINEER_SCHOOL",
"displayValue": "École d'ingénieur"
}
]