Développeurs · Guides

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.

Vue d’ensemble de l’API

Catalogue

Commandes & logistique

Votre premier appel

Stocks et états

Quantités, mouvements et états

Ouvrir la page

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.

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

Importer par lots

Le contrat commun à tous les imports : lots, mode essai, renvoi sans doublon et rapport.

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

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 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.