Skip to content

Heyalink Developers Training API

Training API

Your trainings, published and kept up to date from your website or your catalogue.

Quick start

  1. Create a key

    On the Training API screen of your page, a test key checks everything and publishes nothing.

    Log in to create a key
  2. Check that it answers

    A call to /moi returns your page and the key’s permissions.

    GET /moi
  3. Publish a training

    Send it first as a dry run, with the dry_run parameter: Heyalink answers without writing anything.

    See the example

Log in with an account that manages a business page to try the examples right here, in the sandbox.

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

  1. 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.
  2. 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.
  3. Vérifiez qu'elle marche :
  1. 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).
  2. Suivez le résultat dans le journal de l'écran API Formation, ou par GET /journal.
Request
curl https://heyalink.com/api/formation/v1/moi \
  -H "Authorization: Bearer hl_formation_live_VOTRECLE"

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 /moi la 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.

Request
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"
      }'
Request
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"
Response JSON
{
  "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.

  1. Déclarez le domaine : POST /domaines avec {"domaine": "votre-site.fr"}, ou sur l'écran API Formation. La réponse donne un jeton propre au domaine.
  2. Posez-le sur votre site, au choix : la balise <meta name="heyalink-verification" content="JETON"> dans la page d'accueil, ou un fichier https://votre-site.fr/.well-known/heyalink.txt qui contient le jeton.
  3. Vérifiez : POST /domaines/votre-site.fr/verification. domaine.prouve passe à 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.

Request
curl https://heyalink.com/api/formation/v1/sante

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.

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épond 409, code annonce_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 par POST /formations/{reference}/rouvrir.
Request
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"
      }'
Response JSON
{
  "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
}
Request
curl "https://heyalink.com/api/formation/v1/formations/CACES-R482-B1" \
  -H "Authorization: Bearer hl_formation_live_VOTRECLE"
Request
curl "https://heyalink.com/api/formation/v1/formations?limite=100" \
  -H "Authorization: Bearer hl_formation_live_VOTRECLE"
Request
curl -X POST "https://heyalink.com/api/formation/v1/formations/CACES-R482-B1/pourvue" \
  -H "Authorization: Bearer hl_formation_live_VOTRECLE"
Request
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

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.

Request
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"]
      }'
Request
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"]}'

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.txt qui 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).

Request
curl -X POST "https://heyalink.com/api/formation/v1/sources/12/relire/VOTRE-SIGNATURE"

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.

JSON JSON
{
  "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"
  }
}
Code
[$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;
}

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.

JSON JSON
{
  "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.

JSON JSON
{
  "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.

Request
curl "https://heyalink.com/api/formation/v1/journal" \
  -H "Authorization: Bearer hl_formation_live_VOTRECLE"
Request
curl -X DELETE "https://heyalink.com/api/formation/v1/formations/SST-2026-01" \
  -H "Authorization: Bearer hl_formation_live_VOTRECLE"

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

Your cookie choices

With your consent, Heyalink measures site traffic with Google Analytics, and counts views of sponsored ads to bill their advertisers. Nothing is set before you choose, and declining changes nothing about how you use the site. Your choice is kept for six months; you can change it at any time with "Manage cookies" at the bottom of the page. Find out more

Customise

Nothing is set before you choose, and declining changes nothing about how you use the site. Your choice is kept for six months; you can change it at any time with "Manage cookies" at the bottom of the page. Find out more

Choose category by category