logisticsAPI/documentation/documentation_api_logistics.md

Documentation API Logistics (Flex/ESI Gescom)

Dernière mise à jour : 2026-02-23

---

Table des matières

1. Pré-requis
2. Environnements d'utilisation
3. Comment effectuer des requêtes
4. Structure de réponse
5. Tables et colonnes disponibles
6. Récupération de données
7. Envoi de données
8. Endpoints non fonctionnels
9. Relations entre entités
10. Remarques et points d'attention
11. Ressources externes

---

1. Pré-requis

Connexion VPN

L'API Logistics est hébergée sur l'infrastructure ESI Cloud. Pour y accéder depuis un poste de travail local (hors du réseau ESI), une connexion VPN vers ESI Cloud est obligatoire. Sans cette connexion VPN, le serveur n'est pas joignable. Contactez votre administrateur réseau pour obtenir les identifiants et la configuration du VPN.

Accès au serveur

L'API Logistics est hébergée sur un serveur privé. Les informations de connexion sont les suivantes :

Élément	Valeur
Serveur	TSE-10-TEST
Hôte	tse-10-test.esiweb.pro (public) / tse-10-test.esi.local (réseau privé)
Port HTTP	5186
Port HTTPS	7126

L'accès au serveur nécessite soit une connexion au réseau privé (via VPN), soit l'utilisation de l'hôte public avec le port adéquat.

Clé API

Toutes les requêtes sont protégées par une clé API. Cette clé doit être transmise dans le header HTTP X-API-KEY de chaque requête. Sans clé valide, l'API retourne une erreur d'authentification.

Dossier

Chaque requête cible un dossier comptable spécifique. Le nom du dossier est inclus dans l'URL de la requête. Le nom du dossier doit impérativement être en minuscules dans toutes les URLs (exemple : esigescom, et non EsiGescom).

Variables d'environnement

L'application Laravel utilise les variables d'environnement suivantes pour se connecter à l'API. Elles doivent être configurées dans le fichier .env :

Variable	Description	Exemple
LOGISTICS_API_BASE_URL	URL de base du serveur API	http://tse-10-test.esi.local
LOGISTICS_API_KEY	Clé d'authentification API	YOUR_API_KEY
LOGISTICS_API_FOLDER	Nom du dossier comptable (minuscules)	esigescom
LOGISTICS_API_TIMEOUT	Timeout total de la requête en secondes	300
LOGISTICS_API_CONNECT_TIMEOUT	Timeout de connexion en secondes	10
LOGISTICS_API_RETRY_TIMES	Nombre de tentatives en cas d'échec de connexion	3
LOGISTICS_API_RETRY_SLEEP_MS	Délai entre les tentatives en millisecondes	500

Configuration Laravel

Les variables d'environnement sont lues par le fichier de configuration config/logistics.php :

Clé de config	Variable .env	Défaut
logistics.base_url	LOGISTICS_API_BASE_URL	-
logistics.api_key	LOGISTICS_API_KEY	-
logistics.folder	LOGISTICS_API_FOLDER	-
logistics.timeout	LOGISTICS_API_TIMEOUT	30
logistics.connect_timeout	LOGISTICS_API_CONNECT_TIMEOUT	10
logistics.retry.times	LOGISTICS_API_RETRY_TIMES	3
logistics.retry.sleep_ms	LOGISTICS_API_RETRY_SLEEP_MS	500

Le service App\Services\LogisticsService utilise ces valeurs pour configurer automatiquement les appels HTTP (URL, headers, timeouts, retry). En cas d'échec de connexion, le service effectue un retry automatique selon la configuration.

---

2. Environnements d'utilisation

L'API Logistics peut être interrogée depuis deux environnements distincts. Selon l'environnement utilisé, l'URL de base et les conditions d'accès diffèrent.

2.1 Projet local avec VPN

Dans ce scénario, le développeur travaille sur son poste local (par exemple avec Laravel Herd) et communique avec le serveur Logistics à distance via le VPN ESI Cloud.

Élément	Valeur
Connexion VPN	Obligatoire (VPN vers ESI Cloud)
URL de base	http://tse-10-test.esi.local
Format d'URL complet	http://tse-10-test.esi.local/{dossier}/{endpoint}

Exemple de configuration .env pour un projet local :

LOGISTICS_API_BASE_URL=http://tse-10-test.esi.local
LOGISTICS_API_KEY=votre-cle-api
LOGISTICS_API_FOLDER=esigescom

2.2 Bureau à distance (Postman)

Dans ce scénario, l'utilisateur se connecte au serveur via une connexion de bureau à distance (Remote Desktop) et utilise Postman directement depuis cette session. Étant déjà sur le réseau interne, aucun VPN n'est nécessaire et le serveur est accessible directement.

Élément	Valeur
Connexion VPN	Non requise (connexion directe via bureau à distance)
URL de base	http://tse-10-test.esiweb.pro
Format d'URL complet	http://tse-10-test.esiweb.pro/{dossier}/{endpoint}

