Suppression en masse du prévisionnel via API

Objectif de l'article

Cet article explique comment supprimer en masse, via API, le prévisionnel direction (business_unit_forecasts) et le prévisionnel projet (project_forecasts) sur une période et un périmètre donnés, grâce aux endpoints bulk-delete.

Cette fonctionnalité s'adresse aux systèmes d'information clients (ERP) qui pilotent le prévisionnel via API ; il s'agit d'un flux entièrement machine-to-machine, sans interface iBAT associée.

Au programme de cet article :

• À quoi sert cette fonctionnalité ?
• Profils concernés
• Les endpoints et le mode simulation
• Critères de filtrage disponibles
• Comment se combinent les critères ?
• Ce qui est supprimé concrètement
• Erreurs et garde-fous
• Bonnes pratiques
• Limites fonctionnelles
• FAQ

🎯 À quoi sert cette fonctionnalité ?

Jusqu'ici, lorsqu'un client devait corriger ou reconstruire son prévisionnel (direction ou projet) dans iSYBUY, il devait identifier précisément les lignes à supprimer côté SI source avant de les transmettre — une opération lourde et source d'erreurs en cas de désynchronisation.

La suppression en masse permet de purger simplement le périmètre concerné (une période, des employés, des sociétés, des projets, etc.) puis de renvoyer l'intégralité du prévisionnel à neuf, sans avoir à calculer les écarts. Cela fiabilise la synchronisation entre le SI client et iSYBUY et réduit la charge d'intégration.

👥 Profils concernés

🔌 Les endpoints et le mode simulation

Deux endpoints sont disponibles, sur le même modèle que l'endpoint déjà en production /api/absences/bulk-delete :

• DELETE /api/business_unit_forecasts/bulk-delete — prévisionnel direction
• DELETE /api/project_forecasts/bulk-delete — prévisionnel projet

Chaque endpoint fonctionne selon le même mécanisme général, piloté par le paramètre dryRun (booléen, true par défaut) :

⚠️ Un appel dryRun:false lancé plusieurs fois relance la suppression à chaque fois — il n'y a pas de mécanisme de déduplication.

📋 Les critères de filtrage disponibles

business_unit_forecasts (prévisionnel direction)

⚠️ Le body ne peut jamais être vide : au moins un critère doit être fourni.

project_forecasts (prévisionnel projet)

Mêmes champs que ci-dessus, avec un critère supplémentaire :

📐 Comment se combinent les critères ?

• À l'intérieur d'une même famille de critères (par exemple plusieurs companies), les valeurs se combinent en OU (société A OU société B).

• Entre familles de critères différentes (par exemple companies ET fromDate/toDate ET employees), la combinaison est toujours en ET.

• Aucun critère n'est individuellement obligatoire, mais un minimum de 1 est requis dans le body.

Formats de référence : chaque référence (société, direction, projet, activité, employé) peut être fournie sous 3 formats possibles selon l'objet : IRI (/api/companies/1), {externalReference} ou {code} — à l'exception d'activities, qui n'accepte que l'IRI ou {code} (pas d'externalReference).

🗑️ Ce qui est supprimé concrètement

Prévisionnel direction (business_unit_forecasts) : sont supprimés l'affectation service, l'affectation projet associée, ainsi que le pointage / pointage poste / pointage déplacement associé qui était issu du prévisionnel, dès lors que l'affectation correspond à tous les critères fournis (période, employés, sociétés, directions, projets du critère projects).

Prévisionnel projet (project_forecasts) : sont supprimés l'affectation projet et le pointage poste associé qui était issu du prévisionnel, et l'activité par défaut est remise sur le pointage du projet, dès lors que l'affectation correspond à tous les critères fournis (période, employés, sociétés, directions, projets, et activités).

Dans les deux cas, la suppression (ou mise à jour) de chaque élément trouvé suit le même fonctionnement que le delete unitaire déjà existant.

⚠️ Erreurs et garde-fous

Garde-fou de périmètre : la suppression ne doit jamais dépasser le périmètre auquel l'utilisateur API connecté a accès. Aujourd'hui, ce périmètre correspond au groupe de l'utilisateur, même si les critères fournis dans la requête sembleraient autoriser un périmètre plus large.

👍 Bonnes pratiques

✅ Toujours tester un appel en dryRun:true (comportement par défaut) avant de lancer une suppression réelle (dryRun:false), afin de vérifier la liste des éléments impactés.

✅ Combiner les critères avec précision : une famille de critères trop large associée à une autre restrictive peut donner des résultats inattendus (rappel : ET entre familles, OU à l'intérieur d'une même famille).

✅ Vérifier que les références fournies (sociétés, directions, projets, activités, employés) existent bien avant l'appel, pour éviter les erreurs 400 « objet non trouvé ».

⚠️ Garder à l'esprit qu'un appel dryRun:false répété relance la suppression sans protection anti-doublon.

⛔ Limites fonctionnelles

• Aucune déduplication : un appel dryRun:false répété relance la suppression à chaque fois.

• Le garde-fou de périmètre est aujourd'hui limité au niveau groupe ; les restrictions plus fines (société, projet, utilisateur) ne sont pas encore actives.

• Aucun parcours de modification ou d'archivage n'est couvert — uniquement la suppression.

❓ FAQ

Pourquoi mon appel retourne une erreur 400 avec un body vide ? → Le body ne peut pas être vide : au moins un critère de filtrage (période, employés, sociétés, directions, projets, ou activités pour le prévisionnel projet) doit être fourni.

Pourquoi certains éléments attendus n'apparaissent pas dans le résultat en dryRun ? → Vérifiez que tous les critères fournis se combinent bien en ET entre eux — un élément doit correspondre à tous les critères fournis simultanément pour être inclus.

Puis-je annuler une suppression déjà exécutée (dryRun:false) ? → Aucun mécanisme d'annulation ou de restauration n'est possible.

Mots-clés : bulk-delete - prévisionnel - business_unit_forecasts - project_forecasts - dryRun - API - suppression en masse