{"id":444873,"date":"2026-09-18T00:58:16","date_gmt":"2026-09-17T22:58:16","guid":{"rendered":"https:\/\/www.kafinea.com\/documentation\/uncategorized\/api-rest-champs-de-module\/"},"modified":"2026-09-18T00:58:16","modified_gmt":"2026-09-17T22:58:16","password":"","slug":"api-rest-champs-de-module","status":"publish","type":"docs","link":"https:\/\/www.kafinea.com\/fr\/documentation\/api\/api-rest-champs-de-module\/","title":{"rendered":"API REST – Champs d’un module"},"content":{"rendered":"

Kafinea livre un catalogue de champs<\/strong> et vous activez<\/strong> ceux dont votre m\u00e9tier a besoin. Un
\nlibraire veut le poids, la nomenclature douani\u00e8re et le pays d’origine sur ses articles ; une soci\u00e9t\u00e9
\nde services n’en veut aucun. C’est pourquoi la plupart des champs sont livr\u00e9s disponibles mais non
\nactiv\u00e9s, et pourquoi votre fiche article ne s’ouvre pas sur cent champs vides.<\/p>\n

Deux op\u00e9rations donnent \u00e0 cette m\u00e9canique une interface programmable : lister ce qui existe, puis
\nactiver ce qui vous sert.<\/p>\n

\n\n\n\n\n\n\n
Op\u00e9ration<\/th>\nM\u00e9thode<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
describe<\/code><\/td>\nGET<\/td>\nD\u00e9crire un module, champs non activ\u00e9s compris sur demande<\/td>\n<\/tr>\n
set_field_visibility<\/code><\/td>\nPOST<\/td>\nActiver ou d\u00e9sactiver des champs d’un module<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
\n

Activer un champ est r\u00e9serv\u00e9 aux administrateurs.<\/strong> Modifier la pr\u00e9sentation d’un module est du
\nparam\u00e9trage, pas de la saisie : set_field_visibility<\/code> refuse tout compte non administrateur.<\/p>\n<\/blockquote>\n

\n

Describe \u2013 Lister les champs, activ\u00e9s ou non<\/h2>\n

describe<\/code><\/a> r\u00e9pond par d\u00e9faut \u00e0 la question \u00ab que puis-je lire et \u00e9crire
\nmaintenant<\/strong> \u00bb et ne renvoie donc que les champs activ\u00e9s<\/strong>.<\/p>\n

Cons\u00e9quence importante si vous pr\u00e9parez une reprise de donn\u00e9es : un champ absent de la r\u00e9ponse par
\nd\u00e9faut peut tout aussi bien ne pas exister<\/strong> dans votre version de Kafinea que exister sans \u00eatre
\nactiv\u00e9<\/strong>. Confondre les deux fait perdre du temps, et parfois conclure \u00e0 tort qu’un d\u00e9veloppement est
\nn\u00e9cessaire.<\/p>\n

Le param\u00e8tre fieldStatus<\/code><\/strong> r\u00e9pond \u00e0 l’autre question : \u00ab qu’est-ce que ce module propose, et
\nqu’est-ce qui est allum\u00e9 ? \u00bb<\/p>\n

\n

GET<\/strong> https:\/\/apps.kafinea.com\/{instance}\/webservice.php<\/code><\/p>\n<\/blockquote>\n

\n\n\n\n\n\n\n\n\n
Param\u00e8tre<\/th>\nType<\/th>\nRequis<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
operation<\/code><\/td>\nstring<\/td>\noui<\/td>\nDoit \u00eatre describe<\/code><\/td>\n<\/tr>\n
sessionName<\/code><\/td>\nstring<\/td>\noui<\/td>\nIdentifiant de session<\/td>\n<\/tr>\n
elementType<\/code><\/td>\nstring<\/td>\noui<\/td>\nNom du module (ex : Products<\/code>, Accounts<\/code>)<\/td>\n<\/tr>\n
fieldStatus<\/code><\/td>\nstring<\/td>\nnon<\/td>\nactive<\/code> (d\u00e9faut), all<\/code> ou inactive<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n

Sans fieldStatus<\/code>, la r\u00e9ponse est exactement<\/strong> celle que vous connaissez : vos int\u00e9grations
\nexistantes ne changent pas.<\/p>\n

\n

all<\/code> et inactive<\/code> sont r\u00e9serv\u00e9s aux administrateurs.<\/strong> La liste des champs que personne n’a
\nactiv\u00e9s d\u00e9crit le param\u00e9trage de l’instance, pas des donn\u00e9es : elle n’est pas montr\u00e9e \u00e0 un compte
\nrestreint. Sans le param\u00e8tre, describe<\/code> reste ouvert \u00e0 tous et applique les droits du compte, comme
\navant.<\/p>\n<\/blockquote>\n

Exemple curl :<\/strong> les champs disponibles mais non activ\u00e9s sur les articles.<\/p>\n

curl "https:\/\/apps.kafinea.com\/YourKafinea\/webservice.php?operation=describe&sessionName=YOUR_SESSION_ID&elementType=Products&fieldStatus=inactive"\n<\/code><\/pre>\n
R\u00e9ponse<\/h3>\n
{\n  "success": true,\n  "result": {\n    "label": "Articles",\n    "name": "Products",\n    "fields": [\n      {\n        "name": "mdscustomsnomenclature",\n        "label": "Nomenclature douani\u00e8re",\n        "mandatory": false,\n        "type": { "name": "string" },\n        "editable": false,\n        "active": false\n      }\n    ]\n  }\n}\n<\/code><\/pre>\n
\n\n\n\n\n\n\n\n\n
Champ<\/th>\nSignification<\/th>\n<\/tr>\n<\/thead>\n
name<\/code><\/td>\nLe nom technique, \u00e0 reprendre tel quel dans les autres op\u00e9rations<\/td>\n<\/tr>\n
label<\/code><\/td>\nLe libell\u00e9 tel que l’utilisateur le voit, dans la langue de votre session<\/td>\n<\/tr>\n
active<\/code><\/td>\nfalse<\/code> = livr\u00e9 et disponible, mais invisible sur cette instance<\/td>\n<\/tr>\n
editable<\/code><\/td>\nToujours false<\/code> sur un champ non activ\u00e9 : activez-le d’abord pour pouvoir l’\u00e9crire<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Avec fieldStatus=all<\/code>, les champs activ\u00e9s portent \u00e9galement active<\/code> (\u00e0 true<\/code>), ce qui permet de
\ntrier la liste sans second appel. Les valeurs autoris\u00e9es d’une liste d\u00e9roulante non encore activ\u00e9e se
\nlisent avec getPicklistValues<\/code><\/a>.<\/p>\n
\n
FieldVisibility \u2013 Activer ou d\u00e9sactiver des champs<\/h2>\n
\n
POST<\/strong> https:\/\/apps.kafinea.com\/{instance}\/webservice.php<\/code><\/p>\n<\/blockquote>\n
\n\n\n\n\n\n\n\n\n\n
Param\u00e8tre<\/th>\nType<\/th>\nRequis<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
operation<\/code><\/td>\nstring<\/td>\noui<\/td>\nDoit \u00eatre set_field_visibility<\/code><\/td>\n<\/tr>\n
sessionName<\/code><\/td>\nstring<\/td>\noui<\/td>\nIdentifiant de session<\/td>\n<\/tr>\n
moduleName<\/code><\/td>\nstring<\/td>\noui<\/td>\nNom du module<\/td>\n<\/tr>\n
fields<\/code><\/td>\nJSON<\/td>\noui<\/td>\nTableau des noms techniques de champs<\/td>\n<\/tr>\n
state<\/code><\/td>\nstring<\/td>\noui<\/td>\nactive<\/code> ou inactive<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Exemple curl :<\/strong><\/p>\n
curl -X POST https:\/\/apps.kafinea.com\/YourKafinea\/webservice.php \\\n  -d "operation=set_field_visibility" \\\n  -d "sessionName=YOUR_SESSION_ID" \\\n  -d "moduleName=Products" \\\n  -d 'fields=["mdsweight","vendor_id","mdscustomsnomenclature","mdsorigincountry"]' \\\n  -d "state=active"\n<\/code><\/pre>\n
R\u00e9ponse<\/h3>\n
{\n  "success": true,\n  "result": {\n    "module": "Products",\n    "state": "active",\n    "changed": ["mdsweight", "vendor_id", "mdscustomsnomenclature", "mdsorigincountry"],\n    "unchanged": [],\n    "errors": []\n  }\n}\n<\/code><\/pre>\n
L’op\u00e9ration est idempotente<\/strong> : demander un \u00e9tat qu’un champ a d\u00e9j\u00e0 le range dans unchanged<\/code> sans
\nrien \u00e9crire. Vous pouvez donc rejouer votre script de param\u00e9trage sans r\u00e9fl\u00e9chir \u00e0 ce qui est d\u00e9j\u00e0
\nfait.<\/p>\n
Un champ activ\u00e9 est ajout\u00e9 \u00e0 la fin de son bloc<\/strong> dans la fiche. R\u00e9organisez ensuite l’ordre dans
\nl’\u00e9diteur de pr\u00e9sentation si la position par d\u00e9faut ne vous convient pas.<\/p>\n
Ce que l’op\u00e9ration refuse, et pourquoi<\/h3>\n
Elle applique exactement les m\u00eames garde-fous que l’\u00e9diteur de pr\u00e9sentation : un champ que l’\u00e9cran
\nrefuse de masquer ne devient pas masquable parce que la demande arrive par l’API.<\/p>\n
\n\n\n\n\n\n\n\n\n
Refus<\/th>\nRaison<\/th>\n<\/tr>\n<\/thead>\n
Champ inconnu<\/td>\nPresque toujours une faute de frappe, ou un champ que votre version ne livre pas<\/td>\n<\/tr>\n
Champ structurel<\/td>\nLe masquer casserait la fiche (ex : le nom de l’article)<\/td>\n<\/tr>\n
Champ obligatoire<\/td>\nLe masquer rendrait toute cr\u00e9ation manuelle impossible<\/td>\n<\/tr>\n
Champ jamais affich\u00e9 dans les \u00e9crans<\/td>\nSa visibilit\u00e9 n’est pas un r\u00e9glage<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Chaque refus revient dans errors<\/code> avec son motif, et n’emp\u00eache pas<\/strong> le traitement des autres
\nchamps du m\u00eame appel.<\/p>\n
\n
Ce que l’op\u00e9ration ne fait pas<\/h2>\n
Elle ne cr\u00e9e<\/strong> pas de champ. Ajouter un champ personnalis\u00e9 modifie le sch\u00e9ma de donn\u00e9es : cela
\nreste l’affaire de l’\u00e9diteur de pr\u00e9sentation, dans Param\u00e8tres > \u00c9diteur de pr\u00e9sentation<\/em>.<\/p>\n
\n
R\u00e9f\u00e9rences associ\u00e9es \ud83d\udd17<\/h2>\n