From 2b398bd3b875f64d1808b80fb56a734afbf3fea9 Mon Sep 17 00:00:00 2001 From: fraxken Date: Fri, 27 Sep 2024 21:57:48 +0200 Subject: [PATCH] chore: stage work --- docs/MAD/api/entries.md | 3 - docs/MAD/api/movements.md | 107 +++++++++++++++++++++++++++ docs/MAD/guides/entry-vs-movement.md | 2 + docs/MAD/introduction.md | 23 ++++-- 4 files changed, 125 insertions(+), 10 deletions(-) create mode 100644 docs/MAD/api/movements.md create mode 100644 docs/MAD/guides/entry-vs-movement.md diff --git a/docs/MAD/api/entries.md b/docs/MAD/api/entries.md index 429f81e..b9cc293 100644 --- a/docs/MAD/api/entries.md +++ b/docs/MAD/api/entries.md @@ -47,9 +47,6 @@ Le paramétrage de la route se fait exclusivement par le biais des [querystrings Le JSON renvoyé correspondra à la [spécification suivante](../specs/v1.0.0/entries.md). -> [!CAUTION] -> Pour éviter les extractions abusives nous avons volontairement limité à un exercice par requête API. Si vous souhaitez extraire l'intégralité des mouvements nous vous recommandons d'itérer sur l'intégralité des exercices séquentiellement. - ## 💬 Consulter les écritures sur l'interface MyUnisoft Sur MyUnisoft, il existe plusieurs moyens de récupérer et/ou consulter les écritures: diff --git a/docs/MAD/api/movements.md b/docs/MAD/api/movements.md new file mode 100644 index 0000000..79bb863 --- /dev/null +++ b/docs/MAD/api/movements.md @@ -0,0 +1,107 @@ +--- +prev: + text: 💃 Introduction + link: MAD/introduction.md +next: + text: Écriture et Mouvements (Spec) + link: MAD/specs/v1.0.0/entries.md +--- + +> [!CAUTION] +> Cette API est encore à un stade expérimental et certaines informations peuvent manquer. + +# Export des mouvements + +L'API d'export ci-dessous vous permettra de récupérer les mouvements par deux biais distincts; + +- Avec un [exercice](./exercice.md) +- Sur une période données de maximums **12 mois**. + +Il n'est pas possible de mélanger les deux. + +```bash +curl --location \ +--request GET 'https://api.myunisoft.fr/api/v1/mad/movements?idExercice=1&version=1.0.0' \ +--header 'X-Third-Party-Secret: nompartenaire-L8vlKfjJ5y7zwFj2J49xo53V' \ +--header 'Authorization: Bearer {{API_TOKEN}}' \ +--header 'Content-Type: application/json' +``` + +## 🔧 Paramètres de la requête + +Le paramétrage de la route se fait exclusivement par le biais des [querystrings](https://en.wikipedia.org/wiki/Query_string). + +| nom | description | obligatoire | +| --- | --- | :---: | +| version | version du format | ✔️ | +| idExercice | id exercice | ❌ | +| startDate | Date de début d'extraction au format `YYYYMMDD` | ❌ | +| endDate | Date de fin d'extraction au format `YYYYMMDD` | ❌ | +| classAccount | N'incluent que les comptes démarrant par la class/catégorie fournit | ❌ | + +> [!NOTE] +> L'écart maximum entre la date de début et de fin doit être de maximums 12 mois. + +> [!IMPORTANT] +> 🔹 Accès cabinet +> L'accès cabinet nécessitera la présence de l'en-tête HTTP `society-id` avec l'id du dossier de production (la société concernée par la demande d'extraction). + +## 🔬 Réponse + +Le JSON renvoyé correspondra aux mouvements selon la [spécification suivante](../specs/v1.0.0/entries.md). + +La différence majeure est que les informations liées à l'écriture sont présentes dans un sous-objet `entry`. + +Voici un exemple : + +```json +{ + "producerId": "179953", + "description": "", + "dueDate": null, + "freeNumber": "", + "invoiceNumber": "", + "currency": "EUR", + "value": { + "credit": 3594.3, + "debit": 0, + "amount": 3594.3 + }, + "lettering": { + "state": "none", + "value": null + }, + "entry": { + "producerId": "65771", + "date": "2022-06-30", + "createdAt": 1678132658 + }, + "attachments": {}, + "journal": { + "producerId": "1932", + "customerReferenceCode": "PA", + "name": "JOURNAL PA", + "type": "OD" + }, + "account": { + "producerId": "61440", + "number": "4210000001", + "name": "4210000001" + }, + "payment": null, + "analytics": [] +} +``` + +## 💬 Consulter les mouvements sur l'interface MyUnisoft + +Sur MyUnisoft, il existe plusieurs moyens de récupérer et/ou consulter les écritures: + +- Par le biais de la saisie: `Tenue` > `Saisie/Consultation` > `Saisie` +- Par la **recherche rapide**: accessible via l'icône en forme de loupe en haut à droite. + +![](../../images/quick_search.jpg) + +L'avantage de la première option est qu'elle permet de consulter les factures en attente, ce qui est courant lors d'un import au format JSON nécessitant une étape de validation par le responsable de dossier. + +![](../images/saisie_header.PNG) diff --git a/docs/MAD/guides/entry-vs-movement.md b/docs/MAD/guides/entry-vs-movement.md new file mode 100644 index 0000000..406768d --- /dev/null +++ b/docs/MAD/guides/entry-vs-movement.md @@ -0,0 +1,2 @@ +# Écriture et mouvement: comprendre et choisir la bonne abstraction +TBC diff --git a/docs/MAD/introduction.md b/docs/MAD/introduction.md index 72fb556..6aeb591 100644 --- a/docs/MAD/introduction.md +++ b/docs/MAD/introduction.md @@ -7,9 +7,6 @@ next: false # MAD -> [!WARNING] -> Le format est encore au stade expérimental (des changements sont à prévoir) - MyUnisoft Accounting Data (raccourci en **MAD**) est un format JSON hybride supportant aussi bien l'export que l'import de données comptables. Lors de la conception de ce nouveau format, nos objectifs étaient multiples : @@ -77,17 +74,29 @@ Ces interfaces et types sont régulièrement présents dans les différentes str ## 🌍 API -Les différentes API sont disponibles sur notre [postman en ligne](https://docs.api.myunisoft.fr/) au sein du dossier racine MAD. +Les différentes API sont disponibles sur notre [Postman en ligne](https://docs.api.myunisoft.fr/) dans le dossier racine intitulé **MAD**. > [!IMPORTANT] -> Toutes nos API vous demanderont de fournir le numéro de version MAD. La dernière version est actuellement `1.0.0`. +> Toutes nos API requièrent que vous fournissiez le numéro de version MAD. La dernière version disponible est actuellement `1.0.0` - [Export du dossier de production](./api/accountingFolder.md) -- [Export des écritures et mouvements](./api/entries.md) -- [Récupérer une écriture et ses mouvements](./api/entry.md) - [Export des comptes](./api/account.md) - [Export des journaux](./api/journal.md) - [Export des exercices](./api/exercice.md) - [Export des axes et sections analytiques](./api/analytic.md) - [Export des banques](./api/bank.md) - [Export des méthodes de paiement](./api/payment.md) + +APIs en lien avec les écritures et mouvements; + +- [Export des écritures et mouvements](./api/entries.md) +- [Export des mouvements](./api/movements.md) +- [Récupérer une écriture et ses mouvements](./api/entry.md) + +> [!IMPORTANT] +> Pour éviter les extractions abusives de mouvements, nous avons volontairement limité à un exercice par requête API. +> Si vous souhaitez extraire l'intégralité des mouvements, nous vous recommandons d'itérer séquentiellement sur l'ensemble des exercices. + +## 📌 Guides + +- [Écriture et mouvement: comprendre et choisir la bonne abstraction](./guides/entry-vs-movement.md)