💡 Ce guide s’adresse aux éditeurs logiciels disposant de leur propre base RH (SIRH, outil de paie, hub maison…) et souhaitant exposer une API compatible avec nos standards.

Reflect créera un connecteur à une API REST si et seulement si celui-ci est "réutilisable" pour plusieurs entreprises clientes de Reflect.

Objectif et Principe général

Reflect permet d’agréger automatiquement les données RH depuis n’importe quel logiciel (SIRH, paie, ATS…) via une API REST. L’API doit permettre de :

Récupérer tout l’historique RH structuré
Automatiser la récupération quotidienne des données
Garantir la performance, la sécurité et la fiabilité

Données attendues

Reflect exploite les données RH selon un modèle sémantique standard. Chaque point d’entrée de l’API correspond à un objet métier précis.

Voici les 7 objets métiers que votre API doit exposer si vous souhaitez une couverture complète :

Objet métier	Données attendues
`employee`	Informations démographiques et d’identification
`contract`	Informations contractuelles (type, dates, FTE, etc.)
`career`	Positionnement organisationnel (département, poste, site, grade…)
`management`	Lien hiérarchique avec le manager
`salary`	Rémunération théorique contractuelle
`absence`	Jours d’absence et typologie associée
`payroll`	Rémunération réelle issue du bulletin de paie

Chaque enregistrement doit contenir un employee_id et un contract_id unique et stable, et une effective_date.

Régime historique vs permanent

Votre API doit impérativement permettre deux modes d’usage :

1. Chargement initial historique

Expose toutes les données RH disponibles depuis 3 ans (ou plus si possible)
Supporte la pagination sur gros volumes (jusqu’à 1M+ lignes)
Permet de rejouer un export sur une période précise (via start_date et end_date)
Tous les enregistrements doivent inclure :
- un champ effective_date (date d’effet métier)
- un champ updated_at (dernière date de modification technique)

2. Régime permanent (incrémental)

Tous les endpoints doivent supporter le filtre updated_after
Ce filtre s’applique sur le champ updated_at, pas effective_date
Il permet de récupérer uniquement les enregistrements modifiés depuis la dernière synchronisation

💡 Un objet dont l’effective_date est ancienne mais dont les données ont été modifiées doit réapparaître dans les appels updated_after.

Spécifications techniques

Authentification

Nous recommandons l’un des deux modes suivants :

Bearer token dans le header HTTP

Authorization: Bearer YOUR_API_TOKEN

Le token doit pouvoir être régénéré manuellement si expiré.

Format de réponse

Format JSON strictement structuré
Liste d’objets homogènes
Chaque objet contient un champ employee_id obligatoire et un champ effective_date
Exemple :

[
  {
    "employee_id": "E1234",
    "legal_entity": "SAS ABC",
    "effective_date": "2023-01-01",
    "job_title": "Sales Manager",
    "employment_type": "CDI",
    "fte": 1.0,
    "arrival_date": "2022-03-08",
    "contract_start_date": "2023-01-01",
    "contract_end_date": null,
    "remote_status": "HYBRID"
    "employment_type": "CDI",
  },
  ...
]

Pagination

Obligatoire au-delà de 500 résultats
Standard : limit + page
Recommandé : totalCount + links.prev / links.next
Exemple :

GET /contracts?limit=100&page=3

Error handling

Votre API doit renvoyer des erreurs standardisées avec un message lisible au format JSON :

Toutes les erreurs 4xx et 5xx doivent contenir un objet JSON explicite
Inclure systématiquement status, title et errors

Exemple (HTTP 400)

{
  "title": "Validation failed",
  "status": 400,
  "errors": {
    "employee_id": ["This field is required."],
    "contract_start_date": ["Invalid format."]
  }
}

Spécifications métier

Champs obligatoires

Chaque champ doit respecter les définitions métiers du modèle Reflect (cf. détail des champs / colonnes recommandées). Cependant, les noms ne doivent pas nécessairement respecter la nomenclature Reflect.

Vous pouvez aussi inclure des données complémentaires non comprises le document ci-dessus.

Filtrage

Tous les endpoints doivent permettre de filtrer les données afin d’optimiser les appels.

Paramètre	Cible	Type	Exemple
`employee_id`	Identifiant salarié	égalité	`employee_id=E123`
`status` (optionnel)	Statut RH (actif, inactif)	égalité	`status=active`
`start_date` / `end_date`	Plage sur `effective_date`	intervalle	`start_date=2024-01-01&end_date=2024-12-31`
`updated_after`	Dernière modification	date-time ISO	`updated_after=2024-07-01T00:00:00Z`

Recommandations :

Le champ updated_at est obligatoire sur chaque objet
Utiliser le format ISO 8601 pour les dates (YYYY-MM-DD ou YYYY-MM-DDTHH:MM:SSZ)
Les plages de dates peuvent être ouvertes (ex : start_date=2023-01-01 seul)

Anti-patterns à éviter

Voici les pratiques courantes qui rendent une API incompatible avec Reflect. Elles doivent être strictement évitées.

Cas à éviter	Pourquoi c’est bloquant
API sans champ `updated_at`	Impossible de détecter les modifications
Données limitées à l’état “actuel”	Aucune visibilité historique
Suppression physique d’enregistrements	Rupture de traçabilité des données
Modèle instable (champs renommés ou supprimés)	Casse des mappings Reflect
Identifiants RH non persistants (nom, email…)	Impossibilité de suivre un salarié dans le temps
Format de dates non ISO	Parsing impossible ou imprécis
Données partielles selon statut ou filtre implicite	Incohérences métiers dans les dashboards

Documentation conseillée

Nous recommandons de fournir :

Un lien vers une documentation publique (type swagger) ou PDF
Un exemple d’appel par objet
La méthode d'authentification et les paramètres utilisables (pagination, filtres...)

Si vous cherchez une inspiration, la documentation de l'API du logiciel Lucca est de bonne qualité : 📘 Documentation API de Lucca (exemple à suivre)

Intégration et création du connecteur Reflect

Une fois l’API disponible, notre équipe Data suit ce processus pour créer le connecteur API :

Audit technique (structure, authentification, couverture, volume)
Contrôle de qualité des champs (formats, identifiants, coverage)
Mapping avec notre modèle sémantique
Lancement du flux automatique (production)

Le test complet prend en général une semaine si l’API est bien structurée.

Bonnes pratiques

Utiliser un identifiant RH stable par salarié (employee_id)
Exposer les dates au format ISO (YYYY-MM-DD)
Ne jamais renvoyer de champs vides ou ambigus
Garder une cohérence de structure entre appels
Prévoir un temps de réponse < 5s pour 1000 résultats

Besoin d'aide ? Contactez votre interlocuteur Reflect habituel ou envoyez-nous un email à [email protected]. Nous serons ravis de collaborer pour mettre en place une API stable, fiable et pérenne.

Créer une API SIRH compatible avec Reflect