API REST – Import en masse (upsert)

Cette page décrit l’opération à utiliser pour charger ou mettre à jour beaucoup d’enregistrements
d’un coup, en les désignant par une clef métier (un code article, une référence client, une
référence boutique) plutôt que par leur identifiant Kafinea.

Elle est générique : elle fonctionne pour tous les modules, avec la clef que vous choisissez.

Réservée aux administrateurs. Charger un lot d’enregistrements est un travail de reprise de
données. Un compte non administrateur garde create et update, un enregistrement à la fois, avec
ses propres droits.

---

Pourquoi pas create ou update ? #

Les opérations create et update restent la bonne réponse quand vous
écrivez un enregistrement à la fois. Pour une reprise de données, elles butent sur deux points :

• le volume : un enregistrement par appel, soit 16 000 appels pour 16 000 clients ;
• la reprise après interruption : create crée toujours. Un import coupé au milieu ne peut pas
  être relancé sans nettoyer d’abord ce qui est déjà passé, et update demande de connaître
  l’identifiant Kafinea, que vous n’avez justement pas encore.

mass_upsert retrouve l’enregistrement par sa clef métier : il met à jour ce qui existe, crée ce qui
manque, et n’écrit rien quand les valeurs envoyées sont déjà celles en place. Vous pouvez donc
relancer le même lot autant de fois que nécessaire.

---

Upsert – Écrire un lot d’enregistrements #

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

Chaque élément de elements est un objet champ : valeur, clef comprise. Les noms techniques des
champs se lisent avec describe.

Exemple curl : mettre à jour le poids et le pays d’origine d’articles reconnus par leur code.

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=mass_upsert" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d "elementType=Products" \
  -d 'keyFields=["productcode"]' \
  -d 'elements=[
        {"productcode":"9782070413110","productname":"Le Petit Prince","mdsweight":"0.180","mdsorigincountry":"FRA"},
        {"productcode":"9782070368228","productname":"La Peste","mdsweight":"0.150","mdsorigincountry":"FRA"}
      ]'

Réponse #

{
  "success": true,
  "result": {
    "module": "Products",
    "keyFields": ["productcode"],
    "processed": 2,
    "created": 1,
    "updated": 1,
    "unchanged": 0,
    "records": [
      { "index": 0, "id": "14x8842", "outcome": "updated" },
      { "index": 1, "id": "14x9317", "outcome": "created" }
    ],
    "errors": []
  }
}

---

Choisir la clef métier #

La clef est celle que vous nommez dans keyFields, et elle peut compter plusieurs champs. Elle doit
désigner un seul enregistrement : si la clef envoyée en retrouve plusieurs, la ligne est refusée
avec ce motif plutôt que d’en choisir un au hasard. Corrigez la donnée en double, puis renvoyez la
ligne.

Quelques clefs usuelles :

Les valeurs de clef sont comparées après suppression des espaces de début et de fin. Une valeur de
clef vide fait refuser la ligne : une clef métier ne se devine pas.

---

Rejouable : relancez sans crainte #

L’opération est idempotente. Le même lot envoyé deux fois donne unchanged au second passage :
ni doublon, ni date de modification inutilement remuée, ni ligne d’historique parasite sur les fiches.

De même, une ligne fautive n’annule pas les autres : les lignes valides du lot sont écrites, les
lignes refusées reviennent dans errors avec leur position, à corriger puis à renvoyer seules.

En revanche, si le paramètre elements lui-même n’est pas lisible (JSON invalide, plus de 500
éléments), l’appel entier est refusé : écrire la moitié d’un lot incompréhensible serait pire que de
n’en écrire aucune partie.

Enfin, l’opération n’ouvre aucune porte dérobée : elle applique les mêmes droits et les mêmes
contrôles de champs obligatoires que create et update. Ce que ces opérations refusent, celle-ci le
refuse aussi.

---

Cas d’usage : déclarer les identifiants d’un système extérieur #

Le besoin le plus fréquent est de dire à Kafinea quel enregistrement correspond à quel objet d’un
système extérieur : un client de votre boutique en ligne, un article de votre place de marché, une
fiche issue de votre ancien logiciel.

C’est la table de correspondance que Kafinea consulte avant toute tentative de rapprochement par
nom ou par e-mail. Une correspondance déclarée est une certitude, pas une supposition : elle
supprime les doublons de fiches clients à la source. Une correspondance porte trois informations :

L’unicité est garantie par système source, et c’est le point important. Un même client peut
porter un identifiant différent sur chacune de vos boutiques, et deux boutiques peuvent utiliser le
même numéro pour deux clients différents : la correspondance sait l’exprimer, un simple champ « réf.
externe » sur la fiche client ne le saurait pas.

curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php \
  -d "operation=mass_upsert" \
  -d "sessionName=YOUR_SESSION_ID" \
  -d "elementType=MdsExternalRef" \
  -d 'keyFields=["sourcesystem","objecttype","externalref"]' \
  -d 'elements=[
        {"sourcesystem":"onlinestore:44053","objecttype":"Accounts","externalref":"39146","recordid":"10x54325"},
        {"sourcesystem":"onlinestore:44053","objecttype":"Products","externalref":"3760174130121","recordid":"13x8842"}
      ]'

recordid désigne un enregistrement : il s’écrit et se relit comme tout lien vers un enregistrement
dans l’API, avec l’identifiant Webservice complet que renvoient query ou retrieve. Un
identifiant brut (54325) est refusé. L’enregistrement visé est ainsi un lien cliquable dans
Kafinea, et la fiche client affiche la liste de ses identifiants externes.

Les correspondances déclarées se relisent comme n’importe quel autre module, avec
query.

Reprendre une base clients existante #

Le scénario typique est la mise en service d’une boutique en ligne dont les clients existent déjà
dans Kafinea. Sans correspondances, la synchronisation ne peut que deviner, et crée des doublons.

1. Réglez, sur la fiche de la boutique, la reconnaissance du client sur « Réf. client boutique »
   (voir le paramétrage de la boutique en ligne).
2. Déclarez les correspondances par lots de 500, avec cette opération.
3. Lancez la synchronisation : chaque commande retrouve son client par identité.

Un client absent de la table n’est pas créé en silence si vous avez décoché « Créer les clients
depuis la boutique » : la commande est rattachée au client de repli de la boutique et l’anomalie est
nommée dans le journal de synchronisation. Vous complétez la correspondance, puis vous rafraîchissez
la commande depuis la boutique.

---

Références associées 🔗 #

• Opérations CRUD
• Champs d’un module
• Suppression en masse (corbeille)
• Requêtes et interrogation
• Introduction API