API SIRH : connecter ATS, paie et onboarding

API SIRH : l'architecture fiable en une réponse

Pour connecter un ATS, la paie et l'onboarding avec une API SIRH, ne synchronisez pas toutes les données dans tous les sens. Désignez d'abord le système qui fait autorité pour chaque objet, créez un modèle d'échange minimal, puis faites passer les événements par une couche d'intégration. Cette couche vérifie les droits et les données, conserve les correspondances d'identifiants, rend les écritures idempotentes, met les demandes en file et rapproche régulièrement les systèmes.

Le chemin nominal d'une embauche peut se lire ainsi : l'ATS publie « candidat recruté » ; l'orchestrateur vérifie que la décision et les champs obligatoires sont complets ; le SIRH cœur crée ou active le dossier salarié et renvoie son identifiant stable ; la paie reçoit uniquement les données nécessaires à son périmètre ; le système d'identité prépare le compte et les accès ; l'outil d'onboarding suit les tâches. Une validation RH reste placée avant les écritures irréversibles ou sensibles.

Ce schéma reste volontairement neutre. Une API visible dans la documentation d'un éditeur n'est pas forcément activée dans votre formule, votre région ou votre instance. Par exemple, la documentation officielle de Personio distingue plusieurs versions d'API, signale des conditions de souscription pour les intégrations personnalisées et renvoie vers son Developer Hub pour la liste actuelle des webhooks. L'audit doit donc tester les droits réels, pas seulement lire une page marketing. Si vous devez aussi composer avec un ancien logiciel, consultez notre guide pour automatiser un processus RH sans API.

Définir les systèmes de référence et le modèle de données

La première décision d'une intégration ATS–SIRH–paie n'est pas technique : qui possède quelle information ? Une règle comme « le SIRH est la source de vérité » reste trop vague. L'ATS peut être autoritatif pour l'identifiant de candidature et le poste accepté, le SIRH pour l'identifiant salarié et la date contractuelle validée, la paie pour le résultat calculé, et l'annuaire pour le nom de connexion finalement attribué.

Formalisez cette propriété champ par champ. Définissez aussi qui peut corriger une valeur et dans quel sens la correction circule. Une donnée ne devrait avoir qu'un propriétaire à un instant donné. Un retour ciblé peut rester utile : l'annuaire peut, par exemple, renvoyer l'adresse professionnelle générée vers le SIRH. La documentation Microsoft sur le provisioning piloté par les RH décrit précisément cette logique de système source, système cible, mapping d'attributs et retour d'identifiants.

Le contrat de mapping minimal

Conservez le brut reçu uniquement le temps justifié pour diagnostiquer, puis travaillez sur un modèle canonique réduit. Documentez type, caractère obligatoire, format, liste de valeurs, propriétaire, transformation, comportement si la valeur est vide et date d'effet. Les API normalisées n'éliminent pas ce travail : la référence SAP SuccessFactors OData explique qu'OData fournit un protocole et des métadonnées uniformes ; les objets et règles métier restent néanmoins ceux du produit et de sa configuration.

Webhooks, polling et idempotence : rendre le flux rejouable

Un webhook réduit le délai entre un changement et son traitement, mais ne doit pas être confondu avec une garantie de livraison exactement une fois. Le récepteur doit pouvoir recevoir un doublon, un événement ancien ou deux événements dans un ordre inattendu. Il accuse réception rapidement après validation minimale, place le travail en file, puis traite hors de la requête HTTP. Lorsque le payload ne contient qu'une référence, l'intégration relit l'objet à jour via l'API SIRH avant de décider.

Les possibilités diffèrent selon les éditeurs. La documentation Lucca des endpoints de webhook expose notamment des sujets d'événements, une version d'API et des états actif, suspendu ou inactif ; sa ressource de livraisons permet de consulter statut et tentatives. Ces éléments illustrent ce qu'il faut vérifier chez chaque fournisseur, sans présumer que le même mécanisme existe ailleurs ni qu'il est activé sur votre tenant.

La boucle de fiabilité à mettre en place

