API SIRH : connecter ATS, paie et onboarding
API SIRH : concevez une intégration fiable entre ATS, paie et onboarding. Mapping, webhooks, sécurité, tests et supervision expliqués pas à pas.
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.
| Composant | Responsabilité | À ne pas lui faire porter |
|---|---|---|
| ATS | Candidature, poste, étapes et décision de recrutement | Le calcul de paie ou la gestion durable des accès |
| SIRH cœur | Personne, relation d'emploi, organisation et dates d'effet validées | L'état détaillé de toutes les tâches d'onboarding |
| Paie | Données nécessaires au traitement, calculs et résultats de paie | La décision de créer une identité numérique |
| IAM / annuaire | Compte, groupes, licences et état des accès | La qualification juridique du contrat |
| Orchestrateur | Règles, files, idempotence, reprises, traces et rapprochement | Une nouvelle copie complète de toutes les données RH |
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
| Champ canonique | Règle attendue | Contrôle avant écriture |
|---|---|---|
person_id | Identifiant technique interne, immuable et non signifiant | Unicité ; jamais dérivé de l'email |
employment_id | Distingue une relation d'emploi de la personne | Entité juridique et dates d'effet présentes |
source_ids | Table ATS, SIRH, paie et IAM, sans écraser les identifiants | Une paire source–identifiant ne pointe que vers une personne |
hire_date | Date locale accompagnée du fuseau ou convention documentée | Format, date d'effet et statut contractuel cohérents |
manager_id | Référence stable vers une personne, pas un nom libre | Manager existant ou exception explicitement routée |
legal_entity | Code métier traduit par une table versionnée | Valeur connue dans la cible de paie |
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
- 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.
- Dédupliquer : si la clé a déjà produit le résultat attendu, répondre sans répéter l'écriture.
- 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.
- É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.
- Reprendre : retenter les erreurs transitoires avec attente croissante et aléatoire, respecter l'indication
Retry-Afterlorsqu'elle est fournie, et isoler les échecs permanents dans une file à examiner. - 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.
Passez de la méthode au déploiement
Profilya vous accompagne pour cadrer le cas d'usage, sécuriser les données et déployer une automatisation adaptée à vos outils et à vos équipes.
Intégrations ATS, SIRH et outils RHAuthentification, 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é.
| Contrôle | Décision à documenter | Preuve exploitable |
|---|---|---|
| Authentification | Identité technique, méthode, scopes et procédure de rotation | Inventaire des secrets et date du dernier renouvellement |
| Réseau | TLS, filtrage ou liste d'adresses si officiellement supportée | Configuration et résultat d'un test de connexion |
| Webhooks | Vérification de signature ou autre preuve documentée par l'émetteur | Rejets tracés, sans stocker le secret ni le corps complet |
| Données | Liste des champs, finalité, destinataires et conservation | Registre du traitement et contrat de mapping versionné |
| Journalisation | Événements utiles, accès, durée, alertes et protection des traces | Tableau de bord, alertes testées et revue périodique |
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Faire auditer vos API et votre flux d'embauche
Profilya peut cartographier les systèmes de référence, tester les droits réellement disponibles, construire le mapping et prototyper un flux supervisé sur vos outils. Consultez nos intégrations ATS, SIRH et ERP ou échangez avec nous sur une automatisation RH sur-mesure.
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
Questions fréquentes
Qu'est-ce qu'une API SIRH ?
Une API SIRH est une interface documentée qui permet à un autre système autorisé de lire ou d'écrire certaines données RH. Elle définit les objets accessibles, les opérations permises, le format des données, l'authentification, les limites et les erreurs. Elle ne garantit pas à elle seule que tous les modules ou champs de votre abonnement sont disponibles.
Quel système doit être la source de vérité entre ATS, SIRH et paie ?
Il n'existe pas une source unique pour toutes les données. L'ATS fait généralement autorité sur la candidature jusqu'à l'embauche, le SIRH cœur sur la personne et le contrat validé, la paie sur les calculs et bulletins, et l'annuaire d'identité sur les comptes et accès. La matrice de propriété doit être décidée champ par champ.
Faut-il utiliser des webhooks ou interroger régulièrement l'API SIRH ?
Utilisez un webhook lorsqu'un événement fiable est disponible, puis relisez si nécessaire l'objet canonique par API. Ajoutez un polling incrémental et une réconciliation périodique pour rattraper les événements manqués. Si aucun webhook n'est disponible pour l'objet voulu, le polling devient le mécanisme principal.
Comment éviter de créer deux fois le même salarié ?
Conservez les identifiants techniques de chaque système dans une table de correspondance, attribuez une clé d'idempotence à chaque commande et refusez une création si cette clé a déjà abouti. L'adresse email ne doit pas servir d'identifiant principal, car elle peut changer ou ne pas encore exister au moment de l'embauche.
Peut-on tester une API SIRH avec de vraies données salariés ?
Privilégiez un bac à sable et des données fictives. Si un test réaliste nécessite exceptionnellement des données personnelles, définissez sa nécessité, minimisez les champs, limitez les accès et la conservation, et validez le cadre avec les responsables sécurité et protection des données. La CNIL recommande un environnement de test avec des données fictives.
Une API SIRH suffit-elle pour automatiser l'onboarding ?
Non. L'API transporte les données, mais l'onboarding exige aussi des règles de déclenchement, des validations humaines, une gestion des identités, des reprises sur erreur, une réconciliation et une supervision. Il faut également vérifier les droits et fonctions réellement disponibles dans chaque abonnement éditeur.
Que faire si le SIRH ou le logiciel de paie n'a pas d'API ?
Cherchez d'abord les exports ou imports documentés, SFTP, emails structurés ou connecteurs officiels. Une automatisation par interface peut dépanner en dernier recours, mais elle est plus fragile et demande davantage de surveillance. Le processus doit conserver les mêmes contrôles d'identité, de doublons et de rapprochement.
Pour aller plus loin
Intégrations ATS, SIRH et outils RH
Profilya vous accompagne pour cadrer le besoin, sécuriser les données et déployer une solution adaptée à vos outils et à vos équipes.