Pour obtenir un accès au bureau à distance et à l'application Logistics, contactez Claudi Dewandre.

2.3 Récapitulatif des différences

Critère	Projet local (VPN)	Bureau à distance (Postman)
VPN ESI Cloud	Obligatoire	Non requis
Outil	Application Laravel, cURL, Postman local	Postman sur le serveur distant
URL de base	http://tse-10-test.esi.local	http://tse-10-test.esiweb.pro
Accès requis	Identifiants VPN + clé API	Accès bureau à distance + accès Logistics (contacter Claudi Dewandre) + clé API

---

3. Comment effectuer des requêtes

Méthode HTTP

Tous les endpoints utilisent la méthode POST, y compris les opérations de lecture. Aucun endpoint ne répond aux méthodes GET, PUT, PATCH ou DELETE.

Format de l'URL

L'URL de chaque requête suit le schéma suivant :

POST {base_url}/{dossier}/{endpoint}

Où :

• {base_url} est l'URL de base du serveur (ex : http://tse-10-test.esi.local)
• {dossier} est le nom du dossier comptable en minuscules (ex : esigescom)
• {endpoint} est le nom de l'endpoint (ex : art_list, document_detail)

Headers obligatoires

Header	Valeur	Description
X-API-KEY	<votre clé API>	Clé d'authentification (obligatoire)
Content-Type	application/json	Type de contenu du body (obligatoire si body présent)

Exemple de requête complète

POST /esigescom/art_list HTTP/1.1
Host: tse-10-test.esiweb.pro:5186
X-API-KEY: votre-cle-api
Content-Type: application/json

{
    "search": "chaise",
    "results": 10,
    "select": "artid,name1"
}

Paramètres des requêtes

Les paramètres sont transmis dans le body de la requête au format JSON. Certains endpoints n'exigent aucun paramètre (body vide ou {}). Les paramètres peuvent être de différents types :

Type	Description	Exemple
string	Chaîne de caractères	"ART001"
int	Nombre entier	10
array	Tableau de valeurs	["ART001", "ART002"]

Attention : certains paramètres qui représentent des nombres doivent être transmis au format string (ex : QTY dans Document_GetUnitPriceAndVat doit être "2" et non 2).

Gestion des erreurs

Le service LogisticsService de l'application gère automatiquement :

• Retry automatique : en cas d'échec de connexion (ConnectionException), le service retente automatiquement selon la configuration (retry.times et retry.sleep_ms).
• Logging : chaque requête (réussie ou échouée) est enregistrée dans la table api_request_logs avec l'endpoint, les paramètres, le code de statut et la réponse.
• Exceptions : en cas d'erreur, une LogisticsApiException est levée avec un message explicite en français.
• Traduction des erreurs : la classe App\Support\ApiErrorTranslator normalise le champ error de la réponse API (qui peut être null, une chaîne ou un tableau de chaînes) et ajoute une explication en français aux messages d'erreur connus (ex : "Search terms are required" est enrichi de "Le champ de recherche est obligatoire.").

Validation des champs

Avant chaque appel API, les pages Filament vérifient que les champs obligatoires sont remplis. Si un champ requis est vide, un message d'erreur en français est affiché et l'appel API n'est pas effectué. Les règles de validation sont basées sur la documentation fournisseur (documentation/WEB-A-1 (3).md). Cette validation côté client évite des appels API inutiles et fournit un retour immédiat à l'utilisateur.

---

4. Structure de réponse

Format standard

Tous les endpoints retournent un objet JSON avec la même structure :

{
    "data": "<résultat de la requête>",
    "metadata": {
        "rowcount": 0,
        "issuccess": true
    },
    "error": null
}

Description des clés

Clé	Type	Description
data	mixed	Le résultat de la requête. Peut être un tableau d'objets, un objet unique, une chaîne, ou null.
metadata	object	Informations sur la requête. Contient toujours rowcount et issuccess. Peut contenir d'autres clés selon l'endpoint.
metadata.rowcount	int	Nombre d'éléments retournés dans data.
metadata.issuccess	bool	true si la requête a réussi, false sinon.
error	string, array ou null	Message d'erreur en cas d'échec. Peut être une chaîne, un tableau de chaînes, ou null si la requête a réussi. L'application normalise ce champ via ApiErrorTranslator.

Exemple de réponse réussie

{
    "data": [
        { "artid": "ART001", "name1": "Chaise bureau" },
        { "artid": "ART002", "name1": "Chaise visiteur" }
    ],
    "metadata": {
        "rowcount": 2,
        "issuccess": true
    },
    "error": null
}

Exemple de réponse en erreur

{
    "data": null,
    "metadata": {
        "rowcount": 0,
        "issuccess": false
    },
    "error": "Invalid API key"
}

Métadonnées spécifiques par endpoint

