Générer un fichier des temps importable dans la base de gestion

Objectif

Cet article explique comment générer un fichier Excel des temps (Import_Temps.xlsx) importable dans la base de gestion d'un cabinet, en utilisant les données récupérables par les API : dossiers, collaborateurs, missions et prestations.

Génération du fichier Excel des temps

Cette partie s'adresse aux éditeurs qui souhaitent générer, pour un cabinet comptable, un fichier des temps (fichier Excel) importable dans sa base de gestion.

Prérequis

Disposer d'un compte API généré par le cabinet comptable. Il permet d'interroger les API de la base de gestion du cabinet pour récupérer les codes à utiliser dans le fichier.

Structure du fichier

La ligne 1 du fichier Excel contient les noms des champs de la table (à ne pas modifier). Les colonnes sont classées en trois catégories :

• Obligatoires : ADRESSE.ADR_CODE, COL_CODE, TEMPS_DATE, PREST_CODE et TEMPS_DUREE doivent être renseignées sur chaque ligne.
• Recommandées : MISS_CODE et TEMPS_MEMO sont à renseigner de préférence.
• Facultatives : EXO_CODE, TEMPS_M_QTE, TEMPS_M_PVU, TEMPS_M_PV, TEMPS_M_PR et TEMPS_M_PVC servent uniquement à forcer des valeurs. Si la colonne est absente du fichier, la valeur est calculée automatiquement à l'import.

Les codes à utiliser pour les dossiers, les collaborateurs et les prestations doivent exister dans la base de gestion. Ils peuvent être récupérés par les API indiquées dans le tableau ci-dessous.

Associer la ligne de temps à une mission

Il est préconisé d'associer chaque ligne de temps à une mission ouverte sur le dossier (colonne MISS_CODE). La liste des missions ouvertes d'un dossier est disponible par l'API GET /v1/missions.

Exemple d'un retour de l'API (champs utiles uniquement) :

[
  {
    "Id": 5220, "Code": "COMPTA", "Libelle": "Mission de Comptabilité",
    "CodeCollaborateur": "ED",
    "CodeExercice": "2025", "Etat": "_TERMINE",
    "DateDebut": "2025-01-01T00:00:00",
    "DateFin": "2025-12-31T00:00:00",
    "DateTerminee": "2026-10-02T00:00:00",
    "Dossier": { "Id": 1410, "Code": "DNORD00016", ... }
  },
  {
    "Id": 5221, "Code": "SOCIAL", "Libelle": "Mission Social",
    "CodeCollaborateur": "NL",
    "CodeExercice": "2025", "Etat": "_TERMINE",
    "DateDebut": "2025-01-01T00:00:00",
    "DateFin": "2025-12-31T00:00:00",
    "DateTerminee": "2026-10-02T00:00:00",
    "Dossier": { "Id": 1410, "Code": "DNORD00016", ... }
  },
  {
    "Id": 5222, "Code": "COMPTA", "Libelle": "Mission de Comptabilité",
    "CodeCollaborateur": "ED",
    "CodeExercice": "2026", "Etat": "_ENCOURS",
    "DateDebut": "2026-01-01T00:00:00",
    "DateFin": "2026-12-31T00:00:00",
    "DateTerminee": null,
    "Dossier": { "Id": 1410, "Code": "DNORD00016", ... }
  },
  {
    "Id": 5223, "Code": "SOCIAL", "Libelle": "Mission Social",
    "CodeCollaborateur": "NL",
    "CodeExercice": "2026", "Etat": "_ENCOURS",
    "DateDebut": "2026-01-01T00:00:00",
    "DateFin": "2026-12-31T00:00:00",
    "DateTerminee": null,
    "Dossier": { "Id": 1410, "Code": "DNORD00016", ... }
  }
]

Correspondance avec les colonnes du fichier Excel :

