API : ReadMe / Prise en main 💻 – Workelo - Centre d'aide

💡 L'API Workelo permet d'intégrer les fonctionnalités de la plateforme directement dans vos systèmes et applications. Cette documentation vous guide progressivement dans l'utilisation de l'API pour automatiser vos processus RH et gérer vos parcours collaborateurs.

📄 Documentation technique : https://api.workelo.eu/docs/apis

📋 Vue d'ensemble

L'API Workelo (version 1.6) est une API REST qui permet d'automatiser et d'intégrer vos processus RH.

Que pouvez-vous faire ?

✅ Gérer les parcours collaborateurs (onboarding, crossboarding, offboarding)
✅ Gérer les employés et leurs champs
✅ Collecter les données administratives
✅ Gérer les organisations et niveaux
✅ Automatiser des actions RH

Architecture de l'API

Type : API REST
Format : JSON
Authentification : OAuth 2.0
Base URL : https://api.workelo.eu/v1/
Rate limit : 1000 requêtes/heure par token ⚠️

🔑 Concepts clés

Avant de commencer, voici les notions essentielles définies dans Workelo :

👥 Employés et collaborateurs

Employé : Une personne faisant partie du référentiel de l'entreprise sur Workelo.

Collaborateur : Un employé vivant son (parcours) moment clé avec Workelo.

Identification flexible dans l'API :

ID (identifiant par défaut)
external_id : votre identifiant système
Email : adresse email

🛤️ Parcours (Tracks)

Parcours : Le moment clé vécu par le collaborateur au sein de l’entreprise.

Types de moment clé :

Onboarding : Processus d'intégration d'un nouveau collaborateur dans l'entreprise
Crossboarding : Processus d'accompagnement lors d'une mobilité interne ou d'un changement de poste
Offboarding : Processus d'accompagnement du départ d'un collaborateur de l'entreprise

Statuts :

Brouillon draft
Invitation envoyée invitation_sent
Programméescheduled
En cours in_progress
Clos closed
Annulé cancelled

Acteurs impliqués : Un employé étant impliqué dans le moment clé d'un collaborateur

RH rh
Responsable administratif second_rh
Manager manager
Parrain buddy
Contributeur second_manager

📝 Ressources

Ressource : Un élément précis qui est paramétré afin d'enrichir l'expérience proposée sur Workelo

Types de ressources disponibles :

Formulaire : Ressource dont l'objectif est de récupérer des informations administratives auprès de l'employé
Document : Fichier ou ressource à consulter, télécharger ou signer dans un parcours
Questionnaire : Ressource dont l'objectif est de récupérer du feedback de la part du collaborateur
Quiz : Ressource dont l'objectif est de tester les connaissances du collaborateur
Tâche : Action concrète à réaliser par un acteur ou un collaborateur dans le cadre d'un parcours
Kit : Ressource dont l'objectif est de définir un accessoire/outil/logiciel/accès qu'il est nécessaire de préparer/récupérer pour le collaborateur
Contenu : Ressource dont l'objectif est de pousser de l'information au collaborateur via un fichier ou un lien
Communication : Message ou notification envoyé aux utilisateurs dans le cadre d'un parcours

🏢 Structure organisationnelle

Environnement : C'est le niveau du référentiel organisation que l'on choisit pour définir les différents périmètres du compte.

Dans l'API :

Level Organizations : niveaux hiérarchiques (Direction, Service)
Unit Organizations : unités concrètes (RH, IT, Marketing)

🎯 Modèles (Templates)

Modèle : Un ensemble de ressources qui sont cadencées par rapport à une date clé et qui ont chacune un responsable attitré

🛠️ Bonnes pratiques

Codes de réponse HTTP

200 : Succès
201 : Ressource créée
404 : Ressource non trouvée
422 : Données non valides
401 : Non autorisé

Gestion d'erreurs

Exemple d'erreur 422 :

{
  "errors": ["Invalid email format", "Unit organization not found"],
  "message": "unprocessable_entity", 
  "code": 422
}

Limites et performance

