Implement robust error handling and configuration for Logistics API interactions

- Introduced `LogisticsApiException` to handle connection and request errors with user-friendly messages in French. - Updated `LogisticsService` to include configurable timeout, connection timeout, retry attempts, and sleep duration for retries. - Enhanced error handling in Filament pages to catch `LogisticsApiException` and provide clear feedback to users. - Updated `.env` and `config/logistics.php` to support new configuration options. - Added logging for failed API requests in `api_request_logs`. - Created comprehensive API documentation for Logistics endpoints.
2026-02-20 10:06:04 +01:00
parent 07a3b3a874
commit 4aef33f270
18 changed files with 820 additions and 64 deletions
--- a/documentation/documentation_api_logistics.md
+++ b/documentation/documentation_api_logistics.md
@@ -0,0 +1,517 @@
+# Documentation API Logistics (Flex/ESI Gescom)
+
+Derniere mise a jour : 2026-02-20
+
+---
+
+## Table des matieres
+
+- [Informations generales](#informations-generales)
+- [Authentification](#authentification)
+- [Structure de reponse](#structure-de-reponse)
+- [Tables disponibles](#tables-disponibles)
+- [Endpoints](#endpoints)
+  - [Structure](#structure)
+  - [Articles](#articles)
+  - [Journaux](#journaux)
+  - [Documents](#documents)
+  - [Tiers](#tiers)
+  - [Divers](#divers)
+- [Endpoints non fonctionnels](#endpoints-non-fonctionnels)
+- [Relations entre entites](#relations-entre-entites)
+- [Remarques et points d'attention](#remarques-et-points-dattention)
+
+---
+
+## Informations generales
+
+| Element | Valeur |
+|---------|--------|
+| Serveur | TSE-10-TEST |
+| Hote | `tse-10-test.esiweb.pro` |
+| Port HTTP | 5186 |
+| Port HTTPS | 7126 |
+| Methode | POST (pour tous les endpoints) |
+| Format de reponse | JSON |
+
+L'URL de base de chaque requete suit le schema :
+
+```
+http://<hote>:<port>/<dossier>/<endpoint>
+```
+
+Le nom du dossier **doit etre en minuscules** dans toutes les requetes.
+
+---
+
+## Authentification
+
+Toutes les requetes sont protegees par une cle API. Elle doit etre transmise dans le header HTTP :
+
+| Header | Valeur |
+|--------|--------|
+| `X-API-KEY` | `<votre cle API>` |
+
+Exemple :
+
+```http
+POST /esigescom/tables_list HTTP/1.1
+Host: tse-10-test.esiweb.pro:5186
+X-API-KEY: votre-cle-api
+Content-Type: application/json
+```
+
+---
+
+## Structure de reponse
+
+Tous les endpoints retournent un objet JSON avec la meme structure :
+
+```json
+{
+    "data": "<resultat de la requete>",
+    "metadata": {
+        "rowcount": 0,
+        "issuccess": true
+    },
+    "error": null
+}
+```
+
+| Cle | Type | Description |
+|-----|------|-------------|
+| `data` | mixed | Le resultat de la requete (tableau d'objets, objet, ou null) |
+| `metadata.rowcount` | int | Nombre d'elements retournes |
+| `metadata.issuccess` | bool | Indique si la requete a reussi |
+| `error` | string/null | Message d'erreur en cas d'echec, `null` sinon |
+
+---
+
+## Tables disponibles
+
+Les tables suivantes sont exposees par l'API. Leurs colonnes peuvent etre recuperees via l'endpoint `column_list` et utilisees dans le parametre `select` des endpoints de recherche.
+
+| Table | Description probable | Table | Description probable |
+|-------|---------------------|-------|---------------------|
+| `art` | Articles | `docpay` | Paiements documents |
+| `attach` | Fichiers attaches | `file` | Fichiers |
+| `barcode` | Codes-barres | `hist` | Historique |
+| `category` | Categories | `incodes` | Codes internes |
+| `codes` | Codes | `jnl` | Journaux |
+| `cust` | Clients / Tiers | `pers` | Personnes |
+| `docdet` | Detail documents | `price` | Prix |
+| `dochead` | En-tete documents | `stk` | Stock |
+
+---
+
+## Endpoints
+
+### Structure
+
+Ces endpoints permettent de decouvrir la structure de la base de donnees exposee par l'API.
+
+#### `tables_list` -- Liste des tables
+
+Retourne la liste de toutes les tables accessibles.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/tables_list` |
+| **Parametres** | Aucun |
+
+Exemple de reponse :
+
+```json
+{
+    "data": ["art", "attach", "barcode", "category", "codes", "cust", "docdet", "dochead", "docpay", "file", "hist", "incodes", "jnl", "pers", "price", "stk"],
+    "metadata": { "rowcount": 16, "issuccess": true },
+    "error": null
+}
+```
+
+---
+
+#### `column_list/{tablename}` -- Colonnes d'une table
+
+Retourne la liste des colonnes d'une table donnee. Utile pour connaitre les champs utilisables dans le parametre `select` des autres endpoints.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/column_list/{tablename}` |
+| **Parametres** | `tablename` dans l'URL (nom de la table, issu de `tables_list`) |
+
+---
+
+### Articles
+
+Un document contient un ou plusieurs articles. Les articles sont stockes dans la table `art`.
+
+#### `art_list` -- Recherche d'articles
+
+Retourne une liste d'articles correspondant aux criteres de recherche.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/art_list` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `select` | string | Non | Colonnes a retourner (colonnes de la table `art`) |
+| `results` | int | Non | Nombre de resultats a retourner |
+| `search` | string | Non | Filtre de recherche |
+| `barcode` | string | Non | Code-barres de l'article |
+
+Remarque : lors d'une recherche par `barcode`, le parametre `search` n'est pas requis.
+
+---
+
+#### `art_getstk` -- Stock d'un article
+
+Retourne les informations de stock pour un article donne.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/art_getstk` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `ARTID` | string | Oui | Identifiant de l'article |
+
+---
+
+### Journaux
+
+Un journal contient un ou plusieurs documents. Les journaux sont stockes dans la table `jnl`.
+
+#### `jnl_list` -- Liste des journaux
+
+Retourne la liste des journaux correspondant aux criteres.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/jnl_list` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `select` | string | Non | Colonnes a retourner (colonnes de la table `jnl`) |
+| `results` | int | Non | Nombre de resultats a retourner |
+| `TYPE` | string | Oui | Code de type de journal |
+
+---
+
+### Documents
+
+Un journal contient un ou plusieurs documents, et un document contient un ou plusieurs articles. Les en-tetes de documents sont dans la table `dochead`, les lignes de detail dans `docdet`.
+
+#### `document_list` -- Liste des documents
+
+Retourne une liste de documents, eventuellement filtree par tiers.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/document_list` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `select` | string | Non | Colonnes a retourner (colonnes de la table `dochead`) |
+| `thirdid` | string | Non | Identifiant du tiers (`custid` de la table `cust`) |
+
+---
+
+#### `document_detail` -- Detail d'un document
+
+Retourne le detail complet d'un document (en-tete + lignes).
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/document_detail` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `jnl` | string | Oui | Code du journal |
+| `number` | string | Oui | Identifiant du document |
+
+---
+
+#### `document_add` -- Ajout d'un document
+
+Cree un nouveau document dans un journal.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/document_add` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `ThirdId` | string | Oui | Identifiant du tiers (`custid` de la table `cust`) |
+| `Date` | string | Oui | Date d'encodage |
+| `Artid` | array | Oui | Tableau d'identifiants d'articles (`artid` de la table `art`) |
+| `Qty` | array | Oui | Tableau de quantites (correspond position par position a `Artid`) |
+| `Saleprice` | array | Oui | Tableau des prix de vente unitaires |
+| `JNL` | string | Oui | Code du journal affecte |
+| `Discount` | array | Non | Tableau des reductions de prix |
+| `Vatid` | array | Non | Tableau des identifiants de TVA |
+| `Vatpc` | array | Non | Tableau des pourcentages de TVA |
+| `Attachments` | array | Non | Liste de fichiers joints (voir structure ci-dessous) |
+
+Structure d'un element `Attachments` :
+
+| Cle | Type | Description |
+|-----|------|-------------|
+| `FileName` | string | Nom du fichier avec extension (ex: `facture.pdf`) |
+| `FileDesc` | string | Description du fichier |
+| `FileContentBase64` | string | Contenu du fichier encode en base64 |
+
+Exemple de body :
+
+```json
+{
+    "ThirdId": "CUST001",
+    "Date": "2026-02-20",
+    "Artid": ["ART001", "ART002"],
+    "Qty": ["2", "5"],
+    "Saleprice": ["10.00", "25.50"],
+    "JNL": "VEN",
+    "Attachments": [
+        {
+            "FileName": "bon.pdf",
+            "FileDesc": "Bon de commande",
+            "FileContentBase64": "JVBERi0xLjQK..."
+        }
+    ]
+}
+```
+
+---
+
+#### `document_mod` -- Modification d'un document
+
+Modifie un document existant. Le parametre `number` identifie le document a modifier.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/document_mod` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `number` | string | Oui | Identifiant du document a modifier |
+| `JNL` | string | Oui | Code du journal lie au document |
+| `Thirdid` | string | Non | Identifiant du tiers |
+| `Artid` | array | Non | Tableau d'identifiants d'articles |
+| `Qty` | array | Non | Tableau de quantites |
+| `Saleprice` | array | Non | Tableau des prix de vente |
+| `Attachments` | array | Non | Liste de fichiers joints (meme structure que `document_add`) |
+
+---
+
+#### `Document_GetStatusList` -- Statuts d'un journal
+
+Retourne la liste des statuts disponibles pour les documents d'un journal.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/Document_GetStatusList` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `jnl` | string | Oui | Code du journal |
+
+---
+
+#### `Document_GetUnitPriceAndVat` -- Prix unitaire et TVA
+
+Retourne le prix unitaire et la TVA pour un article dans un contexte donne (journal, tiers, date).
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/Document_GetUnitPriceAndVat` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `ARTID` | string | Oui | Identifiant de l'article |
+| `QTY` | string | Oui | Quantite (format string obligatoire) |
+| `JNL` | string | Oui | Code du journal |
+| `THIRDID` | string | Oui | Identifiant du tiers (`custid` de la table `cust`) |
+| `DATE` | string | Oui | Date |
+
+---
+
+#### `Document_GetDueDate` -- Echeance de paiement
+
+Calcule la date d'echeance a partir d'un type de delai de paiement et d'une date de depart.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/Document_GetDueDate` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `paydelay` | string | Oui | Type de delai de paiement |
+| `date` | string | Oui | Date de depart |
+
+---
+
+#### `Document_GetAttachListThumbnail` -- Miniatures des annexes
+
+Retourne les miniatures des fichiers attaches a un document. Seuls les fichiers de type image sont concernes.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/Document_GetAttachListThumbnail` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `JNL` | string | Oui | Code du journal |
+| `NUMBER` | string | Oui | Identifiant du document |
+
+---
+
+### Tiers
+
+Un tiers (client) possede un ou plusieurs documents. Les tiers sont stockes dans la table `cust`.
+
+#### `third_list` -- Liste des tiers
+
+Retourne une liste de tiers correspondant au filtre de recherche.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/third_list` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `select` | string | Non | Colonnes a retourner (colonnes de la table `cust`) |
+| `results` | int | Non | Nombre de resultats a retourner |
+| `search` | string | Oui | Filtre de recherche |
+
+---
+
+#### `third_GetArtHistory` -- Historique articles d'un tiers
+
+Retourne l'historique des articles des documents associes a un tiers.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/third_GetArtHistory` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `thirdid` | string | Oui | Identifiant du tiers |
+
+---
+
+### Divers
+
+#### `getserialnumber` -- Numero de serie
+
+Retourne le numero de serie du dossier.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/getserialnumber` |
+| **Parametres** | Aucun |
+
+---
+
+#### `codes_list` -- Donnees par code
+
+Retourne des donnees associees a un code interne. Les codes proviennent de la table `incodes`.
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/codes_list` |
+
+| Parametre | Type | Obligatoire | Description |
+|-----------|------|:-----------:|-------------|
+| `code` | string | Oui | Debut de code (de la table `incodes`) |
+
+Remarque : les valeurs retournees contiennent des champs `vala1`, `vala2`, etc. dont la signification precise reste a documenter.
+
+---
+
+## Endpoints non fonctionnels
+
+Les endpoints suivants ont ete testes mais ne fonctionnent pas ou necessitent des parametres inconnus.
+
+#### `Document_GetPDF` -- Generation de PDF
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/Document_GetPDF` |
+| **Statut** | Non fonctionnel |
+
+| Parametre | Type | Description |
+|-----------|------|-------------|
+| `JNL` | string | Code du journal |
+| `NUMBER` | string | Identifiant du document |
+| `LAYOUT` | string | Inconnu -- parametre requis mais valeur non documentee |
+
+Probleme : la valeur attendue pour le parametre `LAYOUT` est inconnue. L'endpoint retourne une erreur sans ce parametre.
+
+---
+
+#### `custom_geninv_updatestock` -- Mise a jour de l'inventaire
+
+| | |
+|---|---|
+| **URL** | `POST /<dossier>/custom_geninv_updatestock` |
+| **Statut** | Non fonctionnel |
+
+| Parametre | Type | Description |
+|-----------|------|-------------|
+| `ARTID` | string | Identifiant de l'article |
+| `STKID` | string | Identifiant du stock -- valeur inconnue |
+| `QTY` | string | Quantite a mettre a jour |
+| `TOCHECK` | string | Signification inconnue (prix ?) |
+| `TOCHECKDETAIL` | string | Signification inconnue (remarques ?) |
+| `MODE` | string | Signification inconnue |
+
+Probleme : la valeur attendue pour `STKID` est inconnue, et la signification de plusieurs parametres reste a clarifier.
+
+---
+
+## Relations entre entites
+
+```
+Tiers (cust)
+  |
+  +-- possede un ou plusieurs --> Documents (dochead / docdet)
+                                    |
+                                    +-- appartient a un --> Journal (jnl)
+                                    |
+                                    +-- contient un ou plusieurs --> Articles (art)
+                                    |
+                                    +-- peut avoir des --> Fichiers attaches (attach)
+```
+
+- Un **tiers** (`cust`) est un client qui peut avoir plusieurs documents.
+- Un **journal** (`jnl`) regroupe plusieurs documents du meme type.
+- Un **document** (`dochead` pour l'en-tete, `docdet` pour les lignes) appartient a un journal et est associe a un tiers.
+- Un **article** (`art`) est une reference produit. Chaque ligne de document fait reference a un article avec une quantite et un prix.
+- Le **stock** (`stk`) contient les quantites en stock par article.
+
+---
+
+## Remarques et points d'attention
+
+1. **Dossier en minuscules** : le nom du dossier dans les URLs doit toujours etre en minuscules. Exemple : `esigescom`, pas `EsiGescom`.
+
+2. **Methode POST uniquement** : tous les endpoints utilisent la methode POST, meme pour les operations de lecture.
+
+3. **Parametre `QTY`** : dans l'endpoint `Document_GetUnitPriceAndVat`, le parametre `QTY` doit etre au format string, pas numerique.
+
+4. **Parametre `search` obligatoire** : pour `third_list`, le parametre `search` est obligatoire. Un appel sans filtre retournera une erreur.
+
+5. **Parametre `results`** : limite le nombre de resultats retournes. Par defaut, l'API retourne un nombre reduit de resultats (environ 5 a 10).
+
+6. **Parametre `select`** : permet de specifier les colonnes a retourner. Les noms de colonnes disponibles pour chaque table peuvent etre obtenus via `column_list/{tablename}`.
+
+7. **Fichiers attaches** : lors de l'ajout ou la modification de documents, les fichiers doivent etre encodes en base64 dans le champ `FileContentBase64`.
+
+8. **Identifiant tiers** : les parametres `thirdid`, `Thirdid` et `THIRDID` font tous reference au champ `custid` de la table `cust`, mais la casse varie selon l'endpoint.
+
+---
+
+## Ressources externes
+
+- [Documentation Postman](https://documenter.getpostman.com/view/40440561/2sB2qaj2Pz)