Import au format JSON
Présentation générale de l'API et finalité fonctionnelle
Cette API permet d'effectuer un import de tous les éléments rattachés aux mouvements comptables au format JSON :
- écritures comptables,
- écritures analytiques,
- comptes généraux,
- tiers,
- axes et sections analytiques,
- journaux,
- gestion des pièces jointes liées aux écritures,
- récupération du lettrage,
- modes de paiements.
Toutes données seront exploitées dans Cegid Loop.
Procédure
Il faut appeler un endpoint permettant d’enregistrer une demande d’import d’écritures au format JSON. Après insertion, un service interne récupèrera la demande pour la traiter et effectuer l’import.
| Route | Méthode http | Description |
|---|---|---|
| /importJson | POST | Insère une demande d’import d’écritures au format JSON |
Paramétrage de l’appel
Méthode http pour la demande : POST
Header(s) attendu(s) obligatoire(s) de la demande : API-KEY
Format du corps de la demande : JSON (format UTF8)
Structure du corps de la demande :
| Clé | Type | Description |
|---|---|---|
| codeIbs | String | Code du dossier dans Loop |
| data | Objet JSON | Objet JSON contenant l’ensemble des paramètres et données à importer |
Structure JSON de l’objet data :
| Clé | Type | Description |
|---|---|---|
| contexte | Object JSON | Objet JSON contenant 2 propriétés, les dates de début et de fin des écritures à importer |
| options | Object JSON | Objet JSON contenant des options de l’import |
| ecritures | Array JSON | Tableau de JSON décrivant une écriture |
Structure JSON de l’objet contexte :
| Clé | Type | Description |
|---|---|---|
| from | String | Date de début des écritures à importer au format iso |
| to | String | Date de fin des écritures à importer au format iso |
Exemple de dates :
- "from" : "2020-02-01T00 :00 :00.000Z"
- "to" : "2020-06-04T00:00:00.000Z"
Notez :
La propriété "contexte" n’est pas obligatoire si l’option multiPeriode vaut true.
Focus sur la notion de multipériode
Cette option devra être utilisée si le contenu du fichier JSON concerne plusieurs périodes ouvertes (excecice en cours et exercice suivant).
Structure JSON de l’objet options :
| Clé | Type | Description |
|---|---|---|
| separatorDecimal | String | Séparateur de décimal pour les montants. "." par défaut. |
| formatDate | String | Format de date à utiliser pour l’import des écritures. JJ/MM/AAAA par défaut. |
| multiPeriode | Boolean | Permet d’indiquer si les écritures sont autorisées sur toutes les périodes ouvertes (true) ou juste sur la dernière période ouverte (false). false par défaut. |
| failOnUnbalanced | Boolean | Permet de déterminer si l’on souhaite lever une erreur en cas de groupes d’écritures non-équilibrés. true par défaut. |
| createNewJournaux | Boolean | Permet d'indiquer s’il faut créer un nouveau journal quand le journal de l’écriture n’existe pas dans le dossier. true par défaut. |
| createNewComptes | Boolean | Permet d'indiquer s’il faut créer un nouveau compte quand le compte de l’écriture n’existe pas dans le dossier. true par défaut. |
| createNewTiers | Boolean | Permet d'indiquer s’il faut créer un nouveau tiers quand le tiers de l’écriture n’existe pas dans le dossier. Si false, alors l’écriture sera créée avec les tiers d’attente de l’écriture. true par défaut. |
| defaultJournalId | String | uuid permettant de spécifier le journal par défaut. null par défaut. |
| sortLines | Boolean | Permet de trier les lignes. false par défaut. |
| comptesRules | Tableau | Permet de gérer les règles de correspondance pour les comptes (correspondance par racine ou par fourchette de compte). null par défaut. |
| newFolio | Boolean | Permet de créer un nouveau groupe. false par défaut. |
| balanceAuto | Boolean | Permet de créer l'équilibrage automatiquement. true par défaut. |
| aNouveaux | Boolean | Permet de gérer les à-nouveaux. true par défaut. |
| defaultCompte | String | uuid du compte à créer par défaut si l'option createNewCompte est à false. null par défaut. |
| createPieceRef | Boolean | Permet de créer la référence de la pièce si aucune pièce n'est trouvée. false par défaut. |
Exemple d'options :
- "separatorDecimal":".",
- "formatDate": "AAAA-MM-JJThh:mm:ss.nnnZ",
- "multiPeriode": false,
- "failOnUnbalanced": true,
- "createNewJournaux": false,
- "createNewComptes": true,
- "createNewTiers": true.
Notez :
La présence d'options dans le fichier n'est pas obligatoire. Les valeurs par défaut sont définis dans le tableau ci-dessus
Structure JSON de l’objet ecritures :
Les différents codes retour en cas de succès
Code retour http de la réponse : 200
Format corps de la réponse : JSON
Structure du corps de la réponse :
| Clé | Type | Valeur |
|---|---|---|
| accountingImportRequestId | String | String sous forme de guid par exemple : "e8bec446-1d5c-4e78-9017-6e2600887a09". Ce guid permettra de suivre la demande via un autre endpoint getImportStatus |
{
"accountingImportRequestId": "97ae1cb4-2ccd-449d-b0b2-582ecbdededd"
}
Les différents codes retour en cas d’erreur
Code retour http de la réponse : 200
Format corps de la réponse : JSON
Structure du corps de la réponse :
| Clé | Type | Valeur |
|---|---|---|
| error | Object JSON | Objet JSON contenant 2 propriétés : instanceId et message |
| instanceId | String | String sous forme de guid correspondant à l’id de l’instance du service d’import |
| message | String | Message explicatif de l’erreur : Cf. liste ci-dessous |
Liste des messages d’erreurs possibles :
- Il n'y a pas de payload : la méthode est-elle bien en POST dans la requête ?
- Le contexte est obligatoire sans l'option multiPeriode
- Il n'y a pas d'écritures à importer (l'objet écritures est vide)
- Les écritures doivent être présentées sous formes de tableau
- Le tableau d'écritures doit comporter au moins deux lignes
- Les dates du contexte doivent être au format ISO 'YYYY-MM-DDTHH:mm:ss.SSSZ'
Dans l’interface des imports partenaires, il n'est pas possible de récupérer les statuts 10 et 20 ("en attente" et "en cours").
En effet, en fin de traitement de l'import via l'API, on aura uniquement les statuts à partir de 25.
Afin de récupérer les statuts "en attente" et "en cours", il faut utiliser l’API "getImportStatus".
Cas spécifiques :
Import avec analytique
Pré-requis :
- La gestion de l'analytique doit être activée dans le dossier Cegid Loop (Configuration>Comptabilité)
- Le compte général doit être ventilable,
- la section et l'axe doivent être renseignés dans le fichier Json,
- si la section n'est pas définie dans le dossier Cegid Loop, elle sera créée lors le l'import,
- l'axe doit obligatoirement être créé dans Cegid Loop au préalable.
{
"axeAnaA1": [
{
"debit": {
"amount": 700,
"currency": "EUR",
"currencyAmount": 700,
"currencyRate": 1
},
"credit": {
"amount": 0,
"currency": "EUR",
"currencyAmount": 0,
"currencyRate": 1
},
"section": "AA1"
},
{
"debit": {
"amount": 300,
"currency": "EUR",
"currencyAmount": 300,
"currencyRate": 1
},
"credit": {
"amount": 0,
"currency": "EUR",
"currencyAmount": 0,
"currencyRate": 1
},
"section": "AB1"
}
],
"axeAnaA2": [
{
"debit": {
"amount": 1000,
"currency": "EUR",
"currencyAmount": 1000,
"currencyRate": 1
},
"credit": {
"amount": 0,
"currency": "EUR",
"currencyAmount": 0,
"currencyRate": 1
},
"section": "AA2"
}
]
}
Import avec lettrage
Pour que le lettrage soit correctement importé :
- Soit le compte général est lettrable, soit le tiers l'est,
- Le code lettrage doit être sur le même compte lettrable,
- Le paquet lettré doit être équilibré (débit = crédit) pour un même compte lettrable.
{
"codeLettrage": "letr1"
}
Import avec pièce jointe
A propos du champ "fichier URI" : Afin que la pièce jointe soit associée à l'écriture, le champ "fichier.uri" doit contenir une URL authentifiée. Celle-ci constituera un lien vers la pièce jointe de l'écriture et sera déposée dans le Sharepoint.
Pré-requis : L'URL ou l'URI pour l'authentification au fichier (pièce jointe liée à l'écritutre comptable) doit être valide pendant au moins 24 heures (recommandation de Microsoft). L'objectif est de pouvoir gérer le processus de "retry" et de suivre les interruptions de service, qu'elles soient volontaires ou involontaires.
{
"fichier": {
"uri": "https://test.rdd.com/piecejointe/123454321234565.txt"
}
}
Exemple de fichier JSON :
{
{
"codeIbs": "IMPORTRAK",
"data": {
"contexte" : {
"from" : "2023-02-01T00:00:00.000Z",
"to" : "2023-06-05T00:00:00.000Z"
},
"options" : {
"separatorDecimal" : ".",
"formatDate" : "AAAA-MM-JJThh:mm:ss.nnnZ",
"multiPeriode" : false,
"failOnUnbalanced" : true,
"createNewJournaux" : true,
"createNewComptes" : true,
"createNewTiers" : true
},
"ecritures" : [
{
"fichier": {
"uri": "https://test.rdd.com/piecejointe/12345432123456543.txt"
},
"date" : "2023-06-02T00:00:00.000Z",
"debit" : {
"amount" : 1000,
"currency" : "EUR",
"currencyAmount" : 1000,
"currencyRate" : 1
},
"credit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"journal" : "ACH",
"compte" : "21860000",
"libelle" : "Facture PC DELL",
"reference" : "FAC-2023-01-29",
"codeLettrage": "letr1",
"ecritureOrigine" : "0d07ade2-c4fa-4892-90bd-2dbd50d1c6b7",
"modePaiement": 9,
"axeAnaA1" : [
{
"debit" : {
"amount" : 700,
"currency" : "EUR",
"currencyAmount" : 700,
"currencyRate" : 1
},
"credit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"section" : "AA1"
},
{
"debit" : {
"amount" : 300,
"currency" : "EUR",
"currencyAmount" : 300,
"currencyRate" : 1
},
"credit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"section" : "AB1"
}
],
"axeAnaA2" : [
{
"debit" : {
"amount" : 1000,
"currency" : "EUR",
"currencyAmount" : 1000,
"currencyRate" : 1
},
"credit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"section" : "AA2"
}
]
},
{
"date" : "2021-06-02T00:00:00.000Z",
"debit" : {
"amount" : 200,
"currency" : "EUR",
"currencyAmount" : 200,
"currencyRate" : 1
},
"credit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"journal" : "ACH",
"compte" : "44562000",
"libelle" : "Facture PC DELL",
"reference" : "FAC-2023-01-29",
"ecritureOrigine" : "0d07ade2-c4fa-4892-90bd-2dbd50d1c6b7"
},
{
"date" : "2023-06-02T00:00:00.000Z",
"debit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"credit" : {
"amount" : 200,
"currency" : "EUR",
"currencyAmount" : 200,
"currencyRate" : 1
},
"journal" : "ACH",
"compte" : "44762000",
"codeLettrage": "letr1",
"tiers" : "DELL",
"tiersLib" : "DELL FRANCE SA",
"libelle" : "Facture PC DELL AVO1",
"reference" : "FAC-2023-01-29",
"ecritureOrigine" : "0d07ade2-c4fa-4892-90bd-2dbd50d1c6b7"
},
{
"date" : "2023-06-02T00:00:00.000Z",
"debit" : {
"amount" : 0,
"currency" : "EUR",
"currencyAmount" : 0,
"currencyRate" : 1
},
"credit" : {
"amount" : 1000,
"currency" : "EUR",
"currencyAmount" : 1000,
"currencyRate" : 1
},
"journal" : "ACH",
"compte" : "41400000",
"codeLettrage": "letr1",
"tiers": "DELL",
"tiersLib": "DELL FRANCE SA",
"libelle" : "Facture PC DELL AVO1",
"reference" : "FAC-2023-01-29",
"ecritureOrigine" : "0d07ade2-c4fa-4892-90bd-2dbd50d1c6b7"
}
]
}
}
}