Certains endpoints retournent des clés supplémentaires dans metadata :

Endpoint	Clés supplémentaires	Description
tables_list	tableCount, folderType, endpoint	Nombre total de tables, type de base de données (ex : DBF), nom de l'endpoint
column_list	columnCount, tableName	Nombre de colonnes retournées, nom de la table interrogée

---

5. Tables et colonnes disponibles

Liste des tables

L'API expose 16 tables. Chacune correspond à un domaine fonctionnel de la gestion commerciale :

Table	Colonnes	Description
art	160	Articles : références produits du catalogue. Contient l'identifiant, le nom, la description, les prix, les unités, les catégories, etc.
attach	13	Fichiers attachés : pièces jointes associées aux documents (factures, bons de commande, etc.).
barcode	12	Codes-barres : codes-barres associés aux articles pour l'identification et le scan.
category	10	Catégories : catégories de classification pour organiser les articles.
codes	50	Codes système : codes de configuration internes au système de gestion.
cust	216	Tiers/Clients : fiches tiers (clients, fournisseurs). Contient l'identifiant, le nom, l'adresse, les conditions commerciales, les coordonnées, etc.
docdet	82	Lignes de documents : lignes de détail des documents commerciaux. Chaque ligne référence un article avec sa quantité, son prix, sa TVA, etc.
dochead	212	En-têtes de documents : en-têtes des documents commerciaux (devis, commandes, factures). Contient le tiers, la date, le journal, le statut, les totaux, etc.
docpay	22	Paiements : paiements associés aux documents (montant, date, mode de paiement).
file	17	Fichiers : fichiers système gérés par l'application.
hist	50	Historique : historique des opérations effectuées dans le système.
incodes	24	Codes internes : codes internes paramétrables, utilisés pour les listes de valeurs, les types, etc.
jnl	155	Journaux : journaux comptables et commerciaux. Chaque journal regroupe des documents du même type (ventes, achats, etc.).
pers	78	Personnes/Contacts : fiches de contacts associées aux tiers ou à l'entreprise.
price	28	Tarifs : grilles de prix et conditions tarifaires par article, client ou catégorie.
stk	20	Stock : quantités en stock par article et par emplacement.

Types de colonnes

Chaque colonne d'une table possède un type de données identifié par un code à une lettre :

Code	Label	Description
C	Caractère	Chaîne de caractères (texte libre, identifiants, noms, etc.)
N	Numérique	Nombre entier ou décimal (quantités, prix, montants, etc.)
T	Date/Heure	Timestamp combinant date et heure
D	Date	Date seule (sans composante horaire)
L	Logique	Booléen (true/false)
M	Mémo	Texte long (champs de description étendus, remarques, etc.)

Exploration des colonnes

Pour connaître les colonnes disponibles dans une table, utiliser les endpoints tables_list et column_list/{tablename} décrits dans la section 6.

Remarque importante : l'API retourne les colonnes en double dans la réponse de column_list. L'application effectue une déduplication automatique côté client.

---

6. Récupération de données

Tous les endpoints de cette section servent à lire des données depuis l'API. Ils utilisent la méthode POST et retournent des données dans la clé data de la réponse.

6.1 Structure de la base de données

tables_list -- Liste des tables

Retourne la liste de toutes les tables accessibles dans le dossier comptable. Utile pour découvrir la structure de la base de données.

URL	POST /{dossier}/tables_list
Méthode service	LogisticsService::tablesList()

Paramètres : aucun.

Exemple de requête :

{}

Exemple de réponse :

{
    "data": [
        { "name": "art", "columnCount": 160 },
        { "name": "attach", "columnCount": 13 },
        { "name": "barcode", "columnCount": 12 },
        { "name": "category", "columnCount": 10 },
        { "name": "codes", "columnCount": 50 },
        { "name": "cust", "columnCount": 216 },
        { "name": "docdet", "columnCount": 82 },
        { "name": "dochead", "columnCount": 212 },
        { "name": "docpay", "columnCount": 22 },
        { "name": "file", "columnCount": 17 },
        { "name": "hist", "columnCount": 50 },
        { "name": "incodes", "columnCount": 24 },
        { "name": "jnl", "columnCount": 155 },
        { "name": "pers", "columnCount": 78 },
        { "name": "price", "columnCount": 28 },
        { "name": "stk", "columnCount": 20 }
    ],
    "metadata": { "tableCount": 16, "folderType": "DBF", "endpoint": "tables_list", "rowcount": 16, "issuccess": true },
    "error": null
}

---

column_list/{tablename} -- Colonnes d'une table

Retourne la liste des colonnes d'une table donnée, avec leur type, leur longueur et leur précision. Indispensable pour connaître les champs utilisables dans le paramètre select des autres endpoints.

URL	POST /{dossier}/column_list/{tablename}
Méthode service	LogisticsService::columnList(string $table)

Paramètres :

