Développeurs · Guides

Créez une clé et décidez de ce qu’elle peut atteindre

Un programme appelle l’API d’Ultineo E-commerce avec une clé qui appartient à une seule boutique. Un administrateur du projet la crée dans l’espace de travail et choisit, une fois pour toutes, ce qu’elle peut atteindre et quand elle expire.

Ce qu’il faut avant de créer une clé

Une boutique ouverte

Une clé se crée dans le projet de la boutique : il vous faut donc d’abord une boutique ouverte. Une clé dont la boutique n’est plus active est refusée.

Un administrateur du projet

Créer, modifier et supprimer des clés est réservé aux administrateurs du projet. Un autre membre ouvre l’onglet et consulte la liste, mais n’a ni bouton pour créer une clé ni bouton pour en ouvrir le détail.

Les ressources à appeler

Chaque ressource a un droit de lecture et un droit d’écriture : un GET exige le droit de lecture, un POST le droit d’écriture. Dans l’espace de travail, « Lecture » et « Écriture » n’accordent chacune qu’elles-mêmes : une clé réglée sur « Écriture » ne peut pas lire.

De l’onglet Accès API à une clé qui fonctionne

1

Ouvrez l’onglet Accès API

Ouvrez votre projet dans l’espace de travail, puis l’onglet « Accès API », et cliquez sur « Créer une clé API ». Saisissez un nom qui distingue vos clés, jusqu’à 200 caractères.

2

Choisissez l’accès

Choisissez « Accès complet » ou « Accès restreint ». Le premier autorise toutes les routes, actuelles et futures ; le second, ce que vous choisissez par ressource : « Aucun accès », « Lecture », « Lecture et écriture » ou « Écriture ».

3

Choisissez l’expiration

Choisissez « 30 jours », « 90 jours », « 365 jours » ou « N’expire jamais ». L’accès, les permissions et l’expiration se choisissent une seule fois : pour les changer, créez une nouvelle clé et supprimez l’ancienne.

4

Copiez la clé une seule fois

Après la création, la liste affiche la nouvelle clé en haut, avec sa valeur complète. Copiez-la à ce moment-là : dès que vous quittez ou rechargez la liste, il ne reste qu’un aperçu de ses quatre derniers caractères.

5

Envoyez-la à chaque appel

Chaque appel présente la clé dans son en-tête Authorization. Elle appartient à une seule boutique : chaque lecture et chaque écriture est limitée à cette boutique, quoi que vous mettiez dans l’URL ou dans le corps.

6

Renommez, désactivez ou supprimez

Cliquez sur « Détail » sur la ligne d’une clé pour modifier son nom ou son statut. Désactiver bloque tous les appels qui utilisent la clé jusqu’à ce que vous la réactiviez ; la suppression est définitive.

La réponse à un appel sans le droit requis

Voici le refus que publie la documentation de référence pour un appel dont la clé n’a pas un droit, ici order:write. La clé doit détenir le droit nommé, la même ressource suivie de :*, ou *.

Refus

{
  "code": 403,
  "title": "Forbidden",
  "response": "The API key is missing the required scope: order:write"
}

Le statut est 403, et le message de response nomme le droit que la clé ne détient pas.

Ce qui peut mal tourner avec une clé

Une valeur de clé perdue

La valeur complète d’une clé est affichée une seule fois, et rien ne permet de la retrouver. Si vous la perdez, supprimez la clé et créez-en une autre.

Une expiration passée inaperçue

Atteindre sa date d’expiration ne change pas le statut d’une clé : la ligne affiche toujours « Activé », avec « (Expirée) » à côté de la date, et ses appels sont pourtant refusés. Surveillez la colonne « Expiration » et créez la clé de remplacement avant la date.

Un appel sans le droit requis

Un appel auquel il manque son droit est refusé avec 403 et un message nommant le droit manquant. Appelez avec une clé qui détient ce droit, ou cessez d’appeler ce point d’accès.

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.

Clés API

Votre premier appel

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

Espace boutique

Commencez chaque tâche dans le bon espace boutique

Intégrations

Connectez les services compatibles

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

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

Une clé commence par une boutique ouverte

Envoyez votre demande d’ouverture d’une boutique Ultineo E-commerce : les comptes sont ouverts après étude, et notre équipe vous répond par e-mail.

Questions

Un droit nomme une ressource et une action : product:read ou product:write, par exemple. Une clé peut aussi détenir product:*, qui accorde les deux actions sur cette ressource, ou *, qui accorde tout. Dans la liste de vos clés, une clé restreinte affiche une permission par ligne, écrite comme l’API la lit. Les bons de réduction utilisent les droits promotion, bien que leur chemin soit /v1/voucher/import.

Un appel sans clé, ou avec une clé expirée, répond 401 ; une clé inconnue ou désactivée, ou dont la boutique n’est plus active, répond 403 ; une clé à laquelle il manque un droit répond 403 en nommant ce droit. Le guide « Gérer les erreurs et les limites » donne le message de chaque refus et la conduite à tenir.

Non. Une clé appartient à une seule boutique, et un élément d’une autre boutique répond 404, exactement comme un élément qui n’existe pas. Une requête qui désigne un projet autre que la boutique de la clé est refusée avec 403 : retirez le champ project, la clé désigne déjà votre boutique.

N’accordez que les permissions dont l’intégration a besoin, et définissez une expiration pour qu’une clé divulguée cesse de fonctionner d’elle-même. Préférez une durée autour de laquelle planifier une rotation : une clé qui n’expire jamais ne peut être retirée qu’en la supprimant. Gardez la clé dans le système qui a besoin de la connexion, et appelez toujours l’adresse https://, car une seule requête en clair divulgue la clé en entier.