---
title: API REST – Champs d’un module
description: "Kafinea **livre un catalogue de champs** et vous **activez** ceux dont votre métier a besoin. Un libraire veut le poids, la nomenclature douanière et le pays d'origine sur ses articles ; une société de services n'en veut aucun. C'est pourquoi…"
url: "https://www.kafinea.com/fr/documentation/api/api-rest-champs-de-module/"
updated: "2026-11-04"
category: Intégrations / API
---

# API REST – Champs d’un module

Kafinea **livre un catalogue de champs** et vous **activez** ceux dont votre métier a besoin. Un
 libraire veut le poids, la nomenclature douanière et le pays d'origine sur ses articles ; une société
 de services n'en veut aucun. C'est pourquoi la plupart des champs sont livrés disponibles mais non
 activés, et pourquoi votre fiche article ne s'ouvre pas sur cent champs vides.

Deux opérations donnent à cette mécanique une interface programmable : lister ce qui existe, puis
 activer ce qui vous sert.

| Opération | Méthode | Description |
| --- | --- | --- |
| `describe` | GET | Décrire un module, champs non activés compris sur demande |
| `set_field_visibility` | POST | Activer ou désactiver des champs d'un module |

> **Activer un champ est réservé aux administrateurs.** Modifier la présentation d'un module est du
>  paramétrage, pas de la saisie : `set_field_visibility` refuse tout compte non administrateur.

---

## Describe – Lister les champs, activés ou non

[`describe`](https://www.kafinea.com/fr/documentation/api/api-rest-operations-crud/) répond par défaut à la question « que puis-je lire et écrire
 **maintenant** » et ne renvoie donc que les champs **activés**.

Conséquence importante si vous préparez une reprise de données : un champ absent de la réponse par
 défaut peut tout aussi bien **ne pas exister** dans votre version de Kafinea que **exister sans être
 activé**. Confondre les deux fait perdre du temps, et parfois conclure à tort qu'un développement est
 nécessaire.

Le paramètre **`fieldStatus`** répond à l'autre question : « qu'est-ce que ce module propose, et
 qu'est-ce qui est allumé ? »

> **GET** `https://apps.kafinea.com/{instance}/webservice.php`

| Paramètre | Type | Requis | Description |
| --- | --- | --- | --- |
| `operation` | string | oui | Doit être `describe` |
| `sessionName` | string | oui | Identifiant de session |
| `elementType` | string | oui | Nom du module (ex : `Products`, `Accounts`) |
| `fieldStatus` | string | non | `active` (défaut), `all` ou `inactive` |

Sans `fieldStatus`, la réponse est **exactement** celle que vous connaissez : vos intégrations
 existantes ne changent pas.

> **`all` et `inactive` sont réservés aux administrateurs.** La liste des champs que personne n'a
>  activés décrit le paramétrage de l'instance, pas des données : elle n'est pas montrée à un compte
>  restreint. Sans le paramètre, `describe` reste ouvert à tous et applique les droits du compte, comme
>  avant.

**Exemple curl :** les champs disponibles mais non activés sur les articles.

```bash
curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=describe&sessionName=YOUR_SESSION_ID&elementType=Products&fieldStatus=inactive"
```

### Réponse

```json
{
  "success": true,
  "result": {
    "label": "Articles",
    "name": "Products",
    "fields": [
      {
        "name": "mdscustomsnomenclature",
        "label": "Nomenclature douanière",
        "mandatory": false,
        "type": { "name": "string" },
        "editable": false,
        "active": false
      }
    ]
  }
}
```

| Champ | Signification |
| --- | --- |
| `name` | Le nom technique, à reprendre tel quel dans les autres opérations |
| `label` | Le libellé tel que l'utilisateur le voit, dans la langue de votre session |
| `active` | `false` = livré et disponible, mais invisible sur cette instance |
| `editable` | Toujours `false` sur un champ non activé : activez-le d'abord pour pouvoir l'écrire |

Avec `fieldStatus=all`, les champs activés portent également `active` (à `true`), ce qui permet de
 trier la liste sans second appel. Les valeurs autorisées d'une liste déroulante non encore activée se
 lisent avec [`getPicklistValues`](https://www.kafinea.com/fr/documentation/api/api-rest-picklist/).

---

## FieldVisibility – Activer ou désactiver des champs

> **POST** `https://apps.kafinea.com/{instance}/webservice.php`

| Paramètre | Type | Requis | Description |
| --- | --- | --- | --- |
| `operation` | string | oui | Doit être `set_field_visibility` |
| `sessionName` | string | oui | Identifiant de session |
| `moduleName` | string | oui | Nom du module |
| `fields` | JSON | oui | Tableau des noms techniques de champs |
| `state` | string | oui | `active` ou `inactive` |

**Exemple curl :**

```bash
curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php 
  -d "operation=set_field_visibility" 
  -d "sessionName=YOUR_SESSION_ID" 
  -d "moduleName=Products" 
  -d 'fields=["mdsweight","vendor_id","mdscustomsnomenclature","mdsorigincountry"]' 
  -d "state=active"
```

### Réponse

```json
{
  "success": true,
  "result": {
    "module": "Products",
    "state": "active",
    "changed": ["mdsweight", "vendor_id", "mdscustomsnomenclature", "mdsorigincountry"],
    "unchanged": [],
    "errors": []
  }
}
```

L'opération est **idempotente** : demander un état qu'un champ a déjà le range dans `unchanged` sans
 rien écrire. Vous pouvez donc rejouer votre script de paramétrage sans réfléchir à ce qui est déjà
 fait.

Un champ activé est ajouté **à la fin de son bloc** dans la fiche. Réorganisez ensuite l'ordre dans
 l'éditeur de présentation si la position par défaut ne vous convient pas.

### Ce que l'opération refuse, et pourquoi

Elle applique exactement les mêmes garde-fous que l'éditeur de présentation : un champ que l'écran
 refuse de masquer ne devient pas masquable parce que la demande arrive par l'API.

| Refus | Raison |
| --- | --- |
| Champ inconnu | Presque toujours une faute de frappe, ou un champ que votre version ne livre pas |
| Champ structurel | Le masquer casserait la fiche (ex : le nom de l'article) |
| Champ obligatoire | Le masquer rendrait toute création manuelle impossible |
| Champ jamais affiché dans les écrans | Sa visibilité n'est pas un réglage |

Chaque refus revient dans `errors` avec son motif, et **n'empêche pas** le traitement des autres
 champs du même appel.

---

## Ce que l'opération ne fait pas

Elle ne **crée** pas de champ. Ajouter un champ personnalisé modifie le schéma de données : cela
 reste l'affaire de l'éditeur de présentation, dans *Paramètres > Éditeur de présentation*.

---

## Références associées 🔗

- [Opérations CRUD](https://www.kafinea.com/fr/documentation/api/api-rest-operations-crud/)
- [Listes déroulantes](https://www.kafinea.com/fr/documentation/api/api-rest-picklist/)
- [Import en masse](https://www.kafinea.com/fr/documentation/api/api-rest-import-en-masse/)
- [Introduction API](https://www.kafinea.com/fr/documentation/api/api-rest-introduction/)