Développeurs · Guides

Importez vos données par lots et vérifiez chaque élément

Chaque import de l’API d’Ultineo E-commerce suit le même contrat : une liste d’éléments, un mode essai facultatif et un rapport ligne par ligne. Dès que vous avez importé une ressource, vous savez les importer toutes.

Ce qu’il vous faut avant votre premier lot

Une clé et ses droits

Un import est un POST, qui exige le droit d’écriture de sa ressource, et une lecture est un GET, qui exige son droit de lecture. Une clé est créée dans l’espace de travail par un administrateur du projet de votre boutique.

Une référence pour chaque élément

Chaque élément est reconnu par sa propre clé : sa référence d’origine dans votre ancien système (external_id), ou son SKU ou son nom pour le catalogue. Le rapport renvoie, pour chaque élément, la clé par laquelle il a été reconnu.

Des ensembles découpés en lots

Chaque ressource a sa propre limite de lot, de 25 à 500 éléments, indiquée dans son tableau de points d’accès. Les ensembles plus grands s’envoient en plusieurs lots.

Du premier lot à un import vérifié

1

Suivez l’ordre d’import

Les éléments font référence les uns aux autres : importez d’abord ceux dont les autres dépendent, le catalogue, puis l’historique des ventes, puis les bons de réduction. Un élément qui fait référence à un autre non importé est refusé.

2

Composez le lot

Envoyez un POST sur le chemin d’import de la ressource, avec une liste items, un objet par élément. La liste ne doit être ni vide, ni plus longue que la limite de lot de la ressource.

3

Envoyez en mode essai

Ajoutez dry_run à true : tout le lot est vérifié et le rapport indique ce qui serait créé, mis à jour, laissé inchangé ou refusé. Rien n’est écrit.

4

Lisez le rapport

La liste data contient une entrée par élément, dans l’ordre d’envoi, avec son action : created, updated, unchanged ou refused. Pour un élément refusé, reason indique ce qu’il faut corriger.

5

Envoyez l’import réel

Renvoyez le lot sans dry_run, qui vaut false par défaut. Un élément refusé n’arrête pas les autres : traitez-le selon son code et ce qu’indique reason, puis renvoyez-le.

6

Relisez un élément

Un GET sur le même chemin d’import renvoie un élément, désigné par sa clé ou par son identifiant dans votre boutique. Utilisez-le pour vérifier ce qui a été enregistré.

Un lot en mode essai et son rapport

Chaque import accepte le même corps et répond par le même rapport. Cet import de deux catégories en mode essai et le rapport qui y répond sont publiés ensemble dans l’article de référence « Catalogue ».

Requête en mode essai

curl https://api.ultineo.com/v1/category/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "items": [
      ...
      { "name": "iPhone", "parent": "Smartphones", "position": 1 }
    ]
  }'

Le corps porte dry_run à true et deux catégories, dont la première est coupée ici.

Rapport de cette requête

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "category",
    "dry_run": true,
    "data": [
      ...
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 1,
    "refused": 0,
    "total": 2
  }
}

Son champ dry_run vaut true, rien n’a donc été écrit, et ses quatre compteurs totalisent total, le nombre d’éléments envoyés.

Les points à surveiller dans un import

Un 200 avec des refus

Un élément refusé ne bloque jamais les autres : l’appel répond 200 dès qu’au moins un élément a été accepté, et 422 uniquement lorsque tous ont été refusés. Lisez le rapport ligne par ligne, même sur un 200.

Un rapport en mode essai

Le mode essai renvoie le rapport complet, comme un import réel, et n’écrit rien. Vérifiez toujours le champ dry_run de la réponse avant de vous fier à un rapport.

Un élément supprimé

Un import ne supprime rien, et il ne fait jamais revenir un élément supprimé. La suppression se fait dans votre espace de travail.

Les articles derrière cette page

Cette page reprend les articles suivants du centre d’aide. Ils détaillent chaque champ, chaque valeur et chaque réponse.

Votre premier appel

Codes d’erreur

Catalogue

Commandes & logistique

Import et export

Modifiez le catalogue en masse avec un résultat lisible

Ouvrir la page

Les pages produit à lire ensuite

Accès API

Reliez vos systèmes avec des accès adaptés à la boutique

Import et export

Modifiez le catalogue en masse avec un résultat lisible

Produits

Fiches produits, images et catégories

Clients

Fiches clients, adresses et notes

Commandes

Articles, paiements et expéditions liés

Poursuivre dans cette rubrique

Faire votre premier appel

L’adresse, le contrôle de disponibilité, la clé dans l’en-tête et la lecture de la réponse d’un premier appel.

Ouvrir la page

Gérer les clés et les accès

Qui crée une clé, ce qu’elle peut atteindre, quand elle expire et comment la renommer, la désactiver ou la supprimer.

Ouvrir la page

Gérer les erreurs et les limites

Ce que chaque statut de l’API demande à votre programme, et ce que vous pouvez renvoyer sans risque.

Ouvrir la page

Relier un ERP ou un flux fournisseur

Une connexion type depuis un autre système : clés à faire correspondre, premier essai, synchronisation et contrôles.

Ouvrir la page

Migrer une boutique existante

Reprenez le catalogue, l’historique de ventes et le domaine de votre boutique, en vérifiant chaque étape.

Ouvrir la page

L’IA dans vos logiciels

Un raisonnement ajouté à un écran de votre logiciel, lancé par l’API puis relu par votre code.

Ouvrir la page

Vue d’ensemble développeurs

Ouvrez votre boutique, puis envoyez votre premier lot

Une clé se crée dans une boutique ouverte, et les comptes sont ouverts après étude de votre demande par notre équipe.

Questions

Oui, avec dry_run à true. Dans ce rapport, l’id d’un élément qui serait créé vaut null. Pour un produit, ses champs propres sont comparés à ce qui est enregistré, tandis que ses niveaux d’état, ses caractéristiques et ses photos sont vérifiés mais pas comparés.

Rejouez-le depuis le début. Envoyer un élément déjà présent dans votre boutique le met à jour si quelque chose a changé, ou le signale comme unchanged ; il n’est jamais créé deux fois.

Non. Une mise à jour ne modifie que les champs que vous avez envoyés, et les champs omis gardent leur valeur enregistrée. Une liste enfant d’un élément du catalogue, comme les niveaux d’état d’un produit, suit une autre règle : la page « Catalogue, commandes et bons de réduction » la donne.

Sa structure est la même : une entrée par élément, puis les compteurs. Certaines ressources ajoutent leurs propres champs à chaque entrée, comme les lignes d’une commande ou les codes d’un bon de réduction, et l’article de référence de chaque ressource les décrit. Un élément accepté peut aussi porter des messages dans notice, par exemple une valeur qui a été ajustée.