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/app/Filament/Pages/Articles.php
+++ b/app/Filament/Pages/Articles.php
@@ -42,6 +42,28 @@ class Articles extends Page

    public bool $hasCheckedStock = false;

+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableArtList(): array
+    {
+        return [
+            ['name' => 'search', 'type' => 'string', 'required' => 'Oui', 'description' => 'Filtre de recherche textuel. Recherche dans artid et name1. Obligatoire.'],
+            ['name' => 'select', 'type' => 'string', 'required' => 'Non', 'description' => 'Colonnes a retourner, separees par des virgules (colonnes de la table art).'],
+            ['name' => 'barcode', 'type' => 'string', 'required' => 'Non', 'description' => 'Sans effet observable. Le parametre search reste obligatoire meme si barcode est fourni.'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableArtGetstk(): array
+    {
+        return [
+            ['name' => 'ARTID', 'type' => 'string', 'required' => 'Oui', 'description' => "Identifiant unique de l'article (champ artid de la table art)."],
+        ];
+    }
+
    public function searchArticles(): void
    {
        $this->errorMessage = null;
--- a/app/Filament/Pages/Divers.php
+++ b/app/Filament/Pages/Divers.php
@@ -28,6 +28,8 @@ class Divers extends Page
    // codes_list
    public string $code = '';

+    public string $codesSelect = '';
+
    public array $codesData = [];

    // custom_geninv_updatestock
@@ -41,7 +43,9 @@ class Divers extends Page

    public string $stkToCheckDetail = '';

-    public string $stkMode = '';
+    public string $stkMode = '1';
+
+    public string $stkThirdId = '';

    public array $updateStockResult = [];

@@ -54,6 +58,33 @@ class Divers extends Page

    public bool $hasUpdatedStock = false;

+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableCodesList(): array
+    {
+        return [
+            ['name' => 'code', 'type' => 'string', 'required' => 'Oui', 'description' => 'Nom exact du groupe de codes internes (table incodes). Correspondance exacte, sensible a la casse (MAJUSCULES). Chaine vide pour la liste maitre.'],
+            ['name' => 'select', 'type' => 'string', 'required' => 'Non', 'description' => 'Sans effet. Toutes les colonnes sont toujours retournees.'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableUpdateStock(): array
+    {
+        return [
+            ['name' => 'ARTID', 'type' => 'string', 'required' => 'Oui', 'description' => 'Identifiant de l\'article (champ artid de la table art).'],
+            ['name' => 'STKID', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du depot / entrepot. Valeurs via codes_list STOCK (ex: A, SG).'],
+            ['name' => 'QTY', 'type' => 'string', 'required' => 'Oui', 'description' => 'Quantite a ajouter au stock. Peut etre negatif pour retirer du stock.'],
+            ['name' => 'MODE', 'type' => 'string', 'required' => 'Oui', 'description' => '"0" = Inventaire (journal KI). "1" = Restock (journal KM, necessite THIRDID).'],
+            ['name' => 'THIRDID', 'type' => 'string', 'required' => 'Si MODE=1', 'description' => 'Identifiant du tiers / fournisseur (custid de la table cust). Obligatoire en mode Restock.'],
+            ['name' => 'TOCHECK', 'type' => 'string', 'required' => 'Oui', 'description' => 'Prix de controle. Stocke avec le mouvement mais n\'affecte pas la quantite de stock.'],
+            ['name' => 'TOCHECKDETAIL', 'type' => 'string', 'required' => 'Oui', 'description' => 'Remarque / detail de controle. Texte libre stocke avec le mouvement.'],
+        ];
+    }
+
    public function getSerialNumber(): void
    {
        $this->errorMessage = null;
@@ -88,7 +119,13 @@ class Divers extends Page

        try {
            $service = app(LogisticsService::class);
-            $response = $service->codesList(['code' => $this->code]);
+            $params = ['code' => $this->code];
+
+            if (filled($this->codesSelect)) {
+                $params['select'] = $this->codesSelect;
+            }
+
+            $response = $service->codesList($params);

            $this->codesData = $response['data'] ?? [];
            $this->errorMessage = ApiErrorTranslator::translate($response['error'] ?? null);
@@ -105,8 +142,14 @@ class Divers extends Page
    {
        $this->errorMessage = null;

-        if (blank($this->stkArtId) || blank($this->stkId) || blank($this->stkQty)) {
-            $this->errorMessage = 'Les champs ARTID, STKID et QTY sont obligatoires.';
+        if (blank($this->stkArtId) || blank($this->stkId) || blank($this->stkQty) || blank($this->stkMode)) {
+            $this->errorMessage = 'Les champs ARTID, STKID, QTY et MODE sont obligatoires.';
+
+            return;
+        }
+
+        if ($this->stkMode === '1' && blank($this->stkThirdId)) {
+            $this->errorMessage = 'Le champ THIRDID est obligatoire en mode Restock (MODE=1).';

            return;
        }
@@ -116,14 +159,18 @@ class Divers extends Page
        try {
            $service = app(LogisticsService::class);

-            $params = array_filter([
+            $params = [
                'ARTID' => $this->stkArtId,
                'STKID' => $this->stkId,
                'QTY' => $this->stkQty,
                'TOCHECK' => $this->stkToCheck,
                'TOCHECKDETAIL' => $this->stkToCheckDetail,
                'MODE' => $this->stkMode,
-            ]);
+            ];
+
+            if (filled($this->stkThirdId)) {
+                $params['THIRDID'] = $this->stkThirdId;
+            }

            $response = $service->customGeninvUpdatestock($params);

--- a/app/Filament/Pages/Documents.php
+++ b/app/Filament/Pages/Documents.php
@@ -139,6 +139,120 @@ class Documents extends Page

    public bool $hasModified = false;

+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableDocumentList(): array
+    {
+        return [
+            ['name' => 'select', 'type' => 'string', 'required' => 'Non', 'description' => 'Colonnes a retourner, separees par des virgules (colonnes de la table dochead). Par defaut : thirdid.'],
+            ['name' => 'thirdid', 'type' => 'string', 'required' => 'Non', 'description' => 'Identifiant du tiers (custid de la table cust). Si fourni, seuls les documents de ce tiers sont retournes.'],
+            ['name' => 'results', 'type' => 'string', 'required' => 'Non', 'description' => "Nombre maximum de resultats. N'a d'effet que lorsqu'un thirdid est egalement fourni. Limite par defaut : ~108."],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableDocumentDetail(): array
+    {
+        return [
+            ['name' => 'jnl', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal auquel appartient le document (ex : 03VEN, 01COM).'],
+            ['name' => 'number', 'type' => 'string', 'required' => 'Oui', 'description' => 'Numero du document dans le journal (ex : 25105397).'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableStatusList(): array
+    {
+        return [
+            ['name' => 'jnl', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal dont on veut connaitre les statuts (ex : 03VEN, 01COM, 02NEV).'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableUnitPriceAndVat(): array
+    {
+        return [
+            ['name' => 'ARTID', 'type' => 'string', 'required' => 'Oui', 'description' => "Identifiant de l'article (champ artid de la table art)."],
+            ['name' => 'QTY', 'type' => 'string', 'required' => 'Oui', 'description' => 'Quantite demandee. Doit etre au format string (ex : "2", pas 2).'],
+            ['name' => 'JNL', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal (ex : 03VEN).'],
+            ['name' => 'THIRDID', 'type' => 'string', 'required' => 'Oui', 'description' => 'Identifiant du tiers (custid de la table cust).'],
+            ['name' => 'DATE', 'type' => 'string', 'required' => 'Oui', 'description' => 'Date de reference. Format obligatoire : YYYY-MM-DD.'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableDueDate(): array
+    {
+        return [
+            ['name' => 'paydelay', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code de delai de paiement. Valeurs via codes_list PAYDELAY (ex : 30, 30F, 60, 60F, 90F).'],
+            ['name' => 'date', 'type' => 'string', 'required' => 'Oui', 'description' => 'Date de depart pour le calcul. Format obligatoire : YYYY-MM-DD.'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableAttachListThumbnail(): array
+    {
+        return [
+            ['name' => 'JNL', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal du document (ex : 03VEN).'],
+            ['name' => 'NUMBER', 'type' => 'string', 'required' => 'Oui', 'description' => 'Numero du document (ex : 25105397).'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableGetPdf(): array
+    {
+        return [
+            ['name' => 'JNL', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal (ex : 03VEN).'],
+            ['name' => 'NUMBER', 'type' => 'string', 'required' => 'Oui', 'description' => 'Numero du document (ex : 25105397).'],
+            ['name' => 'LAYOUT', 'type' => 'string', 'required' => 'Oui', 'description' => 'Identifiant numerique de la mise en page (format string). Valeur "1" recommandee par defaut.'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableDocumentAdd(): array
+    {
+        return [
+            ['name' => 'ThirdId', 'type' => 'string', 'required' => 'Oui', 'description' => 'Identifiant du tiers (custid de la table cust).'],
+            ['name' => 'Date', 'type' => 'string', 'required' => 'Oui', 'description' => "Date d'encodage du document (ex : 2026-02-20)."],
+            ['name' => 'JNL', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal (ex : VEN).'],
+            ['name' => 'Artid', 'type' => 'array', 'required' => 'Oui', 'description' => "Tableau d'identifiants d'articles. Chaque element correspond a une ligne du document."],
+            ['name' => 'Qty', 'type' => 'array', 'required' => 'Oui', 'description' => 'Tableau de quantites (format string). Correspondance positionnelle avec Artid.'],
+            ['name' => 'Saleprice', 'type' => 'array', 'required' => 'Oui', 'description' => 'Tableau des prix de vente unitaires (format string). Correspondance positionnelle avec Artid.'],
+            ['name' => 'Discount', 'type' => 'array', 'required' => 'Non', 'description' => 'Tableau des reductions de prix. Correspondance positionnelle avec Artid.'],
+            ['name' => 'Vatid', 'type' => 'array', 'required' => 'Non', 'description' => 'Tableau des identifiants de code TVA. Correspondance positionnelle avec Artid.'],
+            ['name' => 'Vatpc', 'type' => 'array', 'required' => 'Non', 'description' => 'Tableau des pourcentages de TVA. Correspondance positionnelle avec Artid.'],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableDocumentMod(): array
+    {
+        return [
+            ['name' => 'number', 'type' => 'string', 'required' => 'Oui', 'description' => 'Identifiant du document a modifier (ex : 2026/0001).'],
+            ['name' => 'JNL', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code du journal lie au document (ex : VEN).'],
+            ['name' => 'Thirdid', 'type' => 'string', 'required' => 'Non', 'description' => 'Nouvel identifiant du tiers (si modification du tiers associe).'],
+            ['name' => 'Artid', 'type' => 'array', 'required' => 'Non', 'description' => "Tableau d'identifiants d'articles (remplace les lignes existantes)."],
+            ['name' => 'Qty', 'type' => 'array', 'required' => 'Non', 'description' => 'Tableau de quantites. Correspondance positionnelle avec Artid.'],
+            ['name' => 'Saleprice', 'type' => 'array', 'required' => 'Non', 'description' => 'Tableau des prix de vente unitaires. Correspondance positionnelle avec Artid.'],
+        ];
+    }
+
    public function searchDocuments(): void
    {
        $this->errorMessage = null;
--- a/app/Filament/Pages/Journaux.php
+++ b/app/Filament/Pages/Journaux.php
@@ -36,6 +36,18 @@ class Journaux extends Page

    public bool $hasSearched = false;

+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableJnlList(): array
+    {
+        return [
+            ['name' => 'TYPE', 'type' => 'string', 'required' => 'Oui', 'description' => 'Code de type de journal (1 ou 2 caracteres). Ex: C=Client, S=Fournisseur, K=Stock, CI=Facture client, CO=Commande.'],
+            ['name' => 'select', 'type' => 'string', 'required' => 'Non', 'description' => 'Colonnes a retourner, separees par des virgules (colonnes de la table jnl). Si omis, seule la colonne jnl est retournee.'],
+            ['name' => 'results', 'type' => 'string', 'required' => 'Non', 'description' => 'Nombre maximum de resultats. Doit etre au format string. Limite par defaut : 30.'],
+        ];
+    }
+
    public function searchJournaux(): void
    {
        $this->errorMessage = null;
--- a/app/Filament/Pages/Tiers.php
+++ b/app/Filament/Pages/Tiers.php
@@ -42,6 +42,28 @@ class Tiers extends Page

    public bool $hasHistory = false;

+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableThirdList(): array
+    {
+        return [
+            ['name' => 'search', 'type' => 'string', 'required' => 'Oui', 'description' => 'Filtre de recherche textuel. Recherche dans name, groupid et vat (pas dans custid). Obligatoire.'],
+            ['name' => 'select', 'type' => 'string', 'required' => 'Non', 'description' => 'Colonnes a retourner, separees par des virgules. Par defaut : custid, name.'],
+            ['name' => 'results', 'type' => 'int', 'required' => 'Non', 'description' => "Sans effet. L'API retourne toujours un maximum de 10 resultats."],
+        ];
+    }
+
+    /**
+     * @return array<int, array{name: string, type: string, required: string, description: string}>
+     */
+    public function paramTableArtHistory(): array
+    {
+        return [
+            ['name' => 'thirdid', 'type' => 'string', 'required' => 'Oui', 'description' => 'Identifiant du tiers (custid de la table cust). Sensible a la casse : doit etre en minuscules (thirdid, pas THIRDID).'],
+        ];
+    }
+
    public function searchTiers(): void
    {
        $this->errorMessage = null;