Paramètre	Emplacement	Type	Obligatoire	Description
tablename	URL	string	Oui	Nom de la table (issu de tables_list). Exemple : art, cust, dochead.

Exemple de requête :

POST /esigescom/column_list/stk

Exemple de réponse :

{
    "data": [
        { "name": "ARTID", "dataType": "C", "length": 20, "precision": 0 },
        { "name": "STOCK", "dataType": "N", "length": 10, "precision": 2 },
        { "name": "DEPOT", "dataType": "C", "length": 10, "precision": 0 }
    ],
    "metadata": { "columnCount": 3, "tableName": "stk", "rowcount": 3, "issuccess": true },
    "error": null
}

Remarque : l'API retourne chaque colonne en double. L'application effectue une déduplication automatique.

---

6.2 Articles

Les articles sont les références produits du catalogue. Ils sont stockés dans la table art.

art_list -- Recherche d'articles

Retourne une liste d'articles correspondant aux critères de recherche. L'API retourne un maximum fixe de 5 résultats par appel, cette limite n'est pas configurable.

URL	POST /{dossier}/art_list
Méthode service	LogisticsService::artList(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
search	string	Oui	Filtre de recherche textuel. Recherche dans les colonnes artid et name1 de la table art. Ce paramètre est obligatoire : un appel sans search retourne une erreur "Search terms are required", même si barcode est fourni.
select	string	Non	Liste des colonnes à retourner, séparées par des virgules. Les noms de colonnes disponibles sont ceux de la table art (obtenables via column_list/art). Si omis, un jeu de colonnes par défaut est retourné.
results	int	Non	Sans effet. Ce paramètre est accepté par l'API mais n'influence pas le nombre de résultats retournés. L'API retourne toujours un maximum de 5 résultats, quelle que soit la valeur de results (testé avec 1, 3, 5, 10, 20, en int et en string).
barcode	string	Non	Sans effet observable. Ce paramètre est accepté par l'API mais ne modifie pas les résultats. Les données retournées sont strictement identiques avec ou sans barcode. Le paramètre search reste obligatoire même si barcode est fourni.

Métadonnées retournées :

L'endpoint art_list retourne des métadonnées spécifiques dans la clé metadata :

Clé	Type	Description
rowCount	int	Nombre de résultats retournés.
source	string	Type de base de données (ex : DBF).
executionTimeMs	int	Temps d'exécution de la requête en millisecondes.
searchColumns	string	Colonnes utilisées pour la recherche (ex : artid,name1).
selectColumns	string	Colonnes demandées dans le paramètre select.
searchTerms	string	Termes de recherche utilisés.

Exemple de requête :

{
    "search": "chaise",
    "select": "artid,name1,saleprice"
}

Exemple de réponse :

{
    "data": [
        { "artid": "003R92572", "name1": "Papier A4 80g", "saleprice": 12.50 },
        { "artid": "003R92573", "name1": "Papier A4 90g", "saleprice": 14.00 },
        { "artid": "003R98703", "name1": "Papier A3 80g", "saleprice": 18.75 },
        { "artid": "003R98711", "name1": "Papier A3 90g", "saleprice": 21.00 },
        { "artid": "003R98718", "name1": "Papier A4 100g", "saleprice": 16.50 }
    ],
    "metadata": {
        "rowCount": 5,
        "source": "DBF",
        "executionTimeMs": 720,
        "searchColumns": "artid,name1",
        "selectColumns": "artid,name1,saleprice",
        "searchTerms": "papier"
    },
    "error": null
}

Attention : les noms de colonnes dans select doivent correspondre exactement aux noms retournes par column_list/art (ex : name1, pas artname). L'API ignore silencieusement les noms de colonnes invalides sans emettre d'erreur, ce qui peut donner l'impression que le parametre select ne fonctionne pas.

---

art_getstk -- Stock d'un article

Retourne les informations de stock pour un article donné. Permet de vérifier la disponibilité d'un article dans les différents dépôts.

URL	POST /{dossier}/art_getstk
Méthode service	LogisticsService::artGetStock(string $artId)

Paramètres :

Paramètre	Type	Obligatoire	Description
ARTID	string	Oui	Identifiant unique de l'article (champ artid de la table art).

Exemple de requête :

{
    "ARTID": "ART001"
}

---

6.3 Journaux

Les journaux regroupent les documents commerciaux par type (ventes, achats, retours, etc.). Ils sont stockés dans la table jnl.

jnl_list -- Liste des journaux

Retourne la liste des journaux correspondant au type demandé. Un journal contient un ou plusieurs documents.

URL	POST /{dossier}/jnl_list
Méthode service	LogisticsService::jnlList(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
TYPE	string	Oui	Code de type de journal (1 ou 2 caractères). Voir la section "Codes de type" ci-dessous.
select	string	Non	Colonnes à retourner, séparées par des virgules (colonnes de la table jnl). Insensible à la casse. Si omis, seule la colonne jnl est retournée par défaut.
results	string	Non	Nombre maximum de résultats. Doit être au format string (ex : "50"), pas un nombre. Un entier provoque une erreur HTTP 400. La limite par défaut (sans ce paramètre) est de 30 résultats. Contrairement à art_list et third_list, ce paramètre fonctionne réellement pour jnl_list.

Codes de type de journal :

La colonne TYPE de la table jnl contient un code à 2 caractères suivant le schéma [Domaine][TypeDocument] :

Domaine (1er caractère)	Signification
C	Client
S	Supplier / Fournisseur
K	stocK / Inventaire

Type document (2e caractère)	Signification
O	Order / Commande
D	Delivery / Livraison (note d'envoi)
I	Invoice / Facture
C	Credit note / Note de crédit
P	Proposal / Offre de prix (pro forma)
A	Achat
M	Mouvement (stock)

Le paramètre TYPE accepte 1 ou 2 caractères :

• 1 caractère : filtre tous les journaux dont le code de type contient ce caractère (première ou deuxième position). Exemples :
  • TYPE=C retourne tous les journaux client (CO, CD, CI, CC, CP, CA, CM) -- 42 résultats dans le dossier de test.
  • TYPE=I retourne toutes les factures (CI, KI) -- 26 résultats.
  • TYPE=O retourne toutes les commandes (CO, SO) -- 7 résultats.
  • TYPE=D retourne toutes les livraisons (CD, SD) -- 5 résultats.
  • TYPE=S retourne tous les journaux fournisseur (SD, SO) -- 2 résultats.
  • TYPE=K retourne tous les journaux inventaire (KI, KM) -- 2 résultats.
  • TYPE=P retourne toutes les offres de prix (CP) -- 3 résultats.
  • TYPE=A retourne tous les journaux d'achat (CA) -- 2 résultats.
• 2 caractères : correspondance exacte sur le code de type. Exemples :
  • TYPE=CO retourne uniquement les commandes client -- 6 résultats.
  • TYPE=CI retourne uniquement les factures client -- 25 résultats.
  • TYPE=CC retourne uniquement les notes de crédit client -- 1 résultat.

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).
unlimited	bool	Indique si la requête est sans limite (toujours false dans les tests).

Colonnes utiles de la table jnl :

Colonne	Type	Description
JNL	C(8)	Code unique du journal (ex : 03VEN, 01COM).
NAME	C(40)	Nom du journal (ex : FACTURE CLIENT).
NAME1	C(40)	Nom alternatif 1 (ex : FACTURE 03VEN).
NAME2	C(40)	Nom alternatif 2 (ex : FAKTUUR).
TYPE	C(2)	Code de type (ex : CI, CO, SD).
NUMBER	N(8)	Dernier numéro de document dans ce journal.
JNLORDER	C(8)	Journal de commande lié.
JNLINV	C(8)	Journal de facturation lié.
JNLCRED	C(8)	Journal de note de crédit lié.
JNLMVT	C(8)	Journal de mouvement de stock lié.
STKID	C(2)	Identifiant de stock associé.
STATUSINIT	C(2)	Statut initial des documents créés dans ce journal.

Exemple de requête :

{
    "TYPE": "C",
    "select": "JNL,NAME,TYPE,NUMBER",
    "results": "50"
}

Exemple de réponse :

{
    "data": [
        { "jnl": "01COM", "name": "COMMANDE", "type": "CO", "number": 25100123 },
        { "jnl": "03VEN", "name": "FACTURE CLIENT", "type": "CI", "number": 25105451 },
        { "jnl": "04NCV", "name": "NOTE DE CREDIT CLIENT", "type": "CC", "number": 25400010 }
    ],
    "metadata": {
        "rowCount": 3,
        "source": "DBF",
        "unlimited": false
    },
    "error": null
}

---

6.4 Documents

Les documents commerciaux (devis, commandes, factures, avoirs, etc.) constituent le coeur du système. Chaque document possède un en-tête (dochead) et une ou plusieurs lignes de détail (docdet). Un document appartient à un journal et est associé à un tiers.

document_list -- Liste des documents

Retourne une liste de documents, éventuellement filtrée par tiers. Permet de consulter les documents commerciaux associés à un client.

URL	POST /{dossier}/document_list
Méthode service	LogisticsService::documentList(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
select	string	Non	Colonnes à retourner, séparées par des virgules (colonnes de la table dochead).
thirdid	string	Non	Identifiant du tiers (champ custid de la table cust). Si fourni, seuls les documents de ce tiers sont retournés.

Exemple de requête :

{
    "select": "docid,docdate,thirdid,totalht",
    "thirdid": "CUST001"
}

---

document_detail -- Détail d'un document

Retourne le détail complet d'un document spécifique : l'en-tête (informations générales) et toutes les lignes de détail (articles, quantités, prix).

URL	POST /{dossier}/document_detail
Méthode service	LogisticsService::documentDetail(string $jnl, string $number)

Paramètres :

Paramètre	Type	Obligatoire	Description
jnl	string	Oui	Code du journal auquel appartient le document.
number	string	Oui	Identifiant unique du document dans le journal.

Exemple de requête :

{
    "jnl": "VEN",
    "number": "2026/0001"
}

---

Document_GetStatusList -- Statuts disponibles d'un journal

Retourne la liste des statuts disponibles pour les documents d'un journal donné. Utile pour connaître les états possibles d'un document (brouillon, validé, envoyé, etc.).

URL	POST /{dossier}/Document_GetStatusList
Méthode service	LogisticsService::documentGetStatusList(string $jnl)

Paramètres :

Paramètre	Type	Obligatoire	Description
jnl	string	Oui	Code du journal dont on veut connaître les statuts.

Exemple de requête :

{
    "jnl": "VEN"
}

---

Document_GetUnitPriceAndVat -- Prix unitaire et TVA

Retourne le prix unitaire et la TVA applicable pour un article dans un contexte précis (journal, tiers, date, quantité). Utile pour calculer le montant d'une ligne de document avant création.

URL	POST /{dossier}/Document_GetUnitPriceAndVat
Méthode service	LogisticsService::documentGetUnitPriceAndVat(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
ARTID	string	Oui	Identifiant de l'article.
QTY	string	Oui	Quantité demandée. Doit être au format string (ex : "2"), pas un nombre.
JNL	string	Oui	Code du journal.
THIRDID	string	Oui	Identifiant du tiers (champ custid de la table cust).
DATE	string	Oui	Date de référence pour le calcul du prix.

Exemple de requête :

{
    "ARTID": "ART001",
    "QTY": "5",
    "JNL": "VEN",
    "THIRDID": "CUST001",
    "DATE": "2026-02-20"
}

---

Document_GetDueDate -- Échéance de paiement

Calcule la date d'échéance de paiement à partir d'un type de délai de paiement et d'une date de départ. Utile pour déterminer automatiquement la date limite de paiement d'un document.

URL	POST /{dossier}/Document_GetDueDate
Méthode service	LogisticsService::documentGetDueDate(string $payDelay, string $date)

Paramètres :

Paramètre	Type	Obligatoire	Description
paydelay	string	Oui	Type de délai de paiement (code identifiant les conditions de paiement, ex : 30J, 60J, FDM).
date	string	Oui	Date de départ à partir de laquelle calculer l'échéance.

Exemple de requête :

{
    "paydelay": "30J",
    "date": "2026-02-20"
}

---

Document_GetAttachListThumbnail -- Miniatures des annexes

Retourne les miniatures des fichiers images attachés à un document. Seuls les fichiers de type image sont concernés ; les autres types de fichiers ne sont pas retournés.

URL	POST /{dossier}/Document_GetAttachListThumbnail
Méthode service	LogisticsService::documentGetAttachListThumbnail(string $jnl, string $number)

Paramètres :

Paramètre	Type	Obligatoire	Description
JNL	string	Oui	Code du journal du document.
NUMBER	string	Oui	Identifiant du document.

Exemple de requête :

{
    "JNL": "VEN",
    "NUMBER": "2026/0001"
}

---

6.5 Tiers

Les tiers (clients, fournisseurs) sont les entités commerciales avec lesquelles l'entreprise interagit. Ils sont stockés dans la table cust.

third_list -- Recherche de tiers

Retourne une liste de tiers correspondant au filtre de recherche. Permet de trouver un client ou fournisseur par son nom, son identifiant ou d'autres critères.

URL	POST /{dossier}/third_list
Méthode service	LogisticsService::thirdList(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
search	string	Oui	Filtre de recherche. Ce paramètre est obligatoire : un appel sans filtre retourne une erreur.
select	string	Non	Colonnes à retourner, séparées par des virgules (colonnes de la table cust).
results	int	Non	Sans effet. Ce paramètre est accepté mais n'influence pas le nombre de résultats. L'API retourne toujours un maximum de 10 résultats (testé avec 3, 10, 20).

Exemple de requête :

{
    "search": "Dupont",
    "select": "custid,custname,city"
}

---

third_GetArtHistory -- Historique des articles d'un tiers

Retourne l'historique complet des articles présents dans les documents associés à un tiers. Permet d'analyser les achats ou ventes passés d'un client/fournisseur.

URL	POST /{dossier}/third_GetArtHistory
Méthode service	LogisticsService::thirdGetArtHistory(string $thirdId)

Paramètres :

Paramètre	Type	Obligatoire	Description
thirdid	string	Oui	Identifiant du tiers (champ custid de la table cust).

Exemple de requête :

{
    "thirdid": "CUST001"
}

---

6.6 Divers

getserialnumber -- Numéro de série du dossier

Retourne le numéro de série du dossier comptable. Identifie de manière unique l'installation du logiciel de gestion.

URL	POST /{dossier}/getserialnumber
Méthode service	LogisticsService::getSerialNumber()

Paramètres : aucun.

Exemple de requête :

{}

---

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

URL	POST /{dossier}/codes_list
Méthode service	LogisticsService::codesList(array $params)

Paramètres :

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.

Exemple de requête :

{
    "code": "PAY"
}

Remarque : les valeurs retournées contiennent des champs vala1, vala2, etc. dont la signification précise dépend du code recherché.

---

7. Envoi de données

Les endpoints de cette section permettent de créer ou modifier des données dans le système de gestion via l'API.

7.1 Ajout d'un document

document_add -- Création d'un document

Crée un nouveau document commercial (devis, commande, facture, etc.) dans un journal. Le document est composé d'un en-tête (tiers, date, journal) et d'une ou plusieurs lignes d'articles.

URL	POST /{dossier}/document_add
Méthode service	LogisticsService::documentAdd(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
ThirdId	string	Oui	Identifiant du tiers (champ custid de la table cust). Détermine le client ou fournisseur associé au document.
Date	string	Oui	Date d'encodage du document (ex : "2026-02-20").
Artid	array	Oui	Tableau d'identifiants d'articles (champ artid de la table art). Chaque élément correspond à une ligne du document.
Qty	array	Oui	Tableau de quantités. Correspond position par position au tableau Artid. Chaque élément est un string.
Saleprice	array	Oui	Tableau des prix de vente unitaires. Correspond position par position au tableau Artid. Chaque élément est un string.
JNL	string	Oui	Code du journal dans lequel créer le document (ex : "VEN" pour ventes).
Discount	array	Non	Tableau des réductions de prix (en pourcentage ou montant). Correspond position par position au tableau Artid.
Vatid	array	Non	Tableau des identifiants de code TVA. Correspond position par position au tableau Artid.
Vatpc	array	Non	Tableau des pourcentages de TVA. Correspond position par position au tableau Artid.
Attachments	array	Non	Liste de fichiers joints au document. Voir la structure ci-dessous.

Structure d'un élément Attachments :

Clé	Type	Description
FileName	string	Nom du fichier avec extension (ex : "facture.pdf").
FileDesc	string	Description du fichier (ex : "Bon de commande signé").
FileContentBase64	string	Contenu du fichier encodé en base64.

Correspondance des tableaux : les tableaux Artid, Qty, Saleprice, Discount, Vatid et Vatpc fonctionnent par correspondance positionnelle. L'élément à l'index 0 de chaque tableau concerne la première ligne du document, l'élément à l'index 1 la deuxième ligne, etc.

Exemple de requête :

{
    "ThirdId": "CUST001",
    "Date": "2026-02-20",
    "Artid": ["ART001", "ART002"],
    "Qty": ["2", "5"],
    "Saleprice": ["10.00", "25.50"],
    "JNL": "VEN",
    "Discount": ["0", "10"],
    "Vatid": ["TVA21", "TVA21"],
    "Vatpc": ["21", "21"],
    "Attachments": [
        {
            "FileName": "bon.pdf",
            "FileDesc": "Bon de commande",
            "FileContentBase64": "JVBERi0xLjQK..."
        }
    ]
}

---

7.2 Modification d'un document

document_mod -- Modification d'un document existant

Modifie un document existant identifié par son numéro et son journal. Permet de mettre à jour les lignes d'articles, les prix, le tiers, ou d'ajouter des fichiers joints.

URL	POST /{dossier}/document_mod
Méthode service	LogisticsService::documentMod(array $params)

Paramètres :

Paramètre	Type	Obligatoire	Description
number	string	Oui	Identifiant du document à modifier.
JNL	string	Oui	Code du journal lié au document.
Thirdid	string	Non	Nouvel identifiant du tiers (si modification du tiers associé).
Artid	array	Non	Tableau d'identifiants d'articles (remplace les lignes existantes).
Qty	array	Non	Tableau de quantités (correspond position par position à Artid).
Saleprice	array	Non	Tableau des prix de vente unitaires (correspond position par position à Artid).
Attachments	array	Non	Liste de fichiers joints (même structure que document_add).

Exemple de requête :

{
    "number": "2026/0001",
    "JNL": "VEN",
    "Artid": ["ART001", "ART003"],
    "Qty": ["3", "1"],
    "Saleprice": ["10.00", "50.00"]
}

---

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.

Document_GetPDF -- Génération de PDF

URL	POST /{dossier}/Document_GetPDF
Méthode service	LogisticsService::documentGetPdf(string $jnl, string $number, string $layout)
Statut	Non fonctionnel

Paramètres connus :

Paramètre	Type	Description
JNL	string	Code du journal.
NUMBER	string	Identifiant du document.
LAYOUT	string	Mise en page du PDF. Valeur attendue inconnue.

Problème : le paramètre LAYOUT est requis mais sa valeur attendue n'est pas documentée par le fournisseur de l'API. L'endpoint retourne une erreur sans ce paramètre.

---

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

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

Tiers (cust)
  |
  +-- possède un ou plusieurs --> Documents (dochead / docdet)
                                    |
                                    +-- appartient à un --> Journal (jnl)
                                    |
                                    +-- contient un ou plusieurs --> Articles (art)
                                    |
                                    +-- peut avoir des --> Fichiers attachés (attach)
                                    |
                                    +-- peut avoir des --> Paiements (docpay)

Description des relations :

• Un tiers (cust) est un client ou fournisseur. Il peut être associé à plusieurs documents commerciaux.
• Un journal (jnl) regroupe plusieurs documents du même type (ventes, achats, retours, etc.). Chaque document appartient à un seul journal.
• Un document est composé d'un en-tête (dochead) contenant les informations générales (tiers, date, journal, statut, totaux) et de lignes de détail (docdet) contenant les articles.
• Un article (art) est une référence produit du catalogue. Chaque ligne de document fait référence à un article avec une quantité, un prix unitaire et une TVA.
• Le stock (stk) contient les quantités en stock par article. Il est consultable via l'endpoint art_getstk.
• Les fichiers attachés (attach) sont des pièces jointes associées aux documents (factures PDF, bons de commande scannés, etc.).
• Les paiements (docpay) enregistrent les règlements associés aux documents.
• Les codes internes (incodes) sont des tables de référence paramétrables utilisées pour les listes déroulantes, les types, les catégories, etc.

---

10. 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.

2. Méthode POST uniquement : tous les endpoints utilisent la méthode POST, y compris pour les opérations de lecture. N'utilisez pas GET, PUT ou DELETE.

3. Paramètres numériques en string : plusieurs paramètres qui représentent des nombres doivent être transmis au format string. Le paramètre QTY dans Document_GetUnitPriceAndVat ("2", pas 2) et le paramètre results dans jnl_list ("50", pas 50) provoquent une erreur HTTP 400 s'ils sont envoyés comme entiers. Toujours caster en string les valeurs numériques en cas de doute.

4. Paramètre search obligatoire pour third_list : l'endpoint third_list exige le paramètre search. Un appel sans ce paramètre retourne une erreur.

5. Paramètre results : le comportement de ce paramètre varie selon l'endpoint. Pour art_list, il n'a aucun effet (toujours 5 résultats maximum). Pour third_list, il n'a aucun effet non plus (toujours 10 résultats maximum). En revanche, pour jnl_list, le paramètre results fonctionne réellement et limite le nombre de résultats retournés (la limite par défaut sans ce paramètre est de 30). Le paramètre doit être au format string pour jnl_list.

6. Paramètre TYPE obligatoire pour jnl_list : l'endpoint jnl_list exige le paramètre TYPE. Le filtre accepte 1 caractère (filtre large : C pour tous les journaux client) ou 2 caractères (filtre exact : CI pour les factures client uniquement). Un appel sans ce paramètre retourne une erreur.

7. Format du champ error : le champ error de la réponse API peut être null, une chaîne ou un tableau de chaînes. L'application normalise ce champ automatiquement via ApiErrorTranslator.

8. Paramètre select : permet de choisir les colonnes à retourner. Les noms de colonnes disponibles pour chaque table s'obtiennent via column_list/{tablename}. Si omis, un jeu de colonnes par défaut est retourné. Attention : les noms de colonnes doivent correspondre exactement à ceux retournés par column_list (ex : name1, pas artname). L'API ignore silencieusement les noms de colonnes invalides sans émettre d'erreur.

9. Casse des paramètres : la casse des noms de paramètres varie selon les endpoints. Par exemple, l'identifiant du tiers peut être thirdid, Thirdid ou THIRDID selon l'endpoint. Respectez la casse documentée pour chaque endpoint.

10. Fichiers attachés en base64 : lors de l'ajout ou la modification de documents, les fichiers joints doivent être encodés en base64 dans le champ FileContentBase64. Seul le contenu du fichier est encodé, pas le nom ni la description.

11. Déduplication des colonnes : l'endpoint column_list retourne chaque colonne en double. L'application effectue une déduplication automatique, mais si vous interrogez l'API directement, vous devez gérer ce doublon.

12. Correspondance positionnelle des tableaux : dans document_add et document_mod, les tableaux Artid, Qty, Saleprice, Discount, Vatid et Vatpc fonctionnent par correspondance positionnelle. Assurez-vous que tous les tableaux ont la même longueur.

13. Timeout : certaines requêtes peuvent être lentes selon le volume de données. Le timeout par défaut est configuré à 300 secondes. En cas de timeout, vérifiez la configuration LOGISTICS_API_TIMEOUT.

---

11. Ressources externes

• Documentation Postman