1. Identifier l'événement : stocker son identifiant fournisseur s'il existe ; sinon calculer une clé stable à partir de la source, de l'objet, de la version et de l'action.
2. Dédupliquer : si la clé a déjà produit le résultat attendu, répondre sans répéter l'écriture.
3. Valider l'état : contrôler la transition métier et, si nécessaire, relire la ressource canonique plutôt que croire aveuglément un événement ancien.
4. Écrire de manière idempotente : utiliser une fonction d'upsert documentée ou chercher la correspondance avant création ; transmettre une clé d'idempotence si l'API cible la prend officiellement en charge.
5. Reprendre : retenter les erreurs transitoires avec attente croissante et aléatoire, respecter l'indication Retry-After lorsqu'elle est fournie, et isoler les échecs permanents dans une file à examiner.
6. Rapprocher : interroger périodiquement les modifications depuis un curseur connu, avec une petite fenêtre de recouvrement, puis comparer les états attendus aux cibles.

Ne rejouez pas indifféremment toutes les erreurs. Une indisponibilité, un dépassement temporaire de débit ou certains timeouts peuvent justifier une nouvelle tentative. Une donnée obligatoire absente ou une habilitation refusée réclame plutôt une correction ou une intervention. Dans tous les cas, conservez le nombre d'essais, le dernier code d'erreur, le prochain essai, la clé de corrélation et la personne ou équipe responsable de la reprise.

Enfin, n'essayez pas de simuler une transaction distribuée entre quatre SaaS. Si la fiche SIRH est créée mais que la paie refuse l'écriture, conservez l'état intermédiaire, bloquez les étapes dépendantes et rendez la reprise possible. Une suppression automatique pour « revenir en arrière » pourrait détruire une donnée désormais valide.

Authentification, habilitations et sécurité des données RH

Chaque connexion doit utiliser une identité technique dédiée à l'intégration, jamais le compte personnel d'un administrateur. Choisissez le mécanisme documenté par l'éditeur — par exemple OAuth 2.0 client credentials, certificat ou clé dédiée — et limitez les scopes aux objets, sociétés et opérations nécessaires. Séparez lecture et écriture lorsque le produit le permet, ainsi que test et production. Les secrets vivent dans un coffre, sont masqués dans les logs, font l'objet d'une rotation préparée et peuvent être révoqués sans arrêter les autres intégrations.

La fiche de la CNIL consacrée à la sécurité des API recommande notamment d'identifier les rôles, de minimiser les données partagées, de séparer les fonctions d'administration, de sécuriser les clés, de maintenir la documentation, de chiffrer les communications et de journaliser les échanges. Pour une API SIRH, cela implique concrètement de ne pas envoyer à l'outil d'onboarding un salaire, un numéro de sécurité sociale ou des coordonnées bancaires s'il n'en a aucune utilité.

Les logs doivent répondre à « quel objet, quelle action, quelle source, quel résultat et quand ? » sans recopier par défaut le dossier salarié. Utilisez identifiants techniques, empreintes et codes d'erreur ; protégez les journaux contre la modification et réservez leur accès. Le guide ANSSI sur l'architecture d'un système de journalisation rappelle leur double fonction : détection en temps utile et investigation a posteriori.

Environnements, tests et monitoring avant la production

Une intégration qui réussit une création heureuse n'est pas prête. Demandez un environnement de test à chaque éditeur et vérifiez qu'il reproduit les objets, permissions et versions utiles. La CNIL recommande une version bac à sable de l'API et l'emploi de données fictives. Si un fournisseur ne propose pas de sandbox, utilisez un tenant de test lorsque le contrat le permet, des fixtures synthétiques et un simulateur des réponses API ; n'importez pas spontanément une copie de la base RH de production.

Les tests qui évitent les incidents d'onboarding

• --Contrat : schémas, types, pagination, champs absents, valeurs inconnues et compatibilité de version.
• --Mapping : accents, noms composés, homonymes, manager non créé, multi-contrat, réembauche, changement d'entité et date future.
• --Idempotence : même webhook envoyé plusieurs fois, timeout après une écriture réussie et reprise après arrêt de l'orchestrateur.
• --Erreurs : authentification expirée, débit limité, réponse invalide, cible indisponible et champ obligatoire refusé.
• --Sécurité : secret absent des traces, webhook invalide rejeté, scopes insuffisants par défaut et accès aux files restreint.
• --Bout en bout : embauche, modification avant arrivée, annulation, report, réembauche et départ, avec validation de chaque système cible.

