Résumé des différences entre les API V1 et V2

Il existe plusieurs différences notables entre les API Cegid Expert de version 1 (V1) et de version 2 (V2).

Voici les plus importantes.

Changement de contrats

Les contrats des API V2 ont été repensés pour être plus génériques et flexibles.

Cela a entraîné des modifications dans les structures de données, les noms des ressources et les paramètres des requêtes.

La version 1 possède des méthodes spécifiques.
La plupart demandent peu d'informations en entrée et fournissent peu de détail en retour.
L'inconvénient est que cela implique de cumuler les appels pour obtenir une information compète.

La version 2 propose des méthodes plus génériques.
Celles-ci acceptent plus de paramètres en entrée et fournissent plus d'informations en retour.
Cela permet de réduire le nombre d'appels nécessaires pour obtenir une information complète.

Constantes numériques

Cegid Expert utilise de nombreuses valeurs métiers regroupées dans des ensembles nommés "tablettes".

Ces tablettes sont soit paramétrables par l'utilisateur, soit définies par le système (donc constantes).
Ces dernières sont stockées sous la forme de constantes alphanumériques sur 3 caractères.

La version 1 des API Cegid Expert utilise ces constantes alphanumériques, et cela présente quelques inconvénients :

• Sensibilité à la casse ;
• Nécessité de gérer les espaces blancs;
• Fautes de frappe fréquentes ;
• Manque de connaissance des valeurs possibles.

La version 2 des API Cegid Expert utilise des constantes numériques entières pour représenter ces valeurs métiers.

Cette valeur numérique, si l'information est demandée, est systématiquement fournie dans les réponses des API V2.
Elle est souvent accompagnée de la valeur alphanumérique et d'une description correspondant à ce qui est affichée dans les produits Cegid Expert.

Cette valeur numérique, lorsqu'elle est nécessaire, est demandée en entrée à la place de la valeur alphanumérique.

Cette valeur numérique est systématiquement documentée dans l'APIM.

Exemple avec la nature des comptes généraux :

L'API V1 permettant de lire les comptes généraux utilise la valeur alphanumérique "COF" pour désigner un compte collectif fournisseur.

{
  "id": "401100",
  "description": "Fournisseurs",
  "shortDescription": "Fournisseurs",
  "nature": "COF"
}

L'API V2 permettant de lire les comptes généraux utilise la valeur numérique 6 pour désigner un compte collectif fournisseur.
Elle fournit également la valeur alphanumérique et une description correspondant à ce qui est affichée dans les produits Cegid Expert.

{
  "id": "401100",
  "description": "Fournisseurs",
  "shortDescription": "Fournisseurs",
  "natureId": 6,
  "natureCode": "COF",
  "natureDescription": "Compte collectif fournisseur"
}

La valeur numérique 6 pourra être utilisée dans les filtres de recherche pour obtenir uniquement les comptes de cette nature.

{
  "page": {
    "pageIndex": 1,
    "pageSize": 100
  },
  "filters": [
    {
      "property": 2, 
      "constantValue": "6", 
      "comparisonOperateur": 1, 
      "inversion": false, 
      "logicOperator": 1 
    }
  ]
}

Ici, la propriété 2 correspond à la nature des comptes généraux comme indiqué dans l'APIM.

Veuillez vous référer à la documentation sur les filtres pour connaître leur fonctionnement.

Booléens

Les API V1 utilisent parfois des chaînes de caractères pour représenter les valeurs booléennes.
Ainsi les valeurs "X" et "-" sont utilisées pour représenter respectivement les valeurs true et false.

Les API V2 utilisent systématiquement des valeurs booléennes natives (true et false).

Exemple, avec les informations de taxe des comptes généraux :

L'API V1 permettant de lire les comptes généraux avec leurs informations de taxe utilise les chaînes de caractères "X" et "-" pour représenter les valeurs booléennes.

{
  "id": "411000",
   "description": "Clients",
  "shortDescription": "Clients",
  "nature": "COC",
  "nonchargeable": "X",
  "tpf": "   ",
  "vatWithCashing": "   ",
  "vat": "NOR",
  "vatSystem": "   ",
  "subjectedToTPF": "-",
  "vatOnCashing": "-",
  "axe5": "-"
}

L'API V2 utilise des valeurs booléennes natives (true et false).

{
  "id": "411000",
  "description": "Fournisseurs",
  "shortDescription": "Fournisseurs",
  "natureId": 5,
  "natureCode": "COC",
  "natureDescription": "Compte collectif client",
  ...
  "accountTax": {
    "nonchargeable": true,
    "vatSystem": "",
    "vat": "NOR",
    "vatWithCashing": "",
    "vatOnCashing": false,
    tpf": "",
    "subjectedToTPF": false,
    "axe5": false
  }
}

Dates

Les API V1 utilisent parfois des chaînes de caractères au format "dd/MM/yyyy" pour représenter les dates.

Ce format étant dépendant de la culture utilisée, cela peut entraîner des ambiguïtés.

Ainsi, chaque date en V2 doit être représentée au format ISO 8601.
Exemple :
"2026-01-20" pour le 20 janvier 2026.
"2026-01-20T15:30:00" pour le 20 janvier 2026 à 15h30.

Le format ISO 8601 est indépendant de la culture et permet d'éviter les ambiguïtés.

Pour plus d'informations, veuillez vous référer à la documentation sur le format JSON.

Pagination

La majorité des API V2 utilisent un mécanisme de pagination pour limiter le nombre de résultats retournés par une requête et réduire la charge.

Le mécanisme de pagination est décrit en détail dans la section Pagination des principes communs.

Sélection

Dans la version 2 certaines méthodes d’API demanderont un critère optionnel de sélection.

L’objectif est d’éviter de transmettre des données inutiles pour le consommateur et d’alléger la charge.

Le mécanisme de sélection est décrit en détail dans la section Sélection des principes communs.

Mots de passe

Dans une optique de sécurité renforcée, les mots de passes (cryptés en V1) sont remplacés par des mots de passe hachés en V2.

Important

Il est vivement conseillé de passer en version 2 rapidement pour les API renvoyant des mots de passes.
Les méthodes concernées appartiennent au service de lecture des dossiers (CORE System Info).

• GetDossierForUser
• GetListDossier
• GetListDossierForUser
• GetListDossiersPaginated

Jeton invalide

Le retour en cas de jeton invalide a été complété en V2 pour inclure des informations supplémentaires sur l'erreur.

En V1, un simple message est retourné.

{
  "message": "SaasAdmin's token provided is not valid"
}

En V2, un objet d'erreur plus détaillé est retourné.

{
  "type": "System.UnauthorizedAccessException",
  "title": "An error has occurred",
  "status": 401,
  "detail": "Invalid Token",
  "instance": "/GeneralAccountConsultationWebService/ViewGeneralAccountUsingFilter",
  "Code": "Unauthorized"
}