Développeurs · Guides

Faites votre premier appel à l’API E-commerce

L’API E-commerce permet à vos propres outils de remplir la boutique que vous tenez avec Ultineo E-commerce et de la relire. Ce guide va du contrôle de disponibilité à un premier appel abouti, et montre comment lire la réponse.

Ce qu’il vous faut avant le premier appel

Une clé pour votre boutique

La clé commence par sk-project- et détient les droits des ressources que vous appelez, en lecture, en écriture ou les deux. Un administrateur du projet la crée dans l’espace de travail, dans l’onglet « Accès API ».

Un outil pour envoyer des requêtes

Il vous faut un moyen d’envoyer une requête HTTP avec un corps JSON, par exemple curl. La documentation de référence donne un exemple curl complet.

L’adresse en HTTPS

Toutes les requêtes sont envoyées à https://api.ultineo.com/v1/. Seul HTTPS est servi.

Du contrôle de disponibilité à un appel abouti

1

Vérifiez que l’hôte répond

Appelez https://api.ultineo.com/health, le seul point d’accès qui ne demande aucune clé. Une réponse portant le code 200 et le titre OK montre que l’hôte est joignable.

2

Authentifiez-vous avec votre clé

Envoyez la clé comme jeton Bearer dans l’en-tête Authorization de chaque appel. Ajoutez l’en-tête Content-Type application/json uniquement lorsque vous envoyez un corps.

3

Relisez un élément

Commencez par une lecture : un GET sur le chemin d’import d’une ressource relit un élément, désigné par sa clé ou par son identifiant. L’exemple de la documentation de référence relit une catégorie par son nom, sur /v1/category/import.

4

Lisez le statut, puis response

La réponse est une enveloppe de trois clés : code, title et response. Lisez d’abord le code de statut HTTP, puis response, qui contient l’élément lorsque la lecture a réussi.

5

Préparez un premier import

Chaque import suit le même contrat POST, quelle que soit la ressource. Le guide « Importer par lots » décrit ce contrat.

Une requête et sa réponse

Cette requête relit une catégorie de la boutique par son nom. La réponse est l’enveloppe que renvoie chaque point d’accès.

Requête

curl "https://api.ultineo.com/v1/category/import?name=Smartphones" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

La clé circule dans l’en-tête Authorization, après le mot Bearer.

Réponse

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "category",
    "id": "cate_4be1a07f93c2d58e6a10",
    "name": "Smartphones",
...
    "status": "activated",
...
    "created_at": 1789143990,
    "updated_at": 1789143990
  }
}

L’enveloppe contient code, title et response, et response contient ici la catégorie.

Les points à surveiller au premier appel

Une requête en clair

Une requête sur http:// reçoit une redirection 301 vers le même chemin en https://, et la clé placée dans son en-tête a alors déjà circulé en clair. Appelez toujours directement l’adresse https:// au lieu de compter sur la redirection.

Une clé refusée

Une clé désactivée ou expirée est refusée, tout comme un appel dont la clé n’a pas le droit nécessaire. Lisez le message de response, puis le guide « Gérer les erreurs et les limites », qui indique ce que chaque statut demande à votre client.

Une lecture sans élément désigné

Une lecture qui ne fournit ni la clé de l’élément ni son identifiant reçoit un 400 : le paramètre de lecture est absent. L’article de référence de chaque ressource liste ses paramètres de lecture.

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

Vue d’ensemble de l’API

Clés API

Codes d’erreur

Accès API

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

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

Import et export

Modifiez le catalogue en masse avec un résultat lisible

Poursuivre dans cette rubrique

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

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

Votre clé se crée dans une boutique ouverte

Les comptes Ultineo E-commerce sont ouverts après étude : envoyez votre demande, et notre équipe vous répond par e-mail.

Questions

Aucun élément de votre boutique ne correspond à la clé ou à l’identifiant lu : vérifiez l’orthographe de la référence de l’élément, comme le nom de la catégorie de l’exemple. Un élément d’une autre boutique répond de la même façon. Si c’est le chemin lui-même qui n’existe pas, comparez-le aux tableaux de points d’accès de la documentation de référence.

Oui, pour les imports : un lot envoyé avec dry_run à true est vérifié en entier et rien n’est écrit. Le guide « Importer par lots » montre la requête et la lecture de son rapport.

Ne le supposez pas. L’article « Votre premier appel » liste chaque ressource avec ses droits, et la page « Catalogue, commandes et bons de réduction » indique ce qu’un programme envoie et relit pour chacune ; les colis, les adresses et les transporteurs relèvent de l’API d’Ultineo Logistics.

Elle se trouve dans le centre d’aide E-commerce, à la rubrique consacrée à l’API E-commerce. Elle est publique et rédigée en anglais et en français. Elle se lit sans compte.