Déployez d'abord sur un périmètre maîtrisé : une entité, un type de contrat et un petit groupe de dossiers supervisés. Préparez le retour arrière au niveau de la configuration — désactiver un consommateur, revenir à une version de mapping ou router vers une file manuelle — sans supprimer automatiquement les salariés déjà créés.

Le tableau de bord minimal

Suivez au minimum le volume reçu et traité, le délai entre événement et état cible, le taux d'échec par connecteur, les nouvelles tentatives, la profondeur de file, les messages en quarantaine et les écarts issus du rapprochement. Ajoutez des alertes sur l'expiration des secrets, la suspension d'un webhook, une hausse durable des erreurs ou l'absence anormale d'événements. Fixez vos seuils à partir du processus réel et de ses horaires critiques plutôt que de copier un objectif générique.

Le dossier d'exploitation doit indiquer qui reçoit l'alerte, comment diagnostiquer, quelle action est sûre, comment rejouer un dossier et quand prévenir les RH ou le DPO. Cette exigence a sa place dès le cahier des charges de l'automatisation RH, pas après le premier incident.

Cas concret : relier le recrutement à l'onboarding sans doublon

Prenons un scénario volontairement simple : un candidat accepte une offre, son dossier doit être préparé dans le SIRH, la paie et l'annuaire, puis les tâches d'accueil doivent démarrer. Le déclencheur technique n'est pas seulement un changement d'étape dans l'ATS. La règle métier exige aussi une offre validée, une date d'embauche, une entité juridique, un poste et l'approbation attendue dans l'entreprise.

1. Recevoir et immobiliser l'événement : enregistrer sa clé, son heure et l'identifiant de candidature, puis accuser réception sans lancer toute la chaîne dans la requête webhook.
2. Relire et valider : récupérer le dossier autorisé dans l'ATS, contrôler les champs obligatoires et demander une validation si le contrat ou l'entité ne sont pas confirmés.
3. Résoudre l'identité : rechercher une correspondance stable pour éviter le doublon d'une réembauche ; créer sinon la personne canonique et sa relation d'emploi.
4. Créer dans le SIRH cœur : écrire uniquement les champs dont il devient propriétaire, puis conserver l'identifiant salarié renvoyé avant toute étape suivante.
5. Alimenter la paie : transmettre les seules données nécessaires quand le statut métier l'autorise ; mettre les rejets de validation en attente sans dupliquer la fiche SIRH.
6. Provisionner l'identité : utiliser les données autoritatives du SIRH et les dates d'effet. Le modèle Joiner–Mover–Leaver évite de piloter durablement les accès depuis l'ATS.
7. Lancer l'onboarding : créer les tâches pour RH, manager et IT, avec leurs échéances, sans copier les données de paie dans l'outil de tâches.
8. Rapprocher : vérifier que les identifiants cibles existent, que les états attendus sont atteints et que toute exception possède un responsable.

Microsoft documente ce principe de provisioning depuis un système RH autoritatif vers l'annuaire, ainsi que les cycles Joiner–Mover–Leaver. Ses Lifecycle Workflows couvrent ensuite des tâches liées à l'arrivée, aux changements et au départ. Il s'agit d'un exemple vérifié, pas d'une obligation d'architecture : un autre annuaire ou orchestrateur peut convenir si ses capacités, licences et contrôles répondent à votre besoin.

Prévoyez explicitement les changements après déclenchement : date repoussée, embauche annulée, manager modifié ou contrat remplacé. Une annulation ne doit pas effacer aveuglément les traces ni un dossier déjà repris par les RH ; elle déclenche une procédure contrôlée dans chaque cible. Pour organiser les actions humaines autour du flux technique, partez de notre modèle de processus d'onboarding.

Sources officielles consultées le 8 août 2026

• CNIL — Sécurité des interfaces de programmation applicative
• ANSSI — Recommandations pour l'architecture d'un système de journalisation
• Lucca — Référence officielle des endpoints de webhook
• Personio — Vue d'ensemble officielle des API publiques et webhooks
• Microsoft Learn — Planifier le provisioning depuis une application RH cloud
• SAP Help — Présentation des API OData de SuccessFactors