View Categories

API REST – Relations entre entités

2 minutes

Kafinea distingue trois concepts qui ne sont pas interchangeables :

Besoin Mécanisme à utiliser
Parcourir ou compléter une liste connexe affichée sur une fiche Opérations de listes connexes
Créer un lien qualifié, par exemple « bloque » ou « duplique » Opérations CRUD sur l’entité de lien qualifié
Gérer les composants et quantités d’un kit Opérations dédiées aux kits de produits

Toutes ces opérations s’exécutent avec les droits de l’utilisateur de la session. Une source non lisible, une source non modifiable ou une cible non lisible produit une erreur explicite.

Découvrir les listes connexes #

L’opération relatedtypes retourne les listes connexes disponibles pour un module et leur libellé technique. Utilisez toujours ce libellé dans relatedLabel pour la lecture et dans relationIdLabel pour l’ajout.

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

operation=relatedtypes
sessionName=YOUR_SESSION_ID
elementType=Accounts

Interroger une liste connexe #

L’opération query_related retourne les éléments d’une liste connexe. Le module indiqué dans la requête doit correspondre à celui annoncé par relatedtypes pour le libellé choisi.

curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=query_related&sessionName=YOUR_SESSION_ID&id=21x3456&relatedLabel=Documents&query=SELECT%20*%20FROM%20Documents%20WHERE%20filesize%20%3E%2010000"

retrieve_related permet également de lire une liste connexe selon la pagination standard de l’API.

Ajouter un élément à une liste connexe #

L’opération add_related complète une liste connexe existante. Elle ne convient pas aux kits, car une composition de kit porte une quantité et des règles métier supplémentaires.

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

Paramètre Type Requis Description
operation string oui Doit être add_related
sessionName string oui Identifiant de session
sourceRecordId string oui ID Webservice de l’élément source
relationIdLabel string oui Libellé technique retourné par relatedtypes
relatedRecordId string ou tableau oui Un ou plusieurs ID Webservice du même module 
curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=add_related" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d "sourceRecordId=21x3456" \
  -d "relationIdLabel=Documents" \
  -d "relatedRecordId=15x7890"

Si le libellé ne désigne aucune liste connexe compatible, l’API renvoie une erreur au lieu de signaler un succès sans modification.

La liste des produits spécifiques constitue un cas de relation dépendante : ajouter un produit à cette liste met à jour sa fiche pour lui affecter le produit générique comme parent. L’utilisateur doit donc pouvoir modifier les deux produits. Les validations métier et le recalcul tarifaire sont identiques à ceux de l’écran Kafinea. Consultez Produits génériques et spécifiques pour les exemples complets.

Manipuler les liens qualifiés #

Les liens qualifiés sont des entités à part entière. Ils se créent, se lisent, se modifient et se suppriment donc avec les opérations CRUD, comme les autres données Kafinea. Aucun endpoint spécialisé n’est nécessaire.

Le nom de module à utiliser est :

MdsEntityLink

Exemple de création :

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=create" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d "elementType=MdsEntityLink" \
  --data-urlencode 'element={"source_id":"46x101","target_id":"46x102","link_type":"blocks"}'

Champs utiles :

Champ Rôle
source_id Élément à l’origine du lien
target_id Élément ciblé
link_type Qualification : relates_to, blocks, duplicates ou parent_of

La création refuse les auto-liens, les doublons, les cycles hiérarchiques et toute référence que l’utilisateur ne peut pas lire. Pour retrouver ou supprimer un lien, utilisez respectivement query ou retrieve, puis delete avec l’ID Webservice retourné.

Références associées #