> For the complete documentation index, see [llms.txt](https://help.steeple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.steeple.com/administration/synchroniser-annuaire-api.md).

# Comment synchroniser mon annuaire de collaborateurs avec l'API Steeple ?

## Présentation

L'API Steeple permet d'alimenter votre annuaire Steeple automatiquement depuis l'outil qui fait référence pour vos collaborateurs : SIRH, annuaire d'entreprise, outil de paie, base interne… Il suffit que cet outil puisse produire un fichier de collaborateurs et appeler l'API, par exemple chaque nuit.

L'API demande un développement de votre côté. Steeple propose des intégrations prêtes à l'emploi pour les sources les plus courantes : vérifiez d'abord si l'une d'elles correspond à votre situation, et gardez l'API pour les cas qu'elles ne couvrent pas.

## Quelle solution choisir pour synchroniser votre annuaire ?

| Votre situation                                                                    | Solution recommandée                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Votre SIRH est Lucca                                                               | Le connecteur Lucca : voir [Comment synchroniser mon annuaire de collaborateurs avec Lucca ?](https://help.steeple.com/administration/synchroniser-annuaire-lucca.md)                                  |
| Vos collaborateurs sont gérés dans Microsoft Entra ID ou Okta                      | Le provisioning SCIM, avec le SSO configuré au préalable : voir [Approvisionnement automatique des collaborateurs (Provisioning / SCIM)](https://help.steeple.com/administration/provisioning-scim.md) |
| Vous mettez à jour l'annuaire ponctuellement, quelques fois par an                 | L'import de fichier depuis l'administration : voir [Comment importer des collaborateurs en masse ?](https://help.steeple.com/administration/import-collaborateurs.md)                                  |
| Aucune de ces solutions ne convient et vous voulez une synchronisation automatique | L'API Steeple, décrite dans cet article                                                                                                                                                                |

Ces intégrations se configurent dans l'**Administration**, section **Intégrations** (`/administration/integrations`). Ne cumulez pas plusieurs sources pour le même annuaire : deux sources qui écrivent les mêmes fiches finissent par se contredire. L'API ne bloque pas un import quand une autre synchronisation est active : c'est à vous de le vérifier. En cas de doute, décrivez votre besoin dans [Aide et ressources](https://app.steeple.com/help) pour choisir la solution adaptée.

L'API reprend le fonctionnement de l'import de fichier de l'administration : vous envoyez un fichier de collaborateurs, Steeple le vérifie puis l'applique, et vous consultez le bilan de l'import ainsi que les erreurs, avec la ligne concernée.

## Prérequis

* Un token API Steeple : voir [Comment utiliser l'API Steeple ?](https://help.steeple.com/administration/api-steeple.md).
* Un compte administrateur de l'organisation, au nom duquel les imports sont lancés.
* Aucune autre synchronisation d'annuaire active (SCIM ou Lucca).

## Le compte administrateur

Chaque appel d'import demande un paramètre `user_id` : l'identifiant d'un administrateur de l'organisation. L'import est lancé en son nom et apparaît dans l'historique des imports comme s'il l'avait déposé lui-même.

Pour trouver cet identifiant, appelez `GET /v1/users` : la liste renvoie l'`id`, le prénom et le nom de chaque collaborateur. Repérez l'administrateur par son nom et relevez son `id`.

Utilisez de préférence un compte administrateur dédié à l'intégration : si le compte est retiré de l'organisation ou perd ses droits d'administration, les imports sont refusés.

## Choisir le type d'import

Le paramètre `operation` correspond aux types d'import proposés dans l'administration.

| `operation`      | Type d'import            | Nouveaux collaborateurs | Collaborateurs présents dans le fichier                    | Collaborateurs absents du fichier              |
| ---------------- | ------------------------ | ----------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `INSERT`         | Insertion                | Créés                   | Inchangés                                                  | Inchangés                                      |
| `UPSERT`         | Insertion et mise à jour | Créés                   | Mis à jour                                                 | Inchangés                                      |
| `MIRROR_LENIENT` | Miroir sans suppression  | Créés                   | Mis à jour, et retirés des communautés absentes du fichier | Inchangés                                      |
| `MIRROR_STRICT`  | Miroir                   | Créés                   | Mis à jour, et retirés des communautés absentes du fichier | **Retirés de l'organisation, compte supprimé** |
| `DELETE`         | Suppression              | Ignorés                 | Retirés de l'organisation                                  | Inchangés                                      |

Pour une synchronisation régulière, `UPSERT` ou `MIRROR_LENIENT` conviennent dans la plupart des cas : ils ne retirent personne de l'organisation.

N'utilisez `MIRROR_STRICT` qu'avec un fichier qui contient **tous** les collaborateurs de l'organisation. Un fichier incomplet supprime les comptes des collaborateurs qui n'y figurent pas.

## Préparer le fichier

Le fichier est le même que pour l'import depuis l'administration : partez du gabarit téléchargeable dans l'assistant d'import, pour le type d'import choisi. Formats acceptés : CSV, `.xlsx`, `.xls`, `.xlsm`.

Les colonnes sont reconnues par leur intitulé exact, dans la langue de votre organisation : utilisez les intitulés de la colonne correspondant à cette langue, tels qu'ils apparaissent dans le gabarit. Leur ordre n'a pas d'importance. Une colonne non reconnue est ignorée et signalée dans les messages de l'import.

| Contenu                                                    | Français                        | English                       | Español                          | Deutsch                                  |
| ---------------------------------------------------------- | ------------------------------- | ----------------------------- | -------------------------------- | ---------------------------------------- |
| Adresse email professionnelle                              | `Email`                         | `Email`                       | `Correo electrónico`             | `Email`                                  |
| Matricule RH                                               | `Matricule`                     | `Staff ID`                    | `Matrícula`                      | `Personalnummer`                         |
| Identifiant de connexion, pour un collaborateur sans email | `Identifiant`                   | `Login`                       | `Identificador`                  | `Login`                                  |
| Nom (obligatoire)                                          | `Nom`                           | `Last name`                   | `Apellido`                       | `Nachname`                               |
| Prénom (obligatoire)                                       | `Prénom`                        | `First name`                  | `Nombre`                         | `Vorname`                                |
| Numéro de téléphone                                        | `Téléphone`                     | `Phone number`                | `Número de teléfono`             | `Telefon`                                |
| Jour et mois de l'anniversaire, par exemple `31/12`        | `Jour d'anniversaire`           | `Birthday`                    | `Día de cumpleaños`              | `Geburtstag`                             |
| Nom d'une communauté existante, une colonne par communauté | `Communauté 1`, `Communauté 2`… | `Community 1`, `Community 2`… | `Comunidad 1`, `Comunidad 2`…    | `Gruppe 1`, `Gruppe 2`…                  |
| Nom d'un service de l'organisation                         | `Service`                       | `Service`                     | `Servicio`                       | `Abteilung`                              |
| Nom d'un lieu de l'organisation                            | `Lieu`                          | `Location`                    | `Ubicación`                      | `Standort`                               |
| Intitulé de poste                                          | `Poste`                         | `Position`                    | `Puesto`                         | `Position`                               |
| Adresse email du manager                                   | `Email du responsable`          | `Manager's email`             | `Correo del responsable`         | `E-Mail des Vorgesetzten`                |
| Date d'entrée, par exemple `31/12/2026`                    | `Entrée en entreprise`          | `Seniority date`              | `Fecha de entrada a la empresa`  | `Datum des Eintritts in das Unternehmen` |
| Date de fin de contrat, par exemple `31/12/2026`           | `Fin de contrat`                | `Contract end date`           | `Fecha de fin de contrato`       | `Vertragsende`                           |
| Droits d'administration : `1` ou `0`                       | `Administrateur`                | `Administrator`               | `Administrador`                  | `Administrator`                          |
| Texte de présentation                                      | `Bio`                           | `Biography`                   | `Biografía`                      | `Biografie`                              |
| Connexion par SSO : `1` ou `0`                             | `Méthode de connexion en SSO`   | `SSO Login Method`            | `Método de inicio de sesión SSO` | `SSO-Anmeldemethode`                     |
| Identifiant SSO, si votre organisation utilise le SSO      | `Identifiant SSO`               | `SSO Identifier`              | `Identificador SSO`              | `SSO-Kennung`                            |
| Code à 4 chiffres                                          | `Code PIN TV`                   | `TV PIN`                      | `PIN de TV`                      | `TV-PIN`                                 |

Pour les colonnes oui/non, `1` et `0` sont acceptés quelle que soit la langue.

Un collaborateur est retrouvé par son **email**, son **matricule** ou son **identifiant**. Chaque ligne doit en porter au moins un, et un même identifiant ne peut pas apparaître deux fois dans le fichier. Si les trois changent en même temps dans votre outil source, le collaborateur est traité comme une nouvelle personne.

L'import `DELETE` n'utilise que les trois colonnes d'identification : email, matricule et identifiant de connexion.

## Lancer un import

### Étape 1 — Déclarer le fichier

```bash
curl -X POST "https://api.steeple.com/v1/blobs?user_id=<id administrateur>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"blob": {"filename": "collaborateurs.csv", "content_type": "text/csv", "byte_size": 48213, "checksum": "<empreinte>"}}'
```

* `byte_size` : la taille du fichier en octets.
* `checksum` : l'empreinte MD5 du fichier, encodée en base64. Par exemple : `openssl md5 -binary collaborateurs.csv | base64`.

La réponse contient une clé `signed_id` et un bloc `direct_upload`, avec l'URL de dépôt (`url_for_direct_upload`) et les en-têtes à envoyer (`headers_for_direct_upload`). L'URL de dépôt est valable 5 minutes.

### Étape 2 — Déposer le fichier

Envoyez le contenu du fichier à l'URL `direct_upload.url_for_direct_upload`, avec tous les en-têtes de `direct_upload.headers_for_direct_upload`. Cet appel ne porte pas le token Steeple.

```bash
curl -X PUT "<url_for_direct_upload>" \
  -H "Content-Type: text/csv" \
  -H "Content-MD5: <empreinte>" \
  -H "Content-Disposition: <valeur reçue>" \
  --data-binary @collaborateurs.csv
```

### Étape 3 — Lancer l'import

```bash
curl -X POST "https://api.steeple.com/v1/member_provisionings" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<id administrateur>", "signed_id": "<signed_id>", "operation": "UPSERT", "dry_run": false, "notify_users": false}'
```

* `dry_run` : `true` pour lancer une simulation (voir plus bas). `false` par défaut.
* `notify_users` : `true` pour que les collaborateurs créés reçoivent un email d'activation de leur compte. `false` par défaut : vous pourrez envoyer les identifiants plus tard depuis l'administration (voir [Comment envoyer les identifiants de connexion ?](https://help.steeple.com/administration/envoyer-identifiants.md)).

La réponse contient l'`id` de l'import.

### Étape 4 — Suivre l'import

L'import est traité en arrière-plan. Interrogez son état jusqu'à ce qu'il soit terminé :

```bash
curl "https://api.steeple.com/v1/member_provisionings/<id>?user_id=<id administrateur>" \
  -H "Authorization: Bearer <token>"
```

Le champ `state` passe par `created`, `loading`, `checking`, puis `syncing`. L'import se termine par `succeeded`, `failed` ou `canceled`.

### Étape 5 — Consulter le résultat

* `GET /v1/member_provisionings/{id}/reports` : le bilan de l'import, sous forme de totaux par opération et par communauté (par exemple `CREATE_MEMBER` : 2 collaborateurs créés dans la communauté « Siège »). Ajoutez `dry_run=true` pour n'afficher que le bilan d'une simulation.
* `GET /v1/member_provisionings/{id}/messages` : les erreurs et avertissements, avec la ligne et la colonne concernées.

Ces deux listes demandent le paramètre `user_id`. Demandez `per_page=50` (le maximum). Si un import produit plus de 50 messages, consultez le rapport complet depuis la page **Import** de l'administration, où apparaissent aussi les imports lancés par l'API.

Une erreur détectée pendant la vérification du fichier (nom manquant, ligne sans identifiant, identifiant en double…) fait échouer tout l'import, avant toute modification : corrigez le fichier et relancez l'import. Consultez aussi les messages d'un import `succeeded`, qui peut contenir des avertissements.

## La simulation

Avec `dry_run: true`, Steeple calcule ce que l'import changerait sans rien appliquer. L'import s'arrête à l'état `reviewing`. Un administrateur consulte le rapport et valide l'import depuis la page **Import** de l'administration. L'API ne permet pas de valider une simulation.

Lancez vos premiers imports en simulation, et toujours un import `MIRROR_STRICT`. Sans simulation, un import `MIRROR_STRICT` s'applique directement : la confirmation demandée dans l'administration avant de supprimer un grand nombre de comptes n'intervient pas.

La simulation est **obligatoire** pour un fichier qui attribue ou modifie un identifiant de connexion. Sans simulation, l'import échoue avec le message `dry_run_required`.

## Ce que l'assistant peut faire

L'assistant ne peut pas lancer d'import par l'API. Il doit d'abord orienter vers l'intégration la mieux adaptée (connecteur Lucca, provisioning SCIM, import de fichier) et ne présenter l'API qu'en dernier recours. Il peut ensuite expliquer le fonctionnement de la synchronisation par l'API, les types d'import et le format du fichier, et guider vers la page **Intégrations** pour générer un token ou vers la page **Import** pour valider une simulation. Pour le détail des endpoints, orienter vers <https://api-docs.steeple.com>.
