mpa/logisticsAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4aef33f2704d9cc52e9f77794e14c88c92fdcd9e
logisticsAPI/documentation/documentation_api_logistics.md
Marvin 4aef33f270 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

518 lines
15 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink