Enhance API parameter documentation and introduce reusable component

- Added a new Blade component `<x-logistics.param-table>` for displaying API parameter tables across all Filament pages, ensuring consistent styling and reducing HTML duplication. - Integrated parameter tables for each endpoint in the Articles, Documents, Divers, Journaux, Tiers, and other pages, providing users with clear reference information. - Updated the documentation to reflect the new structure and details of API parameters, including required fields and descriptions. - Improved user experience by ensuring that endpoints without parameters do not display empty tables. - Overall, enhanced the clarity and usability of API interactions within the application.
2026-02-23 13:55:00 +01:00
parent c84e0c680a
commit bc82299aa6
20 changed files with 989 additions and 178 deletions
--- a/documentation/documentation_api_logistics.md
+++ b/documentation/documentation_api_logistics.md
@@ -13,10 +13,9 @@ Dernière mise à jour : 2026-02-23
 5. [Tables et colonnes disponibles](#5-tables-et-colonnes-disponibles)
 6. [Récupération de données](#6-récupération-de-données)
 7. [Envoi de données](#7-envoi-de-données)
-8. [Endpoints non fonctionnels](#8-endpoints-non-fonctionnels)
-9. [Relations entre entités](#9-relations-entre-entités)
-10. [Remarques et points d'attention](#10-remarques-et-points-dattention)
-11. [Ressources externes](#11-ressources-externes)
+8. [Relations entre entités](#8-relations-entre-entités)
+9. [Remarques et points d'attention](#9-remarques-et-points-dattention)
+10. [Ressources externes](#10-ressources-externes)

 ---

@@ -1254,17 +1253,37 @@ Retourne le numéro de série du dossier comptable. Identifie de manière unique

 **Paramètres** : aucun.

+**Structure de la réponse `data`** :
+
+La clé `data` est un objet contenant une seule clé `getserialnumber` avec le numéro de série sous forme de chaîne.
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `getserialnumber` | `string` | Numéro de série du dossier comptable (ex : `"10005826"`). |
+
 **Exemple de requête** :

 ```json
 {}
 ```

+**Exemple de réponse** :
+
+```json
+{
+    "data": {
+        "getserialnumber": "10005826"
+    },
+    "metadata": { "rowcount": 1, "issuccess": true },
+    "error": null
+}
+```
+
 ---

 #### `codes_list` -- Données par code interne

-Retourne les données associées à un code interne. Les codes proviennent de la table `incodes` et servent à stocker des listes de valeurs paramétrables (types de documents, catégories, etc.).
+Retourne les données associées à un code interne. Les codes proviennent de la table `incodes` et servent à stocker des listes de valeurs paramétrables (types de documents, catégories, délais de paiement, modes de paiement, codes TVA, pays, etc.).

 | | |
 |---|---|
@@ -1275,17 +1294,210 @@ Retourne les données associées à un code interne. Les codes proviennent de la

 | Paramètre | Type | Obligatoire | Description |
 |-----------|------|:-----------:|-------------|
-| `code` | `string` | Oui | Début du code interne à rechercher (de la table `incodes`). Le filtre s'applique par préfixe. |
+| `code` | `string` | Oui | Nom exact du groupe de codes internes (de la table `incodes`). **Correspondance exacte**, pas de filtre par préfixe. **Sensible à la casse** : doit être en MAJUSCULES (ex : `PAYDELAY`, pas `paydelay`). Si la valeur est une chaîne vide (`""`), retourne la liste de tous les groupes de codes disponibles. |

-**Exemple de requête** :
+**Comportement selon la valeur de `code`** :
+
+| Valeur de `code` | Résultat |
+|-------------------|----------|
+| Chaîne vide `""` | Retourne la liste maître de tous les groupes de codes (42 groupes dans le dossier de test). Structure : `name` (identifiant du groupe) + `prompt1` (description en français). |
+| Nom exact d'un groupe (ex : `PAYDELAY`) | Retourne les valeurs du groupe. Structure : `vala1` à `vala6` (chaînes), `valn1`, `valn2` (nombres). |
+| Nom inexistant | Retourne un tableau vide sans erreur. |
+| Nom partiel (ex : `PAY` au lieu de `PAYMODE`) | Retourne un tableau vide (pas de recherche par préfixe). |
+| Minuscules (ex : `paydelay`) | Retourne un tableau vide (sensible à la casse). |
+
+**Body vide (`{}`)** : retourne une erreur HTTP 400.
+
+**Paramètre `select`** : accepté par l'API mais sans effet. Toutes les colonnes sont toujours retournées.
+
+**Structure de la réponse `data` -- mode liste maître (code vide)** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Identifiant unique du groupe de codes (ex : `PAYDELAY`, `PAYMODE`, `VAT`). |
+| `prompt1` | `string` | Description du groupe en français (ex : `"Délais de paiements"`, `"Modes de paiement"`). |
+
+**Structure de la réponse `data` -- mode valeurs d'un groupe** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `vala1` | `string` | Code/valeur principale (ex : `"30"`, `"CAS"`, `"BE"`, `"21"`). |
+| `vala2` | `string` | Description en français (ex : `"30 jours date de facture"`, `"CASH"`, `"BELGIQUE"`, `"Ventes 21 %"`). |
+| `vala3` | `string` | Description en néerlandais ou alternative (ex : `"Belgïe"`, `"exclusief cash"`). Souvent vide. |
+| `vala4` | `string` | Champ texte supplémentaire. Généralement vide. |
+| `vala5` | `string` | Champ texte supplémentaire. Utilisé pour certains codes (ex : codes TVA : `"NSS 21"`). |
+| `vala6` | `string` | Champ texte supplémentaire. Généralement vide. |
+| `valn1` | `int` ou `float` | Valeur numérique 1. Signification variable selon le groupe (ex : pour PAYDELAY = nombre de jours, pour VAT = pourcentage). |
+| `valn2` | `int` ou `float` | Valeur numérique 2. Signification variable selon le groupe. |
+
+**Groupes de codes disponibles** (42 dans le dossier de test) :
+
+| Groupe | Description | Exemples de valeurs (`vala1`) |
+|--------|-------------|-------------------------------|
+| `PAYDELAY` | Délais de paiements | `30`, `30F`, `45F`, `50`, `60`, `60F`, `75F`, `90`, `90F`, `0F` |
+| `PAYMODE` | Modes de paiement | `CAS` (Cash), `VIR` (Virement), `BC` (Bancontact), `CBEF` (Cash BEF) |
+| `VAT` | Codes TVA | `21`, `6`, `0`, `ECEE`, `IEXP`, `MD21`, `ESERV`, `EMD21`, `C` |
+| `VATCAT` | Régime TVA | `N` (Non-assujetti), `R` (Exempté), `` (Assujetti) |
+| `STOCK` | Dépôts / Entrepôts | `A`, `SG` (SEGEC) |
+| `COUNTRY` | Pays | `BE` (Belgique), `FR` (France), `DE` (Allemagne), etc. (31 entrées) |
+| `CUSTTYPE` | Types de tiers | `FOU` (Fournisseur), `CLI` (Client), `PRO` (Prospect), `TRA` (Transporteur) |
+| `LANGUAGE` | Langues | `F` (Français), `N` (Nederlands) |
+| `AGENT` | Agents | `PON`, `FAB`, `TD`, `ESI`, `BPOST`, `LEBA`, etc. |
+| `CATEGORIE` | Catégories d'article | `CARTOUCHE`, `PAPIER`, `TONER`, `CABLE`, `IMPRIMANTE`, etc. (45 entrées) |
+| `MARQUE` | Marques produit | (valeurs disponibles) |
+| `CIVILITY` | Civilité | (valeurs disponibles) |
+| `DLVMODE` | Modes de livraison | (0 valeurs configurées) |
+| `ACCOUNT` | Comptes généraux | (valeurs disponibles) |
+| `ARTFAMILY` | Familles de prix article | (valeurs disponibles) |
+| `CUSTACC` | Catégories comptables client | (valeurs disponibles) |
+| `ARTACC` | Catégories comptables article | (valeurs disponibles) |
+
+**Métadonnées retournées** :
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `rowCount` | `int` | Nombre de résultats retournés. |
+| `source` | `string` | Type de base de données (ex : `DBF`). |
+
+**Exemple de requête -- liste maître** :

 ```json
 {
-    "code": "PAY"
+    "code": ""
 }
 ```

-**Remarque** : les valeurs retournées contiennent des champs `vala1`, `vala2`, etc. dont la signification précise dépend du code recherché.
+**Exemple de réponse -- liste maître** (extrait) :
+
+```json
+{
+    "data": [
+        { "name": "PAYDELAY", "prompt1": "Délais de paiements" },
+        { "name": "PAYMODE", "prompt1": "Modes de paiement" },
+        { "name": "VAT", "prompt1": "Codes TVA" },
+        { "name": "STOCK", "prompt1": "Dépôts" }
+    ],
+    "metadata": { "rowCount": 42, "source": "DBF" },
+    "error": null
+}
+```
+
+**Exemple de requête -- valeurs d'un groupe** :
+
+```json
+{
+    "code": "PAYMODE"
+}
+```
+
+**Exemple de réponse -- valeurs d'un groupe** :
+
+```json
+{
+    "data": [
+        { "vala1": "", "vala2": "", "vala3": "", "vala4": "", "vala5": "", "vala6": "", "valn1": 0, "valn2": 0 },
+        { "vala1": "CAS", "vala2": "CASH", "vala3": "exclusief cash", "vala4": "", "vala5": "", "vala6": "", "valn1": 1, "valn2": 0 },
+        { "vala1": "VIR", "vala2": "Virement", "vala3": "Overschrijving", "vala4": "", "vala5": "", "vala6": "", "valn1": 0, "valn2": 0 },
+        { "vala1": "BC", "vala2": "Bancontact", "vala3": "", "vala4": "", "vala5": "", "vala6": "", "valn1": 4, "valn2": 0 },
+        { "vala1": "CBEF", "vala2": "CASH BEF", "vala3": "", "vala4": "", "vala5": "", "vala6": "", "valn1": 2, "valn2": 0 }
+    ],
+    "metadata": { "rowCount": 5, "source": "DBF" },
+    "error": null
+}
+```
+
+**Remarque** : chaque groupe contient souvent une première entrée avec des valeurs vides (entrée par défaut). La signification exacte des champs `valn1` et `valn2` varie selon le groupe. Par exemple, pour `PAYDELAY`, `valn1` est le nombre de jours et `valn2` semble être un type de calcul (1 = date de facture, 2 = date de facture, 3 = fin de mois). Pour `VAT`, `valn1` et `valn2` sont le pourcentage de TVA.
+
+---
+
+#### `custom_geninv_updatestock` -- Mise à jour du stock
+
+Met à jour le stock d'un article dans un dépôt. Supporte deux modes : inventaire (comptage) et réapprovisionnement (restock). Le mode Restock (MODE=1) est fonctionnel. Le mode Inventaire (MODE=0) nécessite un journal d'inventaire (type KI) configuré pour le dépôt, ce qui peut ne pas être le cas dans tous les dossiers.
+
+| | |
+|---|---|
+| **URL** | `POST /{dossier}/custom_geninv_updatestock` |
+| **Méthode service** | `LogisticsService::customGeninvUpdatestock(array $params)` |
+| **Statut** | Fonctionnel (MODE=1 Restock). MODE=0 Inventaire dépend de la configuration des journaux. |
+
+**Paramètres** :
+
+| Paramètre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `ARTID` | `string` | Oui | Identifiant de l'article (champ `artid` de la table `art`). |
+| `STKID` | `string` | Oui | Code du dépôt / entrepôt. Les valeurs valides sont obtenues via `codes_list` avec `code=STOCK` (ex : `"A"`, `"SG"`). L'API recherche un journal d'inventaire ou de mouvement de stock associé à ce dépôt. |
+| `QTY` | `string` | Oui | Quantité de stock à ajouter. Format string. **Peut être négatif** pour retirer du stock (ex : `"-5"`). |
+| `TOCHECK` | `string` | Oui | Prix de contrôle. La valeur est stockée avec le mouvement d'inventaire mais n'affecte pas directement la quantité de stock. Peut être `"0"` si non pertinent. |
+| `TOCHECKDETAIL` | `string` | Oui | Détail / remarque de contrôle. Texte libre stocké avec le mouvement d'inventaire. Peut être vide `""`. |
+| `MODE` | `string` | Oui | Mode d'opération. `"0"` = Inventaire (comptage/rectification, nécessite journal KI pour le dépôt). `"1"` = Restock / réapprovisionnement (nécessite `THIRDID`). Toute valeur différente de `"0"` est traitée comme Restock. |
+| `THIRDID` | `string` | Conditionnel | Identifiant du tiers (fournisseur). **Obligatoire en mode Restock (MODE != "0")**. Correspond au champ `custid` de la table `cust`. Non utilisé en mode Inventaire. |
+
+**Modes de fonctionnement** :
+
+| MODE | Nom | Description | Prérequis |
+|------|-----|-------------|-----------|
+| `"0"` | Inventaire | Comptage / rectification de stock. Crée un document dans le journal d'inventaire (type KI) du dépôt. | Le dépôt doit avoir un journal de type KI associé (via le champ `STKID` du journal). |
+| `"1"` | Restock | Réapprovisionnement. Enregistre une entrée de marchandise en provenance d'un fournisseur. Crée un document dans le journal de mouvement de stock (type KM) du dépôt. | Le paramètre `THIRDID` doit être fourni (identifiant du fournisseur). |
+
+**Codes d'erreur spécifiques** :
+
+| Code | Message | Description |
+|------|---------|-------------|
+| `002` | `Invalid parameter, inventory JNL not found for warehouse : {STKID}` | Aucun journal d'inventaire n'est configuré pour le dépôt spécifié. Vérifiez que le dépôt a un journal KI (MODE=0) ou KM (MODE=1) associé. |
+| `003` | `Invalid parameter, THIRDID is EMPTY, mandatory in this mode 'Restock'` | Le paramètre `THIRDID` est manquant ou vide alors que le mode Restock est actif. |
+
+**Relation STKID / Journaux** :
+
+Le paramètre `STKID` doit correspondre à un dépôt ayant un journal d'inventaire ou de mouvement de stock configuré. Les journaux de type K (inventaire/stock) et leur STKID associé sont visibles via `jnl_list` avec `TYPE=K` :
+
+| Journal | Type | STKID | Compatibilité MODE |
+|---------|------|-------|---------------------|
+| `INV` (Inventaire) | `KI` | `""` (vide) | MODE=0 (mais dépôt par défaut non résolu dans les tests) |
+| `MVTSG` (Mouvement stock SEGEC) | `KM` | `SG` | MODE=1 (Restock) |
+
+**Structure de la réponse `data` (succès)** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `custom_geninv_updatestock` | `string` | Message de confirmation. Contient l'ARTID, le mode et la quantité appliquée. |
+
+**Exemple de requête (Restock)** :
+
+```json
+{
+    "ARTID": "003R92572",
+    "STKID": "SG",
+    "QTY": "5",
+    "TOCHECK": "12.50",
+    "TOCHECKDETAIL": "Réapprovisionnement fournisseur",
+    "MODE": "1",
+    "THIRDID": "0100002174"
+}
+```
+
+**Exemple de réponse (succès)** :
+
+```json
+{
+    "data": {
+        "custom_geninv_updatestock": "OK : Change applied - Artid : 003R92572            - Real stock received (Restock mode) : 5.00"
+    },
+    "metadata": { "rowcount": 1, "issuccess": true },
+    "error": null
+}
+```
+
+**Exemple de réponse en erreur (journal non trouvé)** :
+
+```json
+{
+    "data": {
+        "xml": "<VFPData><headererror><errorcode>002</errorcode><description>Invalid parameter, inventory JNL not found for warehouse : A</description></headererror></VFPData>"
+    },
+    "metadata": { "rowcount": 1, "issuccess": false },
+    "error": ["Code: 002, Description: Invalid parameter, inventory JNL not found for warehouse : A"]
+}
+```

 ---

@@ -1391,34 +1603,7 @@ Modifie un document existant identifié par son numéro et son journal. Permet d

 ---

-## 8. Endpoints non fonctionnels
-
-Les endpoints suivants ont été identifiés mais ne fonctionnent pas dans l'état actuel ou nécessitent des paramètres dont les valeurs attendues sont inconnues.
-
-### `custom_geninv_updatestock` -- Mise à jour de l'inventaire
-
-| | |
-|---|---|
-| **URL** | `POST /{dossier}/custom_geninv_updatestock` |
-| **Méthode service** | `LogisticsService::customGeninvUpdatestock(array $params)` |
-| **Statut** | Non fonctionnel |
-
-**Paramètres connus** :
-
-| Paramètre | Type | Description |
-|-----------|------|-------------|
-| `ARTID` | `string` | Identifiant de l'article. |
-| `STKID` | `string` | Identifiant du stock. **Valeur attendue inconnue**. |
-| `QTY` | `string` | Quantité à mettre à jour. |
-| `TOCHECK` | `string` | Signification inconnue (possiblement un prix). |
-| `TOCHECKDETAIL` | `string` | Signification inconnue (possiblement des remarques). |
-| `MODE` | `string` | Mode d'opération. Signification inconnue. |
-
-**Problème** : la valeur attendue pour `STKID` est inconnue, et la signification de plusieurs paramètres (`TOCHECK`, `TOCHECKDETAIL`, `MODE`) reste à clarifier auprès du fournisseur.
-
---
-
-## 9. Relations entre entités
+## 8. Relations entre entités

 Les entités du système de gestion sont liées entre elles selon le schéma suivant :

@@ -1449,7 +1634,7 @@ Tiers (cust)

 ---

-## 10. Remarques et points d'attention
+## 9. Remarques et points d'attention

 1. **Dossier en minuscules** : le nom du dossier dans les URLs doit toujours être en minuscules. Exemple : `esigescom`, pas `EsiGescom`. Le non-respect de cette règle provoque une erreur.

@@ -1491,8 +1676,16 @@ Tiers (cust)

 20. **`third_GetArtHistory` -- casse du paramètre** : le paramètre `thirdid` doit être en **minuscules**. `THIRDID` en majuscules provoque une erreur HTTP 400 "thirdid parameter is required.", comme si le paramètre n'avait pas été fourni. L'endpoint retourne l'intégralité de l'historique sans limite (potentiellement des milliers d'éléments).

+21. **`codes_list` -- correspondance exacte et casse** : le paramètre `code` de l'endpoint `codes_list` fonctionne par **correspondance exacte** sur le nom du groupe de codes, pas par préfixe. `code=PAY` retourne 0 résultats ; il faut `code=PAYMODE` ou `code=PAYDELAY` en entier. Le paramètre est **sensible à la casse** : seules les majuscules fonctionnent (`PAYDELAY`, pas `paydelay`). Une chaîne vide (`code=""`) retourne la liste maître de tous les groupes disponibles (42 groupes). Le body vide (`{}`) provoque une erreur HTTP 400.
+
+22. **`codes_list` -- structure de réponse variable** : la structure de `data` diffère selon la valeur de `code`. Avec une chaîne vide, les éléments contiennent `name` et `prompt1`. Avec un nom de groupe valide, les éléments contiennent `vala1` à `vala6` (chaînes) et `valn1`, `valn2` (nombres). La signification de ces champs varie selon le groupe.
+
+23. **`custom_geninv_updatestock` -- fonctionnel en mode Restock** : cet endpoint est fonctionnel en MODE=1 (Restock). Il nécessite 6 paramètres obligatoires (`ARTID`, `STKID`, `QTY`, `TOCHECK`, `TOCHECKDETAIL`, `MODE`) plus `THIRDID` en mode Restock. Le paramètre `STKID` correspond à un code de dépôt (obtenu via `codes_list` avec `code=STOCK`), et le dépôt doit avoir un journal d'inventaire (KI) ou de mouvement de stock (KM) associé. Le MODE=0 (Inventaire) dépend de la configuration des journaux du dossier.
+
+24. **`getserialnumber` -- structure de réponse** : la clé `data` de la réponse est un objet `{ "getserialnumber": "10005826" }` (pas une chaîne directe). Le champ contient le numéro de série du dossier comptable.
+
 ---

-## 11. Ressources externes
+## 10. Ressources externes

 - [Documentation Postman](https://documenter.getpostman.com/view/40440561/2sB2qaj2Pz)