API : nos recettes prêtes à l'emploi 👩‍🍳 – Workelo - Centre d'aide

Voici un guide complet, structuré par user story principale, avec tous les appels API nécessaires dans l'ordre (y compris les appels préalables pour récupérer les IDs).

🙋 Pour prendre en main l'API, rendez-vous dans la documentation dédiée dans un premier temps.

1. Gérer la base employés 👥

Récupérer les IDs nécessaires

→ Récupérer le user_role_id correspondant au rôle souhaité (colleague, manager, hr...) :

GET /user_roles

→ Récupérer l'id de l'organisation à laquelle rattacher l'employé :

GET /unit_organizations

→ Récupérer les identification_resource_id des champs personnalisés disponibles (badge, matricule, etc.) :

GET /identification_resources

Créer l'employé

POST /employees
{
  "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 champs d'identification personnalisés

POST /employees/{employee_id}/identifications
{
  "identification_resource_id": 5,
  "value": "BADGE-001"
}

Consulter / Modifier l'employé

GET  /employees/{id}
PUT  /employees/{id}
GET  /employees?role=manager          ← lister par rôle
GET  /employees?external_id=EMP-001  ← retrouver par ID externe

2. Gérer votre structure organisationnelle 🏢

Comprendre la hiérarchie existante

→ Lister les niveaux (ex : Direction, Service, Site) :

GET /level_organizations

→ Lister les unités d'un niveau donné :

GET /unit_organizations?level_organization_id={level_id}

Créer une nouvelle organisation

POST /unit_organizations
{
  "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é (scope d'accès)

GET  /employees/{employee_id}/unit_organization_managements
POST /employees/{employee_id}/unit_organization_managements
     { "unit_organization_id": 42 }
DELETE /unit_organization_managements/{management_id}

3. Créer un parcours 🛤️

Prérequis — récupérer les IDs nécessaires

→ unit_organization_id de l'organisation du collaborateur :

GET /unit_organizations

→ id du manager, RH, buddy, etc. :

GET /employees?role=manager
GET /employees?role=hr

→ id des templates à appliquer :

GET /templates?mobility=onboarding&unit_organization_id={id}

Créer le parcours (statut draft)

POST /tracks
{
  "mobility": "onboarding",
  "start_date": "2026-06-01",
  "end_date": "2026-09-01",
  "employee": {
    "first_name": "Jean",
    "last_name": "Martin",
    "email": "jean.martin@entreprise.com",
    "job_position": "Développeur",
    "unit_organization_id": 5
  },
  "implications": {
    "hr_id": 101,
    "manager_id": 202,
    "buddy_id": 303
  },
  "template_ids": [999056]
}

Lancer le parcours et envoyer les invitations

PUT /tracks/{id}/start
{
  "invite_at": "2026-05-28"   ← optionnel : date d'invitation du collaborateur
}

4. Piloter et suivre les parcours 🧐

Lister et filtrer les parcours

GET /tracks
GET /tracks?status=in_progress
GET /tracks?status=draft

Statuts disponibles : draft, invitation_sent, scheduled, in_progress, closed, cancelled

Consulter le détail d'un parcours (avec métriques live)

→ Retourne santé du parcours, progression, taux de disponibilité des actions, nombre d'actions réalisées :

GET /tracks/{id}

Modifier un parcours (dates, acteurs)

PUT /tracks/{id}
{
  "start_date": "2026-06-15",
  "apply_on_actions": true,     ← décale automatiquement les actions
  "implications": {
    "manager_id": 205
  }
}

5. Gérer l'administratif 📃

Lister les formulaires d'un parcours

GET /tracks/{track_id}/forms
GET /tracks/{track_id}/forms?status=opened         ← en attente de saisie
GET /tracks/{track_id}/forms?status=missing_validation  ← en attente de validation RH

Consulter le détail et les données saisies

→ Retourne tous les paperworks avec leurs valeurs remplies :

GET /forms/{id}

Modifier une valeur d'un champ

PUT /paperworks/{id}
{ "value": "Nouvelle valeur" }

Gérer les fichiers chargés dans un formulaire

GET  /paperwork_files/{id}       ← récupérer un fichier
POST /paperwork_files            ← uploader un fichier
     { "paperwork_id": 456, "file": "..." }

Lister les ressources de formulaire disponibles

GET /paperwork_resources
GET /paperwork_resources?type=selection   ← listes déroulantes
GET /paperwork_resources?type=date

Lister les documents d'un parcours

GET /tracks/{track_id}/documents

Statuts : supplying (en préparation), receipting (disponible), finalized (complété)

Télécharger un fichier (base64)

GET /attachments/{id}

Lister les ressources documents disponibles

GET /document_resources
GET /document_resources?type=sign
GET /document_resources?type=download

6. Gérer les listes déroulantes d'options 🔽

Lister les options d'une ressource

GET /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}

Paginer avec limit / offset pour les grandes listes.

Créer une option simple

POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}
{
  "value": "CDI",
  "external_id": "contract_cdi",
  "position": 1
}

Créer une option avec un parent (liste dépendante)

POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}
{
  "value": "Paris 1er",
  "external_id": "75056",
  "position": 1,
  "parent_id": 1001
}

Le parent_id est l'id de la collection_value parente (ex : le code postal 75001).

Mettre à jour une option (libellé, position, ou parent)

PUT /collection_values/{id}
{
  "value": "Paris 1er Arrondissement",   // modifier le libellé
  "position": 2,                          // changer l'ordre
  "parent_id": 1050                       // changer de branche hiérarchique
}

Les valeurs existantes dans des parcours conservent leur ancienne valeur (pas de cascade)

7. Générer un lien d'accès sécurisé (Magic Link) 🔗

GET /user_magic_links/{employee_id}
GET /user_magic_links_by_email/{email}
GET /user_magic_links_by_external_id/{external_id}

⏱️ Les liens expirent après 2 heures et ne fonctionnent que si le collaborateur a un parcours actif.

8. Analyser et auditer l'activité 📈

GET /logs
GET /logs?event=user_creation&from=2026-01-01&to=2026-05-26
GET /logs/{uuid}

9. Consulter les actions assignées (acteurs) ✔️

→ Récupérer l'id de l'acteur :

GET /employees?role=manager

Lister les actions d'un acteur

GET /owners/{owner_id}/actions
GET /owners/{owner_id}/actions?limit=20&offset=0

📊 Récapitulatif visuel

User Story	Calls principaux
Créer un employé	`GET /user_roles` → `GET /unit_organizations` → `POST /employees`
Enrichir un profil	`GET /identification_resources` → `POST /employees/{id}/identifications`
Gérer les orgs	`GET /level_organizations` → `POST /unit_organizations`
Créer un parcours	`GET /unit_organizations` + `GET /employees` + `GET /templates` → `POST /tracks`
Lancer l'invitation	`PUT /tracks/{id}/start`
Suivre les parcours	`GET /tracks` → `GET /tracks/{id}`
Modifier un parcours	`PUT /tracks/{id}`
Formulaires admin	`GET /tracks/{id}/forms` → `GET /forms/{id}` → `PUT /paperworks/{id}`
Documents	`GET /tracks/{id}/documents` → `GET /attachments/{id}`
Magic Link	`GET /user_magic_links/{id}`
Actions acteurs	`GET /employees` → `GET /owners/{id}/actions`
Logs & audit	`GET /logs`

📑 Articles complémentaires

Associé à