# 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)