Rate limit : 1000 requêtes/heure par token
Pagination : Utilisez limit et offset pour les grandes listes
Timeout : Minimum 30 secondes recommandé
Retry : Backoff exponentiel pour les erreurs 5xx

Les étapes recommandées

🔑 Testez l'authentification avec vos identifiants
👥 Créez un employé test pour vous familiariser
🛤️ Lancez un parcours simple avec les templates par défaut
📝 Explorez les formulaires et leur structure de données
🔄 Implémentez la synchronisation avec votre système existant
⚙️ Automatisez vos processus selon vos cas d'usage

🎯 Conseil : Commencez petit ! Un parcours d'onboarding basique avec les templates existants vous permettra de maîtriser les concepts avant d'implémenter des logiques avancées.

Pour aller plus loin

🚀 Premiers pas

Étape 1 : Obtenir vos identifiants API

Vous pouvez créer vos identifiants depuis la section Compte > Avancés > API de votre compte Workelo.

client_id
client_secret

Étape 2 : Premier appel - Lister les employés

# 1. Obtenir un token d'accès
curl -X POST https://api.workelo.eu/v1/tokens \\
  -F "client_id=your_client_id" \\
  -F "client_secret=your_client_secret"

# 2. Utiliser le token pour lister les employés
curl -X GET https://api.workelo.eu/v1/employees \\
  -H "Authorization: Bearer YOUR_TOKEN"

Étape 3 : Comprendre une réponse typique

