Heyalink Développeurs API Formation
API Formation
Vos formations, publiées et tenues à jour depuis votre site ou votre catalogue.
Démarrage rapide
-
Créez une clé
Sur l’écran API Formation de votre page pro, une clé d’essai vérifie tout et ne publie rien.
Se connecter pour créer une clé -
Vérifiez qu’elle répond
Un appel à /moi rend votre page pro et les droits de la clé.
GET /moi -
Publiez une formation
Envoyez-la d’abord à blanc, avec le paramètre dry_run : Heyalink répond sans rien écrire.
Voir l’exemple
Connectez-vous avec un compte qui gère une page pro pour essayer les exemples ici même, dans le bac à sable.
En bref
L'API Formation de Heyalink publie les formations de votre page entreprise depuis votre site ou votre catalogue. Vous gardez la main chez vous : une formation créée, modifiée ou retirée chez vous l'est aussi sur Heyalink.
Elle est comprise dans les formules Pro Formation et Grands comptes de votre page. Elle a sa sœur, l'API Emploi, pour les offres d'emploi : ce sont deux API distinctes, avec chacune ses clés. Une clé de l'API Formation ne fait rien sur les offres d'emploi.
Pendant le lancement : les abonnements ouvriront avec les paiements, à venir. D'ici là, pour essayer l'API ou publier pour de bon, écrivez-nous à info-contact@heyalink.com : nous ouvrons l'accès page par page.
Trois façons de vous brancher, à combiner si besoin :
- votre catalogue, sans aucun développement : donnez l'adresse de votre catalogue au format LHEO (celui des Carif-Oref) ou JSON, Heyalink le relit et tient vos formations à jour ;
- votre catalogue envoyé tel quel : votre logiciel pousse le fichier LHEO à Heyalink en un appel ;
- l'API : votre logiciel envoie chaque formation à Heyalink, en JSON ; ou votre agent d'IA, par le serveur MCP.
Vos formations restent toujours à jour sans geste de votre part : une formation ajoutée, modifiée, retirée ou complète chez vous l'est aussi sur Heyalink. Une formation publiée ainsi est une formation de votre page comme les autres : sur le site, dans les applications, dans la rubrique Formation.
Se brancher en cinq minutes
- Sur Heyalink, ouvrez la rubrique Formation, onglet Mes formations, puis Connecter mes formations automatiquement (ou depuis la page de l’entreprise, onglet Services). L'écran API Formation s'ouvre ; choisissez la page si vous en gérez plusieurs.
- Créez une clé : donnez-lui un nom (« Site du centre », « Logiciel de gestion »), cochez ce qu'elle peut faire (lire les formations, les publier), acceptez les conditions. La clé ne s'affiche qu'une fois : copiez-la dans le coffre de votre logiciel. Pour vos essais, cochez « Clé d'essai » : elle vérifie tout et ne publie rien.
- Vérifiez qu'elle marche :
- Prouvez que vous possédez le domaine de votre site (voir « Prouver votre domaine ») : sans lui, seule la clé d'essai publie. Puis publiez votre première formation (exemples plus bas).
- Suivez le résultat dans le journal de l'écran API Formation, ou par
GET /journal.
curl https://heyalink.com/api/formation/v1/moi \
-H "Authorization: Bearer hl_formation_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/moi", {
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/moi');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/formation/v1/moi",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
La clé
- Elle commence par
hl_formation_live_et compte 66 caractères. Ce préfixe lisible permet aux outils de détection de secrets (GitHub, GitGuardian) de la repérer si elle est oubliée dans un dépôt. - Elle va dans l'en-tête de chaque appel :
Authorization: Bearer hl_formation_live_VOTRECLE. Jamais dans une adresse, un dépôt de code ou une page web publique. - Elle appartient à une page et à cette API seule : elle ne lit ni ne touche les formations d'une autre page, et une clé de l'API Emploi reçoit 403 ici (comme celle-ci sur l'API Emploi).
- Elle ne marche que tant que la page a la formule Pro Formation ou Grands comptes : sans elle, chaque appel répond 403.
- Elle ne fait que ce que ses droits permettent :
formations:lecture,formations:ecriture(publier permet aussi de lire). - Facultatif, à sa création : une durée de vie (30 jours, 90 jours, 1 an) et une liste
d'adresses IP autorisées (par exemple
203.0.113.0/24) ; un appel venu d'ailleurs répond 403. - Une page peut avoir jusqu'à dix clés actives sur l'API Formation : une par logiciel, pour pouvoir en couper une sans toucher les autres. Révoquer une clé la coupe aussitôt.
- Remplacer une clé (rotation) en crée une nouvelle aux mêmes réglages, durée de vie comprise ; l'ancienne marche encore 7 jours, le temps de la changer dans votre logiciel, sans coupure. Si la clé a fuité, choisissez le remplacement d'urgence : l'ancienne est coupée tout de suite, avec ses jetons OAuth.
- Une clé d'essai (
hl_formation_test_) a sa propre limite d'appels, plus basse que celle d'une vraie clé (GET /moila donne).
Le bac à sable
Une clé d'essai commence par hl_formation_test_. Elle donne exactement les mêmes
réponses, validations et erreurs qu'une vraie clé, mais ses formations vivent à part : elles ne
sont jamais publiées ni vues des membres. Vous pouvez les créer, les lister, les modifier, les
archiver et les supprimer comme de vraies formations ; elles sont effacées 7 jours après leur
dernière modification. Chaque réponse porte "bac_a_sable": true et l'en-tête
Heyalink-Bac-A-Sable: oui. Vos webhooks de test sont prévenus aussi, avec
"bac_a_sable": true dans donnees. Branchez votre logiciel avec elle, puis passez à une clé
hl_formation_live_.
Le journal de test (GET /journal avec la clé d'essai, ou l'écran API Formation) garde
chaque appel avec sa requête et sa réponse complètes, secrets masqués.
La validation à blanc
Avec une vraie clé, ajoutez ?dry_run=1 à n'importe quelle écriture (ou l'en-tête
Heyalink-Simulation: 1) : tout est vérifié (clé, droits, champs, référence) et la réponse est
celle d'une vraie écriture, avec "simulation": true. Rien n'est écrit.
Essayer sans rien installer
- « Essayer » dans cette documentation, connecté à Heyalink : chaque exemple part avec un jeton du bac à sable de votre page.
- Données d'exemple valides telles quelles : formations.json, catalogue-lheo.xml.
- Collections prêtes à importer, tirées de la spécification OpenAPI de l'API Formation :
Postman,
Bruno. Mettez votre clé
d'essai dans la variable
cle. - Tester ma source (écran API Formation) : ce que Heyalink importerait de votre catalogue, champ par champ, avec les erreurs, sans rien publier.
OAuth 2.0
Si votre logiciel préfère OAuth, échangez la clé contre un jeton d'une heure (octroi
« client credentials », RFC 6749) : client_id est l'identifiant client de la clé (hlc_…,
affiché sur l'écran API Formation), client_secret la clé elle-même. scope restreint les
droits du jeton (facultatif), pris parmi formations:lecture et formations:ecriture.
Le jeton s'emploie ensuite comme une clé : Authorization: Bearer hl_at_…. Il ne vaut que pour
l'API Formation, et tombe avec la clé (révocation, expiration).
Les anciennes clés
Les clés créées avant le 21 octobre 2026 (hle_…, hl_live_…, hl_test_…) marchent jusqu'à
leur remplacement depuis l'écran API Formation. Leur API se déduit de leurs droits : avec
formations:…, elles ouvrent l'API Formation ; leur remplacement donne une clé de l'API
Formation seule. L'ancienne adresse commune /api/entreprises/v1 reste servie pour elles ; le
cloisonnement des deux API y vaut aussi. Passez à https://heyalink.com/api/formation/v1 à votre rythme.
curl -X PUT "https://heyalink.com/api/formation/v1/formations/CACES-R482-B1?dry_run=1" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite des pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1"
}'
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/CACES-R482-B1?dry_run=1", {
method: "PUT",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite des pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/CACES-R482-B1?dry_run=1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite des pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1"
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.put(
"https://heyalink.com/api/formation/v1/formations/CACES-R482-B1?dry_run=1",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite des pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1",
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/formation/v1/oauth/token" \
-u "hlc_VOTREIDENTIFIANT:hl_formation_live_VOTRECLE" \
-d grant_type=client_credentials \
-d scope="formations:ecriture"
const reponse = await fetch("https://heyalink.com/api/formation/v1/oauth/token", {
method: "POST",
headers: {
"Authorization": "Basic " + btoa("hlc_VOTREIDENTIFIANT:hl_formation_live_VOTRECLE"),
},
body: new URLSearchParams({
"grant_type": "client_credentials",
"scope": "formations:ecriture"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/oauth/token');
curl_setopt_array($ch, [
CURLOPT_USERPWD => 'hlc_VOTREIDENTIFIANT:hl_formation_live_VOTRECLE',
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'client_credentials',
'scope' => 'formations:ecriture',
]),
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/formation/v1/oauth/token",
auth=("hlc_VOTREIDENTIFIANT", "hl_formation_live_VOTRECLE"),
data={
"grant_type": "client_credentials",
"scope": "formations:ecriture",
},
)
print(reponse.status_code, reponse.text)
{
"access_token": "hl_at_…",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "formations:ecriture"
}
Prouver votre domaine
Une publication pour de bon (et sa validation à blanc) demande que votre page ait prouvé qu'elle possède le domaine de son site. Un SIRET vérifié dit que l'organisme existe, pas que c'est bien lui qui publie : la preuve de domaine protège vos stagiaires contre une page qui usurperait votre nom. Le bac à sable, lui, reste ouvert sans preuve. Les domaines prouvés sont ceux de la page : ils valent pour l'API Formation comme pour l'API Emploi.
- Déclarez le domaine :
POST /domainesavec{"domaine": "votre-site.fr"}, ou sur l'écran API Formation. La réponse donne un jeton propre au domaine. - Posez-le sur votre site, au choix : la balise
<meta name="heyalink-verification" content="JETON">dans la page d'accueil, ou un fichierhttps://votre-site.fr/.well-known/heyalink.txtqui contient le jeton. - Vérifiez :
POST /domaines/votre-site.fr/verification.domaine.prouvepasse àtrue.
Le domaine prouvé vaut aussi pour ses sous-domaines (formations.votre-site.fr). Le lien de vos
formations (lien) doit mener à un domaine prouvé de votre page : sinon la formation est refusée
en 422, sur le champ. Un catalogue déjà prouvé comme source vaut preuve de son domaine. La preuve
est revue chaque semaine : retirée de votre site, elle ne compte plus. Il n'y a pas d'autre voie :
pas de validation à la main. GET /domaines liste vos domaines, DELETE /domaines/votre-site.fr
en retire un.
Adresse et format
| Adresse de base | https://heyalink.com/api/formation/v1 |
| Format | JSON en UTF-8 (Content-Type: application/json), réponses en JSON ; LHEO en XML pour /formations/lheo |
| Description complète | OpenAPI 3.1 : https://heyalink.com/api/formation/v1/openapi.json, à importer dans Postman, Insomnia ou un générateur de client |
| Limite | 300 appels par minute et par clé, annoncés sur chaque réponse |
Limite d'appels. Chaque réponse porte les en-têtes RateLimit-Policy et RateLimit
(appels restants, secondes avant la remise à zéro). Au-delà, la réponse est 429 avec
Retry-After : attendez ce nombre de secondes, ou regroupez vos formations avec /lot.
Rejouer sans risque. Ajoutez Idempotency-Key: <un identifiant unique> à une écriture :
rejouée avec la même valeur dans les 24 heures (après une coupure réseau, par exemple), elle rend
la même réponse sans rien refaire, avec Idempotent-Replayed: true. La même valeur pour une autre
requête répond 422.
Lire sans retélécharger. Chaque lecture porte un ETag ; renvoyez-le en If-None-Match :
si rien n'a changé, la réponse est 304, sans corps.
Langue. Les messages sont en français ; envoyez Accept-Language: en pour les avoir en
anglais.
État de l'API. GET https://heyalink.com/api/formation/v1/sante, public et sans clé, donne l'état et la version :
Chaque formation est désignée par votre référence (le code de la formation chez vous) :
lettres, chiffres, -, _, . et :, 191 caractères au plus. C'est elle qui rend les appels
sûrs à rejouer : envoyer deux fois la même référence modifie la formation, ne la double jamais.
curl https://heyalink.com/api/formation/v1/sante
const reponse = await fetch("https://heyalink.com/api/formation/v1/sante");
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/sante');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get("https://heyalink.com/api/formation/v1/sante")
print(reponse.status_code, reponse.text)
Les formations
| Appel | Effet |
|---|---|
PUT /formations/{reference} |
crée la formation (201) ou la modifie (200) |
GET /formations/{reference} |
la formation et son état |
GET /formations?limite=100&curseur=… |
vos formations, de la plus récente à la plus ancienne, 100 au plus par page ; suivant donne le curseur de la page d'après (vide à la dernière) |
POST /formations/{reference}/pourvue |
la session est complète : la formation sort du site, archivée « pourvue » |
POST /formations/{reference}/fermer |
les inscriptions sont closes : la formation sort du site et de votre limite, ceux qui ont fait une demande sont prévenus ; état fermee (depuis la v1.11.0) |
POST /formations/{reference}/rouvrir |
une formation fermée revient en ligne, dans la limite de votre formule (403 sinon) |
GET /formations/{reference}/apercu |
la fiche telle qu'un membre la voit sur Heyalink (fiche), son état et le nombre de demandes (reponses) |
POST /formations/{reference}/pieces |
joindre des photos (photos, 6 au plus, JPEG, PNG, WebP ou HEIC, 10 Mo chacune ; la première est le visuel de l'annonce et de son partage) et des PDF (documents, 6 au plus, 20 Mo chacun), chacun {nom, donnees} en base64 (depuis la v1.12.0) |
PUT /formations/{reference}/pieces/ordre |
ranger les photos : ordre, les identifiants dans l'ordre voulu |
DELETE /formations/{reference}/pieces/{piece} |
retirer une photo ou un PDF (le fichier est effacé) |
POST /formations/{reference}/archivage |
la formation sort du site, archivée ; un PUT la ramène |
DELETE /formations/{reference} |
la retire (204, même si elle n'existait pas) |
POST /formations/lot |
jusqu'à 100 formations et 100 retraits en un appel |
POST /formations/synchronisation |
la liste complète de vos références en ligne : tout ce qui manque est archivé |
POST /formations/lheo |
votre catalogue LHEO, tel quel |
| Champ | Obligatoire | Contenu |
|---|---|---|
titre |
oui | l'intitulé, 200 caractères au plus |
presentation |
oui | le contenu de la formation, 15 000 caractères au plus ; HTML gardé en texte |
lien |
oui | l'adresse https:// de la fiche ou de l'inscription chez vous |
organisme |
non | l'organisme ; absent, le nom de votre page |
mode |
non | presentiel, distanciel ou mixte |
lieu |
non | la ville |
code_postal |
non | 5 chiffres |
duree_heures |
non | la durée en heures, un nombre entier |
debut |
non | la date de la prochaine session, AAAA-MM-JJ |
pour_qui |
non | le public visé |
niveau_d_entree |
non | le niveau demandé |
prerequis |
non | les prérequis |
objectifs |
non | les objectifs, 255 caractères au plus |
infos_pratiques |
non | prix, financement, horaires, 500 caractères au plus |
metier |
non | le métier visé, en texte (Conducteur d’engins de chantier) |
metier_code |
non | le code d'un métier du référentiel de Heyalink ; inconnu, la formation est refusée (422) |
famille_code |
non | le code d'une des 39 familles de métiers ; sans lui, la famille du métier |
code_rome |
non | le code ROME du métier visé (F1302) |
financements |
non | une liste prise dans cpf, opco, france_travail, region, employeur, sans doublon |
type_certification |
non | diplome (diplôme ou titre), habilitation (habilitation, CACES ou certificat) ou attestation |
code_rncp |
non | le code RNCP de France Compétences (RNCP34567) |
code_rs |
non | le code du Répertoire spécifique (RS5080) |
alternance |
non | une liste prise dans apprentissage, professionnalisation |
niveau_entree |
non | le niveau demandé, codé : aucun, cap, bac, bac2, bac3, bac5, bac8 (le texte libre niveau_d_entree reste) |
prix |
non | le prix total TTC par stagiaire, en euros ; toujours TTC, la fiche l'affiche « 1 500 € TTC » |
certification |
non | l'intitulé de la certification préparée (CAP Couvreur, CACES® R482 catégorie B1), 190 caractères au plus |
diplome |
non | le sigle du diplôme d'État préparé : CAP, BP, BTS, Bac pro, BUT… |
niveau_certification |
non | le niveau européen de la certification, de 1 à 8, avec un code_rncp seulement |
attestation |
non | true si la formation se termine par une attestation de fin de formation |
photo_url |
non | l'adresse https:// d'une photo de la formation : JPEG, PNG, GIF ou WebP, 5 Mo au plus |
photo_base64 |
non | la même photo en base64, à la place de photo_url |
Les champs à partir de metier (v1.6.0) sont facultatifs et suivent des listes fermées : une
valeur hors liste est refusée en 422, avec un exemple valide. Ils servent les filtres de
Formation : une formation sans la donnée sort du filtre correspondant (financement,
certification, alternance, niveau). « cpf » sans code RNCP ni RS est accepté, avec un
signalement incoherence.
La fiche de la formation (v1.8.0) se remplit avec ces champs, comme une formation saisie à la
main sur Heyalink. En tête, la carte « Ce que vous obtenez » : certification, le code
(code_rncp ou code_rs), le niveau sur 8 pour un RNCP (celui du répertoire national passe
devant niveau_certification) et la nature du titre (« Diplôme national » avec un diplome
d'État, « Certification » pour un code RS ; un code que le répertoire national ne connaît pas est
affiché comme déclaré par l'organisme). Sans certification, la carte devient « Ce que vous saurez
faire » et montre vos objectifs, puis la durée, puis l'attestation si attestation est vrai.
Sans l'un ni l'autre, pas de carte. La famille de métier est calculée par Heyalink (le titre
d'abord, puis famille_code) et rendue en lecture dans famille. La photo est facultative :
Heyalink la lit à l'adresse donnée (adresse publique seulement), la vérifie et la remet au propre
(2 000 px de large au plus). Illisible, la formation est refusée (422, champ photo_url). Une
photo absente de la requête reste ; photo_url envoyé à null la retire. Une nouvelle photo passe
ensuite par la vérification des images de Heyalink, comme une photo de profil : tant qu'elle est
vérifiée, photo rend la précédente ; refusée, elle n'est jamais publiée. Le prix (prix) est
toujours TTC : la fiche l'affiche « 1 500 € TTC ».
La réponse dit aussi ce qui s'est passé, dans resultat : creee, modifiee, restauree
(revenue en ligne), inchangee (rien n'a changé, rien n'est réécrit) ou doublon (le même
contenu est déjà en ligne sous une autre référence : rien n'est créé). Une formation peut
attendre avant de paraître (Grands comptes) : au plafond de facture du mois, ou sur une facture
impayée quatorze jours après son échéance, elle est enregistrée mais reste hors ligne. etat vaut
alors en_attente et attente dit pourquoi (motif : plafond ou impaye), depuis quand, et
parait_au_plus_tard_le. Le webhook annonce.en_attente vous prévient, puis annonce.publiee
quand elle paraît. Pour toute autre formation, attente vaut null. Les avertissements ne
bloquent jamais : ils disent ce qui manque pour bien ranger la formation (un lieu sans
département, par exemple).
Les signalements (signalements, depuis la v1.6.0) ne bloquent jamais non plus : code
champ_ignore (un champ que l'API ne connaît pas, ni publié ni refusé), champ_recommande_absent
(un champ qui manque, et la formation sortira du filtre qu'il remplit), valeur_deduite
(l'algorithme de Heyalink l'a déduit à votre place ; origine dit d'où : metier, code_rome,
titre, code_rncp, code_rs…) ou incoherence. Une valeur déduite est listée dans
champs_deduits, jamais présentée comme la vôtre.
Dans un catalogue LHEO (2.3), ces données se lisent sans saisie : domaine-formation/code-ROME,
organisme-financeur/code-financeur (2 Conseil régional, 4 France Travail, 5 Entreprise, 16
OPCO), certification/code-RNCP et code-RS, code-CPF (éligible au CPF), certifiante,
code-niveau-entree, prix-total-TTC et l'alternance des sessions
(session/cycle/alternance/type-alternance).
Relire une formation, et la liste de vos formations :
La session est complète : la formation sort du site, archivée « pourvue ».
Votre catalogue LHEO s'envoie aussi tel quel, en corps de requête (5 Mo au plus). Avec
?synchronisation=complete, les formations absentes du catalogue sont archivées.
Une formation masquée par la modération de Heyalink ne se republie pas (422) et ne se retire pas par l'API : écrivez à l'équipe si vous pensez à une erreur.
Supprimée ou fermée sur Heyalink (depuis la v1.11.0)
Un gérant de votre page peut fermer ou supprimer la formation sur Heyalink.
- Supprimée : elle ne revient jamais. Renvoyer la même référence (
PUT, envoi par lot) répond409,codeannonce_supprimee, avec la date (supprimee_le) et ce texte : « Cette annonce a été supprimée sur heyalink le … par un gérant de la page. Pour la republier, utilisez une nouvelle référence. » Un flux (page carrières, logiciel) la saute et le note dans son bilan (supprimees_sur_le_site) et dans le journal. - Fermée : renvoyée, elle se met à jour mais reste fermée (état
fermee) ; seul un gérant la rouvre, ou vous parPOST /formations/{reference}/rouvrir.
curl -X PUT "https://heyalink.com/api/formation/v1/formations/CACES-R482-B1" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite en sécurité des pelles hydrauliques de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1",
"mode": "presentiel",
"lieu": "Blagnac",
"code_postal": "31700",
"duree_heures": 21,
"debut": "2026-11-16"
}'
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/CACES-R482-B1", {
method: "PUT",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite en sécurité des pelles hydrauliques de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1",
"mode": "presentiel",
"lieu": "Blagnac",
"code_postal": "31700",
"duree_heures": 21,
"debut": "2026-11-16"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/CACES-R482-B1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite en sécurité des pelles hydrauliques de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1",
"mode": "presentiel",
"lieu": "Blagnac",
"code_postal": "31700",
"duree_heures": 21,
"debut": "2026-11-16"
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.put(
"https://heyalink.com/api/formation/v1/formations/CACES-R482-B1",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"titre": "CACES R482 catégorie B1",
"presentation": "Conduite en sécurité des pelles hydrauliques de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1",
"mode": "presentiel",
"lieu": "Blagnac",
"code_postal": "31700",
"duree_heures": 21,
"debut": "2026-11-16",
},
)
print(reponse.status_code, reponse.text)
{
"formation": {
"reference": "CACES-R482-B1",
"titre": "CACES R482 catégorie B1",
"mode": "presentiel",
"lieu": "Blagnac",
"etat": "en_ligne",
"adresse": "https://heyalink.com/formations/caces-r482-categorie-b1-8",
"source": "api"
},
"avertissements": [],
"success": true
}
curl "https://heyalink.com/api/formation/v1/formations/CACES-R482-B1" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/CACES-R482-B1", {
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/CACES-R482-B1');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/formation/v1/formations/CACES-R482-B1",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl "https://heyalink.com/api/formation/v1/formations?limite=100" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations?limite=100", {
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations?limite=100');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/formation/v1/formations?limite=100",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/formation/v1/formations/CACES-R482-B1/pourvue" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/CACES-R482-B1/pourvue", {
method: "POST",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/CACES-R482-B1/pourvue');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/formation/v1/formations/CACES-R482-B1/pourvue",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/formation/v1/formations/lheo?synchronisation=complete" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE" \
-H "Content-Type: application/xml" \
--data-binary @catalogue-lheo.xml
import { readFile } from "node:fs/promises";
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/lheo?synchronisation=complete", {
method: "POST",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/xml",
},
body: await readFile("catalogue-lheo.xml"),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/lheo?synchronisation=complete');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
'Content-Type: application/xml',
],
CURLOPT_POSTFIELDS => file_get_contents('catalogue-lheo.xml'),
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/formation/v1/formations/lheo?synchronisation=complete",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/xml",
},
data=open("catalogue-lheo.xml", "rb"),
)
print(reponse.status_code, reponse.text)
Envoyer par lot
Pour synchroniser un catalogue entier, envoyez jusqu'à 100 formations et 100 retraits par appel. Chaque formation a sa propre réponse : une formation refusée n'empêche pas les autres.
La réponse donne un bilan (créées, modifiées, retirées, refusées) et, pour chaque formation,
son statut (201, 200 ou 422) avec le message d'erreur s'il y en a un.
La liste complète. POST /formations/synchronisation reçoit toutes vos références en ligne :
chaque formation de l'API qui n'y est pas est archivée. Une liste vide n'archive rien, sauf avec
"confirmer_liste_vide": true : une erreur d'envoi ne vide pas votre page.
curl -X POST "https://heyalink.com/api/formation/v1/formations/lot" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"formations": [
{
"reference": "CACES-R482-B1",
"titre": "CACES R482 catégorie B1",
"presentation": "Pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1"
},
{
"reference": "SST-2026-01",
"titre": "Sauveteur secouriste du travail",
"presentation": "Deux jours pour savoir porter secours.",
"lien": "https://www.votre-organisme.fr/formations/sst"
}
],
"retirer": ["HAB-2025-099"]
}'
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/lot", {
method: "POST",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"formations": [
{
"reference": "CACES-R482-B1",
"titre": "CACES R482 catégorie B1",
"presentation": "Pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1"
},
{
"reference": "SST-2026-01",
"titre": "Sauveteur secouriste du travail",
"presentation": "Deux jours pour savoir porter secours.",
"lien": "https://www.votre-organisme.fr/formations/sst"
}
],
"retirer": [
"HAB-2025-099"
]
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/lot');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"formations": [
{
"reference": "CACES-R482-B1",
"titre": "CACES R482 catégorie B1",
"presentation": "Pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1"
},
{
"reference": "SST-2026-01",
"titre": "Sauveteur secouriste du travail",
"presentation": "Deux jours pour savoir porter secours.",
"lien": "https://www.votre-organisme.fr/formations/sst"
}
],
"retirer": [
"HAB-2025-099"
]
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/formation/v1/formations/lot",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"formations": [
{
"reference": "CACES-R482-B1",
"titre": "CACES R482 catégorie B1",
"presentation": "Pelles de moins de 6 tonnes.",
"lien": "https://www.votre-organisme.fr/formations/caces-r482-b1",
},
{
"reference": "SST-2026-01",
"titre": "Sauveteur secouriste du travail",
"presentation": "Deux jours pour savoir porter secours.",
"lien": "https://www.votre-organisme.fr/formations/sst",
},
],
"retirer": [
"HAB-2025-099",
],
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/formation/v1/formations/synchronisation" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{"references": ["CACES-R482-B1", "SST-2026-01"]}'
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/synchronisation", {
method: "POST",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"references": [
"CACES-R482-B1",
"SST-2026-01"
]
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/synchronisation');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"references": [
"CACES-R482-B1",
"SST-2026-01"
]
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/formation/v1/formations/synchronisation",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"references": [
"CACES-R482-B1",
"SST-2026-01",
],
},
)
print(reponse.status_code, reponse.text)
Sans développement : votre catalogue
Sur l'écran API Formation, collez l'adresse https:// de votre catalogue : au format LHEO
(celui des Carif-Oref) ou en JSON (une liste de formations, ou un objet
{"formations": […]}, avec les champs de la table plus haut). Heyalink le relit et tient vos
formations à jour.
D'abord, prouvez que la source est la vôtre. Pour que personne ne publie vos formations à votre place, Heyalink ne lit une source qu'une fois prouvé qu'elle vous appartient. L'écran API Formation vous donne un jeton propre à la source, à poser d'une de ces façons, puis cliquez « Vérifier » :
- sur votre site, une balise dans l'en-tête de votre page d'accueil :
<meta name="heyalink-verification" content="VOTRE-JETON">; - ou un fichier texte
https://votre-site/.well-known/heyalink.txtqui contient le jeton.
Si vous ne pouvez pas poser le jeton, branchez-vous par l'API (plus haut) : POST /formations/lheo
envoie le même catalogue avec votre clé.
Laissez le jeton en place : Heyalink le revérifie chaque semaine. S'il disparaît, la source n'est plus lue et vous êtes prévenu par courriel.
Chaque lecture compare tout : une formation nouvelle est créée, une formation modifiée mise à jour, une formation disparue de votre catalogue archivée (jamais effacée : si elle revient, elle revient avec son adresse).
Prudence en cas de panne : une lecture en erreur ne retire rien ; un catalogue qui ne rend soudain plus aucune formation n'est vidé qu'au passage suivant, s'il est toujours vide. Au bout de trois erreurs de suite, ou dès qu'il se vide, vous êtes prévenu par courriel.
Fraîcheur : Heyalink relit votre catalogue toutes les 10 minutes au plus vite, plus rarement
s'il ne change pas (jusqu'à 6 heures), en requêtes conditionnelles (ETag, Last-Modified)
pour ne télécharger que ce qui change, et s'annonce comme HeyalinkBot. « Synchroniser
maintenant » se demande une fois toutes les cinq minutes au plus.
Tout de suite, si vous voulez : appelez l'adresse de mise à jour immédiate de votre
source (écran API Formation, « Mise à jour immédiate ») à chaque changement, Heyalink relit
votre catalogue dans la minute. Si votre catalogue annonce un hub WebSub, Heyalink s'y abonne
seul, avec un secret propre au hub (signatures sha1, sha256, sha384 ou sha512
acceptées).
curl -X POST "https://heyalink.com/api/formation/v1/sources/12/relire/VOTRE-SIGNATURE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/sources/12/relire/VOTRE-SIGNATURE", {
method: "POST",
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/sources/12/relire/VOTRE-SIGNATURE');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post("https://heyalink.com/api/formation/v1/sources/12/relire/VOTRE-SIGNATURE")
print(reponse.status_code, reponse.text)
Les webhooks
Plutôt que d'interroger Heyalink, faites-vous prévenir. Sur l'écran API Formation, ajoutez une
adresse https:// de votre site (cinq au plus) et choisissez ses événements. Une adresse de
l'API Formation n'est prévenue que des formations : elle n'apprend rien des offres d'emploi.
| Événement | Quand |
|---|---|
annonce.publiee |
la formation est en ligne (créée, revenue d'une archive, ou sortie d'attente) |
annonce.en_attente |
la formation est enregistrée mais attend hors ligne : plafond de facture atteint ou facture impayée (Grands comptes) |
annonce.refusee |
la modération de Heyalink l'a masquée |
annonce.expiree |
sa source (flux, page carrières) la dit échue ; une formation envoyée par l'API n'expire plus |
annonce.archivee |
elle est archivée |
annonce.pourvue |
elle est marquée complète |
annonce.fermee |
un gérant l'a fermée (sur Heyalink ou par …/fermer) ; elle se rouvre |
annonce.rouverte |
une annonce fermée est de nouveau en ligne |
annonce.supprimee |
un gérant l'a supprimée sur Heyalink, définitivement |
annonce.piece_refusee |
la modération a refusé une photo ou un PDF de l'annonce ; donnees.piece porte id, type (photo ou document) et nom |
ping |
l'essai envoyé depuis l'écran API Formation |
Une adresse peut être une adresse de test : elle ne reçoit que les événements de vos
formations de test (clé hl_formation_test_), et une vraie adresse que ceux de vos vraies
formations, jamais les uns chez les autres. Un événement de test porte "bac_a_sable": true dans
son corps signé et l'en-tête Heyalink-Bac-A-Sable: oui. Si l'une de vos adresses accumule trop
de livraisons en attente (panne de votre côté), les nouvelles ne sont plus préparées jusqu'à ce
qu'elle réponde.
Heyalink envoie un POST en JSON :
Vérifiez la signature avant de croire un appel. L'en-tête
Heyalink-Signature: t=<horodatage>,v1=<signature> porte un HMAC-SHA256, calculé avec le secret
de l'adresse (affiché une seule fois à sa création) sur <horodatage>.<corps brut>. Refusez un
horodatage de plus de cinq minutes : un appel rejoué plus tard sera refusé.
Répondez par un statut 2xx dans les 10 secondes. Sinon, Heyalink réessaie après 1, 5, 30
minutes, puis 2 h, 6 h et 24 h ; Heyalink-Livraison identifie la livraison, pour ne pas traiter
deux fois la même. Une adresse en échec 20 fois de suite est désactivée.
{
"id": "evt_2d7k9m1q4x0a7b6c5f3e",
"evenement": "annonce.publiee",
"cree_le": "2026-10-21T09:14:03+02:00",
"bac_a_sable": false,
"donnees": {
"nature": "formation",
"reference": "CACES-R482-B1",
"titre": "CACES R482 catégorie B1",
"motif": null,
"adresse": "https://heyalink.com/formations/caces-r482-categorie-b1-8"
}
}
[$t, $v1] = sscanf($_SERVER['HTTP_HEYALINK_SIGNATURE'], 't=%d,v1=%s');
$corps = file_get_contents('php://input');
$attendu = hash_hmac('sha256', $t.'.'.$corps, getenv('HEYALINK_SECRET'));
if (! hash_equals($attendu, (string) $v1) || abs(time() - $t) > 300) {
http_response_code(400);
exit;
}
// corpsBrut : le corps reçu, tel quel (avant tout JSON.parse).
const [, t, v1] = req.get('Heyalink-Signature').match(/t=(\d+),v1=([a-f0-9]+)/);
const attendu = crypto.createHmac('sha256', process.env.HEYALINK_SECRET)
.update(`${t}.${corpsBrut}`)
.digest('hex');
const valide = attendu.length === v1.length
&& crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1))
&& Math.abs(Date.now() / 1000 - Number(t)) <= 300;
# entete : l'en-tête Heyalink-Signature ; corps_brut : le corps reçu, en octets.
t, v1 = (partie.split('=', 1)[1] for partie in entete.split(','))
attendu = hmac.new(os.environ['HEYALINK_SECRET'].encode(),
t.encode() + b'.' + corps_brut, hashlib.sha256).hexdigest()
valide = hmac.compare_digest(attendu, v1) and abs(time.time() - int(t)) <= 300
Le serveur MCP (agents d'IA)
Un agent d'IA (Claude, ChatGPT, ou votre propre agent) peut publier et tenir à jour vos
formations par le Model Context Protocol : POST https://heyalink.com/api/formation/v1/mcp, transport « Streamable
HTTP », avec la même clé et les mêmes droits que l'API (Authorization: Bearer hl_formation_live_…). Une clé d'essai ne publie rien.
Outils, ceux de l'API Formation seulement : formations_lister, formation_publier,
formation_archiver, formation_pourvue, formation_supprimer.
{
"mcpServers": {
"heyalink-formation": {
"type": "http",
"url": "https://heyalink.com/api/formation/v1/mcp",
"headers": { "Authorization": "Bearer hl_formation_live_VOTRECLE" }
}
}
}
Les erreurs
Une erreur répond au format standard RFC 9457 (application/problem+json), avec un message
en français lisible tel quel :
violations dit, pour chaque champ refusé, la règle qui a échoué et une valeur valide : de quoi
corriger sans chercher.
| Code | Signification | Que faire |
|---|---|---|
| 200, 201 | modifiée, créée | rien |
| 204 | retirée | rien |
| 304 | rien n'a changé depuis votre ETag |
garder ce que vous avez |
| 400 | requête mal formée (Idempotency-Key trop longue, catalogue LHEO illisible, par exemple) |
lire detail |
| 401 | clé absente, inconnue, révoquée ou expirée | vérifier l'en-tête, recréer une clé |
| 403 | clé de l'API Emploi, page sans Pro Formation ni Grands comptes, droit manquant, adresse IP non autorisée, ou domaine pas encore prouvé | lire detail |
| 404 | référence inconnue (lecture seulement) | vérifier la référence |
| 409 | la même Idempotency-Key est encore en cours |
attendre sa réponse |
| 413 | catalogue LHEO de plus de 5 Mo | l'envoyer en plusieurs fois |
| 422 | formation refusée : champ manquant ou trop long, lien bloqué ou hors de vos domaines, formation masquée par la modération, ou Idempotency-Key déjà prise |
lire errors, champ par champ |
| 429 | trop d'appels | attendre Retry-After secondes, ou passer par /lot |
Erreur 400
La requête est mal formée : lisez detail, il dit quoi corriger.
Erreur 401
La clé est absente, mal copiée, révoquée ou expirée. Vérifiez l'en-tête
Authorization: Bearer hl_formation_live_… ; au besoin, créez une nouvelle clé sur l'écran API
Formation.
Erreur 403
detail dit laquelle de ces raisons s'applique : la clé appartient à l'API Emploi (elle n'ouvre
pas l'API Formation) ; la page n'a ni Pro Formation ni Grands comptes, ou ne les a plus ; la clé n'a pas le droit
demandé (par exemple formations:ecriture) ; l'appel vient d'une adresse IP que la clé
n'autorise pas ; ou la page n'a pas encore prouvé son domaine (publication pour de bon).
Erreur 404
La référence n'existe pas pour votre page. Vérifiez-la ; un PUT la crée.
Erreur 409
Une requête avec la même Idempotency-Key est encore en cours : attendez sa réponse avant de
rejouer.
Erreur 413
Le catalogue LHEO envoyé pèse plus de 5 Mo : envoyez-le en plusieurs fois, ou passez par /lot.
Erreur 422
La formation est refusée : errors donne le message champ par champ. Corrigez puis renvoyez.
Erreur 429
Trop d'appels pour cette clé. Attendez le nombre de secondes donné par Retry-After, ou
regroupez vos formations avec /lot (100 par appel).
Une formation masquée par la modération de Heyalink le reste : la republier répond 422, et son
etat vaut masquee_par_la_moderation.
{
"type": "https://heyalink.com/developpeurs/api/formation#erreur-422",
"title": "Annonce refusée",
"status": 422,
"detail": "Le champ lien est obligatoire.",
"instance": "/api/formation/v1/formations/CACES-R482-B1",
"errors": { "lien": ["Le champ lien est obligatoire."] },
"violations": [
{
"champ": "lien",
"regle": "required",
"message": "Le champ lien est obligatoire.",
"exemple": "https://www.votre-organisme.fr/formations/caces-r482-b1"
}
]
}
Le journal
GET /journal rend les 100 derniers appels et lectures de catalogue de l'API Formation, avec
leur statut et leur message : une clé ne lit que le journal de son API. Il se lit avec une clé
qui a le droit formations:ecriture. Le même journal se lit sur l'écran API Formation. Il est
gardé 90 jours ; le journal de test (requêtes et réponses des clés d'essai, secrets masqués)
l'est 7 jours.
Retirer une formation se rejoue sans risque : la réponse est 204, même si elle était déjà retirée.
curl "https://heyalink.com/api/formation/v1/journal" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/journal", {
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/journal');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/formation/v1/journal",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl -X DELETE "https://heyalink.com/api/formation/v1/formations/SST-2026-01" \
-H "Authorization: Bearer hl_formation_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/formation/v1/formations/SST-2026-01", {
method: "DELETE",
headers: {
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/formation/v1/formations/SST-2026-01');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_formation_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.delete(
"https://heyalink.com/api/formation/v1/formations/SST-2026-01",
headers={
"Authorization": "Bearer hl_formation_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
Versions et journal des changements
L'API Formation est en v1 (https://heyalink.com/api/formation/v1). Ce contrat est stable : la v1 n'évolue que de façon
compatible (un champ ou un appel de plus, jamais un champ retiré ni un sens changé). Une rupture
passerait en v2, à une autre adresse, annoncée à l'avance. La description complète, à jour, est
la spécification OpenAPI (https://heyalink.com/api/formation/v1/openapi.json), qui fait foi.
| Version | Date | Changements |
|---|---|---|
| 1.13.0 | 08/11/2026 | Rien ne change pour l'API Formation : la version est commune aux deux API (l'API Emploi publie désormais les demandes de sous-traitance) |
| 1.12.0 | 07/11/2026 | Changement compatible (rien de retiré ni de renommé). Photos et PDF de l'annonce : media[] dans la lecture (id, type, nom, url, taille, ordre, statut : verification, publiee ou refusee), POST …/pieces, PUT …/pieces/ordre, DELETE …/pieces/{piece}, et le webhook annonce.piece_refusee. Chaque pièce est lue par la modération avant d'être montrée aux membres. Une annonce importée n'en porte pas |
| 1.11.0 | 07/11/2026 | Changement compatible (rien de retiré ni de renommé). Fermer et rouvrir : POST /formations/{reference}/fermer et …/rouvrir ; l'aperçu tel qu'un membre le voit : GET /formations/{reference}/apercu. Deux états de plus (fermee, retiree) et trois webhooks (annonce.fermee, annonce.rouverte, annonce.supprimee). Une annonce supprimée sur Heyalink par un gérant ne revient jamais : la même référence répond 409 annonce_supprimee ; une annonce fermée renvoyée reste fermée. Les services de la page, bloc par bloc : GET /services, POST /services (un brouillon), GET /services/{id}, PATCH /services/{id}/blocs/{bloc} (seuls les champs du bloc changent ; photos et PDF en multipart), GET /services/{id}/apercu, POST /services/{id}/publication, POST /services/{id}/fermeture, POST /services/{id}/reouverture, DELETE /services/{id}. La lecture suit le droit de lecture de la clé, l'écriture son droit d'écriture. Les trois mêmes webhooks disent aussi le geste de la page sur un service (nature service, référence : l'identifiant du service), et annonce.publiee sa publication |
| 1.10.0 | 07/11/2026 | Aucun changement de champ pour l’API Formation : le numéro suit celui de l’API Emploi (plus de date de fin des offres). Précision : annonce.expiree ne vise que les formations reprises d’une source |
| 1.9.0 | 07/11/2026 | Aucun changement de l’API Formation : le numéro suit celui de l’API Emploi (la fiche de l’offre), qui partage la spécification. Précision de documentation : prix est toujours le prix total TTC par stagiaire, et la fiche l'affiche « 1 500 € TTC ». La photo reçue (photo_url, photo_base64) passe par la vérification des images de Heyalink avant d'être publiée : tant qu'elle est vérifiée, photo rend la précédente ; refusée, elle n'est jamais publiée. Aucun champ ajouté ni retiré |
| 1.8.0 | 06/11/2026 | La fiche Formation : champs facultatifs certification, diplome, niveau_certification, attestation, photo_url et photo_base64 (photo vérifiée et recopiée par Heyalink, 422 si illisible) ; dans la réponse, famille (calculée par Heyalink), certification, diplome, niveau_certification, attestation, photo ; la famille non reçue suit d'abord le titre (origine titre dans champs_deduits) ; une formation publiée par l'API s'affiche comme une formation saisie à la main ; changement compatible : aucun champ retiré, aucun champ renommé, aucun sens changé |
| 1.7.0 | 30/10/2026 | Documentation seule : elle dit la règle d'accès en vigueur depuis le 25/10/2026 : l'API Formation est comprise dans les formules Pro Formation et Grands comptes ; l'API elle-même ne change pas |
| 1.7.0 | 29/10/2026 | Dans la réponse, secteur_de_recherche : le secteur (un des dix) sous lequel la formation se trouve dans les filtres de recherche de Heyalink, lu depuis la famille; l’origine formacode peut paraître dans champs_deduits (le métier d’une formation déduit de son Formacode) ; aucun champ retiré, aucun sens changé |
| 1.6.0 | 28/10/2026 | Données riches, toutes facultatives : metier, metier_code, famille_code, code_rome, financements, type_certification, code_rncp, code_rs, alternance, niveau_entree, prix (listes fermées, 422 hors liste) ; dans la réponse, ces champs plus secteur et champs_deduits ; bloc signalements (champs ignorés, champs recommandés absents, valeurs déduites, incohérences) dans chaque publication et chaque résultat d'un lot ; ces données sont lues aussi dans les catalogues LHEO 2.3 et les flux JSON ; aucun champ retiré, aucun sens changé |
| 1.5.0 | 26/10/2026 | État en_attente et champ attente (motif plafond ou impaye, date de parution au plus tard) pour les annonces d'un Grand compte retenues par le plafond de facture ou un impayé ; webhook annonce.en_attente ; une formation en attente se relit par sa référence et figure dans la liste |
| 1.4.0 | 21/10/2026 | Deux API distinctes, l'API Formation (/api/formation/v1) et l'API Emploi (/api/emploi/v1), chacune avec ses clés (hl_formation_live_, hl_formation_test_), sa spécification, ses collections, ses webhooks, son journal et ses outils MCP ; une clé de l'autre API reçoit 403 ; cle.api dans GET /moi ; l'ancienne adresse /api/entreprises/v1 et les anciennes clés restent servies jusqu'à leur remplacement |
| 1.3.0 | 19/10/2026 | Domaines prouvés (/domaines) : exigés pour publier pour de bon, et les liens des annonces doivent y mener ; adresses de webhook de test, champ bac_a_sable et en-tête Heyalink-Bac-A-Sable ; la validation à blanc vaut aussi pour le serveur MCP ; remplacement d'urgence d'une clé ; limite d'appels propre aux clés d'essai ; le journal demande un droit de publication ; le secret OAuth ne passe plus dans l'adresse |
| 1.2.0 | 19/10/2026 | Bac à sable complet (annonces de test listables, effacées après 7 jours), validation à blanc (dry_run), violations dans les erreurs, messages en anglais (Accept-Language), route sante, journal de test, données d'exemple, collections Postman et Bruno, « Tester ma source » |
| 1.1.0 | 19/10/2026 | Clés hl_live_ et hl_test_, droits fins, durée de vie, adresses IP, rotation, OAuth 2.0, Idempotency-Key, en-têtes RateLimit, erreurs RFC 9457, curseur, ETag, webhooks signés, OpenAPI 3.1, serveur MCP, preuve de propriété des sources |
| 1.0.0 | 19/10/2026 | Offres d'emploi et formations par référence, lot, synchronisation, LHEO, sources lues sans développement |