Update Tiers functionality and enhance API documentation
- Changed the default value of the `$select` property in Tiers.php from `custid,custname` to `custid,name` to reflect valid column names. - Updated the tiers.blade.php view to align the placeholder for the select field with the new default value. - Enhanced the documentation for the `third_list` and `third_GetArtHistory` endpoints, detailing valid search columns, metadata, and response structures. - Added new tests in TiersPageTest.php to verify the default select value, API parameter handling, and metadata storage. - Overall, improved the user experience and API interaction for managing tiers.
This commit is contained in:
@@ -1061,7 +1061,7 @@ Les tiers (clients, fournisseurs) sont les entités commerciales avec lesquelles
|
||||
|
||||
#### `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.
|
||||
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. L'API retourne un maximum fixe de **10 résultats** par appel, cette limite n'est pas configurable. La recherche s'effectue dans les colonnes `name`, `groupid` et `vat` (pas dans `custid`).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -1072,16 +1072,81 @@ Retourne une liste de tiers correspondant au filtre de recherche. Permet de trou
|
||||
|
||||
| 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). |
|
||||
| `search` | `string` | Oui | Filtre de recherche textuel. Recherche dans les colonnes `name`, `groupid` et `vat` de la table `cust`. **Ce paramètre est obligatoire** : un appel sans `search` retourne une erreur HTTP 400 "Search terms are required". Un body vide provoque une erreur HTTP 500. **Attention** : la recherche ne porte PAS sur `custid`. Pour trouver un tiers par son identifiant, il faut chercher par son nom, son groupid ou son numéro de TVA. |
|
||||
| `select` | `string` | Non | Liste des colonnes à retourner, séparées par des virgules. Insensible à la casse. Si omis, les colonnes par défaut sont `custid,name`. L'API ignore silencieusement les noms de colonnes invalides sans émettre d'erreur. Voir le tableau des colonnes valides ci-dessous. |
|
||||
| `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 10 résultats, quelle que soit la valeur de `results` (testé avec 3, 5, 10, 20, en int et en string). |
|
||||
|
||||
**Colonnes valides pour `select`** (testées individuellement) :
|
||||
|
||||
| Colonne | Type | Description | Exemple |
|
||||
|---------|------|-------------|---------|
|
||||
| `custid` | `string` | Identifiant unique du tiers | `"0100002174"` |
|
||||
| `name` | `string` | Nom principal du tiers | `"ESI SPRL"` |
|
||||
| `name2` | `string` | Nom secondaire / complément | `"BOX7"` |
|
||||
| `vat` | `string` | Numéro de TVA | `"0431.066.713"` |
|
||||
| `email` | `string` | Adresse email | `"jre@esi-informatique.com"` |
|
||||
| `groupid` | `string` | Identifiant de groupe | `"ESI01"` |
|
||||
| `website` | `string` | Site web | `""` |
|
||||
| `memo` | `string` | Mémo / remarques | `""` |
|
||||
| `paydelay` | `string` | Code de délai de paiement | `""` |
|
||||
| `paymode` | `string` | Mode de paiement | `""` |
|
||||
| `bankname` | `string` | Nom de la banque | `""` |
|
||||
| `iban` | `string` | Code IBAN | `"BE09348066192157"` |
|
||||
| `bic` | `string` | Code BIC/SWIFT | `"BBRUBEBB"` |
|
||||
| `custtype` | `string` | Type de client | `"PRO"` |
|
||||
| `discount` | `float` | Remise globale | `0` |
|
||||
|
||||
**Colonnes invalides** (ignorées silencieusement) : `custname`, `name1`, `addr1`, `addr2`, `zip`, `city`, `country`, `vatnum`, `phone1`, `phone`, `addr`, `address`, `tel`, `fax`, `web`, `note`, `lang`, `type`, `status`, `categ`, `bankaccount`, `maxdisc`.
|
||||
|
||||
**Attention** : la colonne `custname` n'existe PAS dans `third_list`. Le nom du tiers est dans la colonne `name`. C'est une différence importante par rapport à d'autres endpoints (comme `document_detail`) qui utilisent `thirdname`.
|
||||
|
||||
**Métadonnées retournées** :
|
||||
|
||||
| Clé | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `rowCount` | `int` | Nombre de résultats retournés (maximum 10). |
|
||||
| `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 (toujours `name,groupid,vat`). |
|
||||
| `selectColumns` | `string` | Colonnes demandées dans le paramètre `select`. |
|
||||
| `searchTerms` | `string` | Termes de recherche utilisés. |
|
||||
|
||||
**Exemple de requête** :
|
||||
|
||||
```json
|
||||
{
|
||||
"search": "Dupont",
|
||||
"select": "custid,custname,city"
|
||||
"search": "ESI",
|
||||
"select": "custid,name,vat,groupid"
|
||||
}
|
||||
```
|
||||
|
||||
**Exemple de réponse** :
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"custid": "0100002174",
|
||||
"name": "ESI SPRL",
|
||||
"vat": "0431.066.713",
|
||||
"groupid": "ESI01"
|
||||
},
|
||||
{
|
||||
"custid": "0100002175",
|
||||
"name": "E.I.S. SA",
|
||||
"vat": "0435.063.806",
|
||||
"groupid": "ESI02"
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"rowCount": 2,
|
||||
"source": "DBF",
|
||||
"executionTimeMs": 111,
|
||||
"searchColumns": "name,groupid,vat",
|
||||
"selectColumns": "custid,name,vat,groupid",
|
||||
"searchTerms": "ESI"
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1089,7 +1154,7 @@ Retourne une liste de tiers correspondant au filtre de recherche. Permet de trou
|
||||
|
||||
#### `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.
|
||||
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. L'endpoint retourne **tous les articles** sans pagination ni limite (jusqu'à plusieurs milliers d'éléments). Les résultats sont triés par date décroissante (les plus récents en premier).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -1100,16 +1165,80 @@ Retourne l'historique complet des articles présents dans les documents associé
|
||||
|
||||
| Paramètre | Type | Obligatoire | Description |
|
||||
|-----------|------|:-----------:|-------------|
|
||||
| `thirdid` | `string` | Oui | Identifiant du tiers (champ `custid` de la table `cust`). |
|
||||
| `thirdid` | `string` | Oui | Identifiant du tiers (champ `custid` de la table `cust`). **La casse du nom de paramètre est importante** : `thirdid` en minuscules est obligatoire. `THIRDID` en majuscules provoque une erreur HTTP 400 "thirdid parameter is required.". Un appel sans ce paramètre retourne également une erreur HTTP 400. Si l'identifiant n'existe pas, l'API retourne un tableau vide sans erreur. |
|
||||
|
||||
**Paramètres ignorés** : les paramètres `select` et `results` sont acceptés par l'API mais n'ont aucun effet sur la réponse. L'endpoint retourne toujours l'ensemble complet des colonnes et tous les résultats.
|
||||
|
||||
**Structure de la réponse `data`** :
|
||||
|
||||
Chaque élément du tableau `data` contient :
|
||||
|
||||
| Champ | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `artid` | `string` | Identifiant de l'article. |
|
||||
| `artname` | `string` | Nom de l'article (peut être tronqué à environ 80 caractères). |
|
||||
| `jnl` | `string` | Code du journal dans lequel l'article a été utilisé (ex : `03VEN`, `09OFFRE`, `INV`). |
|
||||
| `unitprice` | `float` | Prix unitaire de l'article dans ce document. |
|
||||
| `qty` | `int` ou `float` | Quantité de l'article dans ce document. |
|
||||
| `vatid` | `string` | Code de taux TVA (ex : `"21"`). |
|
||||
| `vatpc` | `int` ou `float` | Pourcentage TVA (ex : `21`). |
|
||||
| `s_credate` | `string` | Date de création du document (format `YYYY-MM-DD`). |
|
||||
|
||||
**Métadonnées retournées** :
|
||||
|
||||
| Clé | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `rowCount` | `int` | Nombre total de résultats retournés (peut atteindre plusieurs milliers). |
|
||||
| `source` | `string` | Type de base de données (ex : `DBF`). |
|
||||
|
||||
**Exemple de requête** :
|
||||
|
||||
```json
|
||||
{
|
||||
"thirdid": "CUST001"
|
||||
"thirdid": "0100002174"
|
||||
}
|
||||
```
|
||||
|
||||
**Exemple de réponse** :
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"artid": "EP2-06658",
|
||||
"artname": "Office Home and Business 2024 French Eur",
|
||||
"jnl": "09OFFRE",
|
||||
"unitprice": 220,
|
||||
"qty": 1,
|
||||
"vatid": "21",
|
||||
"vatpc": 21,
|
||||
"s_credate": "2025-06-03"
|
||||
},
|
||||
{
|
||||
"artid": "MO ATELIER",
|
||||
"artname": "FORFAIT PREPARATION PC / REMPLACEMENT DISQUE",
|
||||
"jnl": "09OFFRE",
|
||||
"unitprice": 65,
|
||||
"qty": 1,
|
||||
"vatid": "21",
|
||||
"vatpc": 21,
|
||||
"s_credate": "2025-06-03"
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"rowCount": 4468,
|
||||
"source": "DBF"
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**Remarques** :
|
||||
|
||||
- Un même article peut apparaître plusieurs fois dans l'historique s'il figure dans plusieurs documents.
|
||||
- Le champ `jnl` permet de distinguer le type de document (offre, facture, note de crédit, etc.).
|
||||
- Le volume de données peut être conséquent (milliers d'éléments). L'application affiche les résultats dans un bloc JSON formaté.
|
||||
|
||||
---
|
||||
|
||||
### 6.6 Divers
|
||||
@@ -1356,6 +1485,12 @@ Tiers (cust)
|
||||
|
||||
17. **Modes de paiement** : les valeurs valides pour les modes de paiement sont obtenues via `codes_list` avec `code=PAYMODE`. Les codes courants sont : `CAS` (Cash), `VIR` (Virement), `BC` (Bancontact), `CBEF` (Cash BEF).
|
||||
|
||||
18. **Colonnes `third_list` vs `column_list/cust`** : l'endpoint `third_list` n'accepte PAS toutes les colonnes de la table `cust` dans son paramètre `select`. Seul un sous-ensemble de colonnes est valide : `custid`, `name`, `name2`, `vat`, `email`, `groupid`, `website`, `memo`, `paydelay`, `paymode`, `bankname`, `iban`, `bic`, `custtype`, `discount`. Les colonnes `custname`, `name1`, `addr1`, `zip`, `city`, `country`, `phone1` (pourtant présentes dans `column_list/cust`) sont ignorées silencieusement. La colonne pour le nom du tiers est `name` (et non `custname`).
|
||||
|
||||
19. **Colonnes de recherche `third_list`** : la recherche textuelle de `third_list` porte sur les colonnes `name`, `groupid` et `vat`. Il n'est PAS possible de rechercher par `custid`. Pour retrouver un tiers spécifique par son identifiant, il faut utiliser une autre information (nom, numéro de TVA, groupid).
|
||||
|
||||
20. **`third_GetArtHistory` -- casse du paramètre** : le paramètre `thirdid` doit être en **minuscules**. `THIRDID` en majuscules provoque une erreur HTTP 400 "thirdid parameter is required.", comme si le paramètre n'avait pas été fourni. L'endpoint retourne l'intégralité de l'historique sans limite (potentiellement des milliers d'éléments).
|
||||
|
||||
---
|
||||
|
||||
## 11. Ressources externes
|
||||
|
||||
Reference in New Issue
Block a user