View Categories

API REST – Champs d’un module

5 minutes

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

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

Réponse #

{
  "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.

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 :

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 #

{
  "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 🔗 #