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.
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.
- 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.
- 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.
- 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.
- Migrer une boutique existante
Reprenez le catalogue, l’historique de ventes et le domaine de votre boutique, en vérifiant chaque étape.
- L’IA dans vos logiciels
Un raisonnement ajouté à un écran de votre logiciel, lancé par l’API puis relu par votre code.
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.