• Code → MISS_CODE (ex. COMPTA ou SOCIAL). Dans le fichier Excel, le lien se fait sur le code de la mission, et non sur son Id. Dans l'exemple, le dossier a donc 2 missions : COMPTA et SOCIAL, chacune présente sur l'exercice 2025 et sur l'exercice 2026.
• Id : ne sert pas dans le fichier Excel ; il est uniquement utilisé pour appeler GET /v1/missions/{id}/prestations.
• CodeCollaborateur : code du collaborateur affecté à la mission (ex. ED pour COMPTA, NL pour SOCIAL).
• Dossier.Code → ADRESSE.ADR_CODE (ex. DNORD00016)
• CodeExercice → EXO_CODE (ex. 2026), uniquement pour forcer l'exercice ; sinon il est calculé à l'import.
• Etat = _ENCOURS : la mission est ouverte et peut recevoir des temps.
• Etat = _TERMINE : la mission est clôturée. Il ne sera pas possible de saisir des temps à une date supérieure à la date de clôture (DateTerminee). Dans l'exemple, les missions COMPTA et SOCIAL de l'exercice 2025 sont clôturées au 02/10/2026 : il ne sera pas possible d'y saisir des temps datés après le 02/10/2026.
• DateDebut / DateFin : la date TEMPS_DATE doit de préférence se situer dans cette période.

Choisir la prestation parmi celles prévues dans la mission

Pour la colonne PREST_CODE, il est préconisé de reprendre une prestation prévue dans la mission, récupérable par l'API GET /v1/missions/{id}/prestations ({id} = champ Id de la mission renvoyé par GET /v1/missions, ex. 5222). Seules les prestations dont "UtilisableTemps": true doivent être utilisées pour une ligne de temps.

La liste complète des prestations du cabinet est disponible par l'API GET /v1/prestations.

Exemple pour la mission COMPTA 2026 (Id 5222) : GET /v1/missions/5222/prestations (champs utiles uniquement) :

[
  { "Code": "C100", "Libelle": "Tenue de la comptabilité",
    "Unite": "Temps", "UtilisableTemps": true, ... },
  { "Code": "C115", "Libelle": "Intégration des relevés bancaires",
    "Unite": "Temps", "UtilisableTemps": true, ... },
  { "Code": "C200", "Libelle": "Révision",
    "Unite": "Temps", "UtilisableTemps": true, ... },
  { "Code": "C500", "Libelle": "Comptes Annuels",
    "Unite": "Temps", "UtilisableTemps": true, ... }
]

Correspondance avec les colonnes du fichier Excel :

• Code → PREST_CODE (ex. C100 pour la tenue de la comptabilité)
• UtilisableTemps = true : la prestation peut être utilisée dans une ligne de temps.

Démarche de génération

1. Récupérer la liste des dossiers : POST /v1/dossiers/filtrer → ADRESSE.ADR_CODE.
2. Récupérer la liste des collaborateurs : GET /v1/collaborateurs → COL_CODE.
3. Se positionner sur un dossier : POST /v2/sessions/dossier.
4. Récupérer les missions du dossier : GET /v1/missions (missions ouvertes : Etat = _ENCOURS) → MISS_CODE et Id de la mission.
5. Récupérer les prestations de la mission : GET /v1/missions/{id}/prestations (prestations où UtilisableTemps = true) → PREST_CODE.
6. Générer le fichier Excel au format .xlsx en renseignant au minimum les colonnes obligatoires (TEMPS_DATE, TEMPS_DUREE…), puis le transmettre au cabinet.

Les étapes 3 à 5 sont à répéter pour chaque dossier concerné.

Exemple de fichier Excel

Exemple d'une ligne de temps pour le dossier DNORD00016, saisie par le collaborateur ED sur la mission COMPTA, avec la prestation C100 (Tenue de la comptabilité) :

Les colonnes facultatives (EXO_CODE, TEMPS_M_…) ne sont pas présentes : l'exercice d'imputation et les montants sont calculés automatiquement à l'import.

Import dans la base de gestion

Le cabinet peut, avec l'outil Import générique :

• importer manuellement les données, en choisissant le fichier Excel à importer ;
• et mettre en place un import automatisé à partir d'un emplacement fixe, par une tâche planifiée Windows.