{
  "data": [
    {
      "id": 123,
      "first_name": "Marie",
      "last_name": "Dubois",
      "email": "marie.dubois@entreprise.com",
      "role": "colleague",
      "unit_organization": {
        "id": 5,
        "name": "Service RH"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 10,
    "offset": 0
  }
}

💡 Premier succès ! Si vous obtenez cette réponse, votre intégration fonctionne. Vous pouvez maintenant explorer les autres endpoints.

🔐 Authentification

L'API utilise OAuth 2.0 avec des tokens d'accès temporaires.

Obtenir un token

POST /tokens
Content-Type: multipart/form-data

client_id=your_client_id
client_secret=your_client_secret

Réponse :

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Utiliser le token

Ajoutez le token dans l'en-tête de toutes vos requêtes :

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

⏰ Durée de vie : Les tokens sont valides 1 heure et peuvent être réutilisés. Prévoyez un système de renouvellement automatique.

👥 Gestion des employés

Lister les employés

GET /employees

or 

GET /employees?limit=10&offset=0&role=colleague

Paramètres de filtrage :

role : colleague, manager, hr, owner
unit_organization_ids : IDs des organisations (séparés par virgules)

Créer un employé

POST /employees
Content-Type: application/json

{
  "first_name": "Marie",
  "last_name": "Dubois",
  "email": "marie.dubois@entreprise.com",
  "job_position": "Manager",
  "external_id": "EMP-001",
  "unit_organization_id": 5,
  "user_role_id": 234

}

Ajouter des identifications personnalisées

POST /employees/{employee_id}/identifications
Content-Type: application/json

{
  "identification_resource_id": 5,
  "value": "BADGE-001"
}

Rechercher un employé par external_id

GET /employees?external_id=EMP-001

🛤️ Parcours collaborateurs

Créer un parcours

POST /tracks
Content-Type: application/json

{
  "mobility": "onboarding",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "employee": {
    "external_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "job_position": "string",
    "unit_organization_id": 0
  },
  "implications": {
    "hr_id": 0,
    "second_hr_id": 0,
    "manager_id": 0,
    "second_manager_id": 0,
    "buddy_id": 0
  },
  "template_ids": [
    0
  ]
}

Envoyer l'invitation au parcours

PUT /tracks/{id}/start
Content-Type: application/json

{
  "invite_at": "2019-08-24"
}

Générer un lien d'accès sécurisé

GET /user_magic_links/{employee_id}

Réponse :

{
  "magic_link": "https://app.workelo.eu/magic/97abc...",
  "expires_in": 7200
}

🔗 Sécurité : Les liens magiques expirent après 2 heures et ne sont accessibles qu'aux collaborateurs ayant un parcours actif.

📝 Formulaires et informations

Lister les formulaires d'un parcours

GET /tracks/{id}/forms

Statuts :

opened : formulaire ouvert, en attente de saisie
closed : formulaire fermé et complété
missing_validation : en attente de validation RH

Consulter les détails et données saisies

GET /forms/{id}

Structure de réponse :

{
  "id": 123,
  "name": "Informations personnelles", 
  "status": "closed",
  "paperworks": [
    {
      "id": 456,
      "paperwork_resource_name": "Adresse personnelle",
      "value": "123 Rue de la Paix, Paris",
      "paperwork_files": []
    },
    {
      "id": 789, 
      "paperwork_resource_name": "Photo d'identité",
      "value": null,
      "paperwork_files": [
        {
          "id": 101,
          "file": {"url": "https://..."}
        }
      ]
    }
  ]
}

Modifier une information

PUT /paperworks/{id}
Content-Type: application/json

{
  "value": "Nouvelle valeur"
}

Gérer les fichiers uploadés

Récupérer un fichier :

GET /paperwork_files/{id}

Uploader un nouveau fichier :

POST /paperwork_files/
Content-Type: multipart/form-data

paperwork_id={paperwork_id}
file={file_data}

📄 Documents

Lister les documents d'un parcours

GET /tracks/{id}/documents

Statuts des documents :

supplying : en cours de préparation par l'organisation
receipting : disponible pour action du collaborateur
finalized : action terminée par le collaborateur

Télécharger le fichier associé au document

GET /attachments/{id}

Réponse (fichier encodé base64) :

{
  "id": 123,
  "name": "Contrat de travail",
  "filename": "contrat_martin_jean.pdf", 
  "extension": "pdf",
  "content": "JVBERi0xLjQKMSAwIG9iao8CAovVHlwZSA..."
}

🏢 Structure organisationnelle

Comprendre la hiérarchie

Lister les niveaux organisationnels :

GET /level_organizations

Lister les organisations d'un niveau :

GET /unit_organizations?level_organization_id={level_id}

Créer une organisation

POST /unit_organizations
Content-Type: application/json

{
  "external_id": "IT-001",
  "name": "Service Informatique", 
  "level_organization_id": 2,
  "parent_id": 15,
  "language": "fr"
}

Gérer les périmètres d'un employé

Donner accès à une organisation :

POST /employees/{id}/unit_organization_managements
Content-Type: application/json

{
  "unit_organization_id": 42
}

Retirer l'accès :

DELETE /unit_organization_managements/{management_id}

⚙️ Fonctionnalités avancées

Templates et modèles

Lister les templates disponibles :

GET /templates

or 

GET /templates?mobility=onboarding&unit_organization_id=42

Utiliser des templates lors de la création :

Les templates sont spécifiés via template_ids dans la création de parcours.

⚡ Performance : L'application des templates peut prendre du temps. Le parcours est créé immédiatement, les ressources sont ajoutées en arrière-plan.

Suivi et logs

GET /logs?event=track_creation&from=2025-09-01T00:00:00Z&to=2025-09-09T23:59:59Z

Événements principaux :

user_creation : création d'employé
track_creation : création de parcours
track_start : démarrage de parcours
form_completion : formulaire complété

📑 Articles complémentaires

Associé à

📋 Vue d'ensemble

🔑 Concepts clés

👥 Employés et collaborateurs

🛤️ Parcours (Tracks)

📝 Ressources

🏢 Structure organisationnelle

🎯 Modèles (Templates)

🛠️ Bonnes pratiques

Codes de réponse HTTP

Gestion d'erreurs

Limites et performance

Les étapes recommandées

Pour aller plus loin

🚀 Premiers pas

🔐 Authentification

👥 Gestion des employés

🛤️ Parcours collaborateurs

📝 Formulaires et informations

📄 Documents

🏢 Structure organisationnelle

⚙️ Fonctionnalités avancées

📑 Articles complémentaires

Articles associés