Remplissez votre boutique depuis un ERP ou un flux fournisseur
L’API d’Ultineo E-commerce permet à vos propres outils de remplir votre boutique et de la relire : une synchronisation avec votre ERP ou un flux fournisseur envoie des éléments par lots, puis relit n’importe quel élément pour le vérifier. Ce guide suit une connexion type, de la correspondance des clés à la synchronisation.
Ce qu’il faut régler avant de relier vos systèmes
- Une référence stable par élément
Chaque passage ultérieur reconnaît un élément par la clé envoyée la première fois. Le nom est la clé d’une caractéristique, d’une catégorie ou d’un groupe de produits : envoyer un nouveau nom crée donc un nouvel élément au lieu de renommer l’ancien.
- Une clé et son détenteur
Une fois la boutique ouverte, un administrateur de son projet crée la clé API dans l’onglet « Accès API » de l’espace de travail. Gardez-la dans le système qui a besoin de la connexion.
- Les données que couvre l’API
La documentation de référence couvre le catalogue, l’historique des ventes et les bons de réduction ; les colis, les adresses et les transporteurs relèvent de l’API d’Ultineo Logistics. Ne supposez pas que chaque écran de l’espace de travail possède un point d’accès équivalent.
Une connexion type, dans l’ordre
-
1
Faites correspondre vos clés Un produit est reconnu par son SKU ; une caractéristique, une catégorie ou un groupe de produits par son nom ; un élément de l’historique des ventes par external_id, votre référence pour cet élément.
-
2
Restreignez la clé À la création de la clé, choisissez « Accès restreint » et n’accordez, ressource par ressource, que ce dont la connexion a besoin. Une clé réglée sur « Écriture » ne peut pas lire : accordez « Lecture et écriture » là où la connexion relit aussi des éléments.
-
3
Envoyez un premier essai Envoyez un premier lot avec dry_run à true et lisez son rapport avant que rien ne soit écrit. Le guide « Importer par lots » décrit le mode essai et le rapport.
-
4
Importez dans l’ordre recommandé Importez d’abord le catalogue : les caractéristiques, puis les catégories, puis les groupes de produits, puis les produits. Viennent ensuite l’historique des ventes, les clients avant les commandes, puis les bons de réduction.
-
5
Lancez la synchronisation À chaque passage, renvoyez les éléments : un élément déjà présent dans votre boutique est mis à jour si quelque chose a changé, ou signalé comme unchanged, et n’est jamais créé deux fois. Un passage interrompu se rejoue depuis le début.
-
6
Relisez pour vérifier Relisez n’importe quel élément par un GET sur son chemin d’import, un produit par son SKU par exemple, pour vérifier ce qui a été enregistré. La page « Catalogue, commandes et bons de réduction » passe les ressources en revue une à une.
Un produit envoyé, puis relu
Les deux exemples viennent de l’article « Catalogue » de la documentation de référence et portent sur le même produit. Les lignes qui ne contiennent que trois points marquent les coupes.
Import d’un produit
curl https://api.ultineo.com/v1/product/import \
-H "Authorization: Bearer sk-project-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"sku": "IP13-128-MID",
...
"currency": "EUR",
...
"grades": [
{ "grade": "very_good", "price": 459.00, "stock": 6 },
{ "grade": "good", "price": 419.00, "stock": 3 }
],
...
}
]
}' Le SKU est la clé du produit, et chaque niveau d’état porte son propre prix et son propre stock.
Produit relu
{
"code": 200,
"title": "OK",
"response": {
"object": "product",
"id": "prod_a81f3c6e0b2d49e7c5f0",
"sku": "IP13-128-MID",
"status": "activated",
...
"price": "419.00",
"price_compare": "729.00",
"currency": "EUR",
...
"stock": 9,
...
}
} Relu, price vaut 419.00, le plus bas des deux prix de niveau envoyés, et stock vaut 9, soit les 6 et 3 des deux niveaux d’état.
Les points à surveiller dans une synchronisation
- Un client modifié en boutique
Un champ de contact ou d’adresse d’un client a pu être modifié dans votre boutique depuis votre import précédent. Envoyez previous, les valeurs envoyées lors de cet import avec les mêmes clés : un champ qui en diffère a été modifié dans votre boutique depuis, et il est conservé.
- Prix et stock par niveau
Lorsqu’un produit a des niveaux d’état, son prix est le plus bas parmi ses niveaux et son stock la somme de leurs stocks : un prix ou un stock envoyé au niveau du produit n’est pas appliqué. Lisez le champ notice de l’entrée, qui le signale, et envoyez prix et stock sur chaque niveau d’état.
- Aucune action déclenchée
Les points d’accès de l’historique des ventes ne déclenchent aucune action : annuler une commande, émettre un remboursement ou contacter un transporteur se font dans votre espace de travail. Les marques et les garanties y sont créées aussi, et un import ne fait que s’y référer.
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
- Produits
Fiches produits, images et catégories
- Stocks et états
Quantités, mouvements et états
- Clients
Fiches clients, adresses et notes
- Commandes
Articles, paiements et expéditions liés
- Import et export
Modifiez le catalogue en masse avec un résultat lisible
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.
- Importer par lots
Le contrat commun à tous les imports : lots, mode essai, renvoi sans doublon et rapport.
- 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.
- 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 reliez vos systèmes
Envoyez votre demande d’ouverture de boutique : notre équipe l’étudie et vous répond par e-mail.
Questions
Pour les champs, oui : les champs que vous omettez dans une mise à jour gardent leur valeur enregistrée. Une liste enfant envoyée constitue en revanche l’ensemble complet : sur un produit, les niveaux d’état ou les photos omis sont désactivés ; omettez donc la liste lorsqu’elle n’a pas changé. La page « Catalogue, commandes et bons de réduction » nomme ces listes.
Non. Les points d’accès des commandes importent un historique de ventes et relisent une commande, par son external_id ou par son identifiant dans votre boutique. Les ressources importées n’ont ni liste, ni recherche, ni pagination.
Non. L’API fournit des éléments de connexion, pas un connecteur installé. Votre équipe technique ou votre prestataire construit et teste l’échange avec les points d’accès documentés.
L’API associe des photos déjà présentes dans vos médias ; elle ne téléverse pas de fichiers. Chaque entrée de la liste media d’un produit désigne, par son identifiant, un fichier déjà téléversé dans vos médias.