Au cours de la deuxième moitié de 2020, Salesforce a mis à disposition une nouvelle API nommée Commerce API. Celle-ci permet de faire du développement appelé headless car tout le back-end est découplé du front-end.

Cette toute nouvelle API n’est pas à confondre avec Open Commerce API (OCAPI). Cette dernière n’est pour l’instant pas dépréciée et Salesforce continuera à la maintenir, mais probablement que les évolutions futures ne se feront que sur Commerce API (affaire à suivre). Aussi, toutes les API OCAPI ne seront pas forcément reproduites en Commerce API, il est donc conseillé de regarder ce que font les deux pour savoir laquelle utiliser et quand.

Dans cet article nous allons uniquement parler de Commerce API : comment s’authentifier et faire quelques appels API. Je partagerai enfin une collection Postman qui permettra d’avoir un support pour vos développements futurs.

C’est parti !

⚠️ Important ⚠️

Pour pouvoir s’authentifier sur les API Salesforce, il faut au préalable avoir un accès administrateur sur Account Manager et disposer d’un accès back-office à une instance du PIG (Development / Staging / Production). Si vous n’avez pas ces éléments, je vous invite à vous rapprocher de votre administrateur ou de Salesforce.

Création de l’API Client

Que ce soit pour OCAPI ou pour Commerce API, il faut se créer un utilisateur API. Pour se faire, rendez vous dans votre espace Account Manager, section API Client et cliquez sur Add API Client.

Création d'un client API sur Account Manager
Création d'un client API sur Account Manager

Donnez ensuite un nom clair à votre utilisateur API, je vous conseille de faire un utilisateur pour vos tests et un utilisateur pour la production, et sélectionnez l’organisation voulue. Dans la section Roles, cliquez sur Add, et ajoutez le rôle Salesforce Commerce API.

Une fois le rôle ajouté, il faut cliquer sur le symbole filtre, et sélectionner la sandbox/plateforme sur laquelle l’utilisateur API fonctionnera. Dans notre cas, ce sera une sandbox de test.

Assigner un rôle et une ou plusieurs instances à un utilisateur API
Assigner un rôle et une ou plusieurs instances à un utilisateur API

Il faut désormais donner les permissions voulues pour cet utilisateur API. Voici un exemple.

sfcc.catalogs.rw
sfcc.products.rw

Ces deux lignes offrent un accès en lecture et écriture aux API des catalogues et des produits. Vous trouverez la liste exhaustive des permissions disponibles dans la documentation officielle de Commerce API.

Enfin, sélectionnez client_secret_post comme méthode d’authentification, et JWT comme format de token. Vous pouvez maintenant valider la création de votre utilisateur API.

Paramètres Commerce API de l’infrastructure

À ce stade, vous avez un client ID et un client password. C’est bien, mais pas suffisant pour utiliser toutes les API de Commerce API. Pour cela, il faut déjà savoir sur quelle instance vous allez faire vos appels : une sandbox, Development, Staging, ou Production ?

Une fois que vous avez déterminé l’instance, rendez vous dans le Business Manager à la page Administration > Site Development > Salesforce Commerce API Settings. Vous devriez alors voir les informations nécessaires.

Récupération du Short Code et de l'Organization ID
Récupération du Short Code et de l'Organization ID

Dans cette page, s’affichent le Short Code et l’Organization ID.

Par la suite, je vais découper l’Organization ID en plusieurs morceaux : il commence toujours par f_ecom, suivi de l’ID de votre realm, puis de l’instance (dev pour Development / stg pour Staging / prd pour Production).

Nous avons donc tout ce qu’il nous faut :

  • api_client_id : identifiant du client créé dans l’Account Manager.
  • api_client_secret : mot de passe du client créé dans l’Account Manager.
  • short_code : ce que nous venons d’obtenir dans le Business Manager, il est commun à tout votre PIG.
  • realm_id : sous-partie de l’Organization ID (sous la forme f_ecom_REALM_INSTANCE).
  • instance_id : sous-partie de l’Organization ID (sous la forme f_ecom_REALM_INSTANCE).
  • site_id : identifiant du site sur lequel vous voulez faire les appels (récupéré dans Administration > Sites > Manage Sites).

Récupération du jeton (token)

Les différents types d’API

Maintenant que nous avons un utilisateur API, nous pouvons nous authentifier sur Commerce API et ainsi récupérer un jeton, ou token, qu’il faudra par la suite transmettre à chaque appel.

Une chose à savoir avant de se lancer, il existe deux types d’authentification possibles.

  • JWT token pour utiliser les API de type Shopper APIs.
  • OAuth access-token pour utiliser les API de type Management APIs.

Les Shopper APIs sont globalement celles qu’il faut utiliser pour le storefront (passer des commandes, s’authentifier, etc). Vous pouvez les retrouver en allant sur la documentation officielle et en filtrant avec le mot clef Shopper.

Liste des API Shopper
Liste des API Shopper

Toutes les autres API sont considérées comme des Management APIs. Elles permettent de gérer les groupes d’utilisateurs par exemple, ou encore les coupons, etc. Je ne vais pas lister ici toutes les possibilités, je vous laisse consulter la documentation qui en plus aura le mérite d’évoluer au fur et à mesure des mises à jour.

Obtenir le token pour les API Shopper

Pour les API de type Shopper, il faut se mettre à la place d’un utilisateur. Celui-ci peut être soit connecté, soit déconnecté. Il y a donc un appel API pour chacun de ces deux cas.

Demande d’un token guest

Un utilisateur déconnecté est un guest. Si vous n’avez pas la possibilité de le connecter, car vous n’avez pas ses identifiants par exemple, alors c’est celui-ci qu’il vous faut. Pour l’obtenir, il est nécessaire d’effectuer l’appel suivant.

Type POST
URL https://{short_code}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/f_ecom_{realm_id}_{instance_id}/customers/actions/login?siteId={site_id}&clientId={api_client_id}
Données postées aucune
Contenu de l’appel { "type": "guest" }

En-tête de la réponse

Allow: DELETE,OPTIONS,POST
Authorization: Bearer LeSuperTokenIci

Contenu de la réponse

{
   "authType": "guest",
   "customerId": "ac7oo5FaCFGW9vZBPXyyqbbT8T",
   "preferredLocale": "fr_FR"
}

Voilà, vous venez d’obtenir le token (dans l’en-tête du retour) ainsi que le customerID qui sera utile pour les appels futurs. La locale, quant à elle, vous aide à construire votre application dans la bonne langue.

Demande d’un token pour utilisateur authentifié

Lorsque votre application a accès aux identifiants, ou les obtient suite à un formulaire d’authentification, vous pouvez demander un token pour que vos appels à Commerce API persistent les modifications dans le compte de l’utilisateur.

La demande de token est similaire à la méthode précédente à l’exception du contenu de l’appel, et du fait qu’il faille envoyer l’identifiant et mot de passe. Il s’agit d’une authentification Basic. Il faut donc envoyer le base64 de l’identifiant et du mot de passe séparés par :.

Ce qui pourrait donner base64(“myuser:MyGr3atPwd!”), par exemple.

Type POST
URL https://{short_code}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/f_ecom_{realm_id}_{instance_id}/customers/actions/login?siteId={site_id}&clientId={api_client_id}
Données postées Authorization: Basic bXl1c2VyOk15R3IzYXRQd2Qh
Contenu de l’appel { "type": "credentials" }

En-tête de la réponse

Allow: DELETE,OPTIONS,POST
Authorization: Bearer LeSuperTokenIci

Contenu de la réponse

{
   "authType": "registered",
   "birthday": "1901-01-01",
   "creationDate": "2017-12-21T17:34:50.000Z",
   "customerId": "abf532er5axNquq3Btrtbl3oXv",
   "customerNo": "00000001",
   "email": "monemail@mail.com",
   "enabled": true,
   "firstName": "Thibault",
   "gender": 0,
   "lastLoginTime": "2021-05-20T11:57:29.770Z",
   "lastModified": "2021-05-20T11:57:29.770Z",
   "lastName": "Test",
   "lastVisitTime": "2021-05-20T11:57:29.770Z",
   "login": "monemail@mail.com",
   "phoneMobile": "0612345678",
   "previousLoginTime": "2021-05-18T15:38:10.000Z",
   "previousVisitTime": "2021-05-18T15:38:10.000Z"
}

Obtenir le token pour les API Management

Tout comme la demande d’un token pour un utilisateur authentifié, il est nécessaire d’envoyer une authentification de type Basic, avec l’identifiant et le mot de passe de l’utilisateur API créés précédemment. Voici les données à poster.

  • grant_type: il faudra mettre client_credentials.
  • scope: permissions que vous souhaitez obtenir pour les appels API futurs. Il est important de préfixer les autorisations par SALESFORCE_COMMERCE_API:{realm_id}_{instance_id}.
Demande de token pour API Management
Demande de token pour API Management

Contenu de la réponse

{
   "access_token": "LeSuperTokenIci",
   "scope": "sfcc.catalogs sfcc.orders.rw mail sfcc.products.rw sfcc.promotions.rw sfcc.products sfcc.catalogs.rw SALESFORCE_COMMERCE_API:abcd_dev",
   "token_type": "Bearer",
   "expires_in": 1799
}

Nous avons désormais récupéré des tokens pour tous les cas possibles (API Shopper guest ou authentifié, API Management). Nous pouvons maintenant développer notre application et effectuer les vraies requêtes.

Important

Vous ne pouvez pas demander des autorisations pour les API Shopper lors d’une demande de token d’API Management.

Quelques appels

Nous voici dans la partie intéressante : nous avons les informations de connexion et nous pouvons nous amuser avec les API classiques. Je ne vais pas présenter ici toutes les API, mais une ou deux afin de se faire la main. Pour le reste, je vous laisse consulter la documentation officielle.

Le but sera de rechercher un produit et de l’ajouter au panier. En affichant les API de type Shopper dans la documentation officielle, on voit 10 résultats. Dans ces résultats, on trouve ce qui nous intéresse : Shopper Search et Shopper Basket. On ne va pas aller jusqu’au passage de commande, mais si vous voulez aller jusque-là vous avez aussi Shopper Orders.

Avec Shopper Search, nous allons rechercher un produit dans le catalogue, puis nous allons créer un panier, et ajouter un des produits dans ce panier avec Shopper Basket.

Tout commence par l’onglet API Specification de la documentation. Celui-ci donne l’URL de base de l’API, toutes les API ont une URL spécifique, ici : https://{shortCode}.api.commercecloud.salesforce.com/search/shopper-search/{version}.

Si vous sélectionnez les endpoints disponibles dans le menu, vous trouverez GET productSearch donnant les détails de ce qu’il faut envoyer et à quelle URL.

  • Type : GET
  • URL : /organizations/{organizationId}/product-search
  • Header requis : le token Bearer
  • Paramètres :
    • siteId : requis (l’identifiant du site Salesforce à requêter)
    • q : optionnel, mais on va le fournir (il s’agit de la recherche à faire)

Il suffit donc tout simplement de s’authentifier (guest ou non), puis d’exécuter cette requête avec le token reçu et la recherche que vous souhaitez faire (paramètre q). L’API vous retournera un JSON avec le résultat de la recherche ! Pour ma part, je vais prendre le premier produit retourné et l’ajouter au panier.

Shopper Basket

La création d’un panier (basket en anglais) peut se faire en une ou plusieurs fois.

  1. Vous avez toutes les informations à mettre dans le panier (produits, modes de livraison, etc) et vous pouvez tout envoyer en un appel.
  2. Vous créez un panier vide et le modifiez au fur et à mesure.

Dans notre cas, nous allons choisir l’option 2 et faire un premier appel pour créer le panier.

Comme dans la partie précédente, tout commence par la documentation Shopper Basket. Dans l’onglet Developer Guide, vous trouverez beaucoup d’informations intéressantes sur comment procéder, je vous conseille de le lire si vous n’êtes pas au point sur cette notion de panier, et de tout ce qu’il est censé contenir. Pour les autres, rendez-vous sur l’onglet API Specification pour trouver l’URL de base des API Basket: https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/{version}.

Allez ensuite dans le menu dans Endpoints > /organizations/{organizationID} > /baskets > createBasket.

Aperçu de la documentation de l'API createBasket
Documentation sur l'API createBasket

Nous allons créer un panier vide, nous n’avons donc qu’à fournir le paramètre siteId sans body.

  • Type : POST
  • URL : /baskets?siteId={site_id}
  • Header requis : le token Bearer
  • Contenu de l’appel : {}

Le retour de l’API peut impressionner, car d’un JSON vide, Salesforce renvoie beaucoup d’informations. C’est normal, comme je l’ai évoqué plus haut un panier contient de nombreuses choses. Un panier vide a quand même un objet shipment, des informations de taxe, etc.

Nous allons surtout avoir besoin du basketId qui est retourné, car pour mettre à jour ce panier, il nous faudra envoyer son identifiant ! Nous n’avons plus qu’à ajouter notre produit au panier. Pas besoin de changer de page de documentation, il faut aller via le menu dans Endpoints > /organizations/{organizationID} > /baskets > /{basketID} > /items > addItemToBasket.

Aperçu de la documentation de l'API addItemToBasket
Documentation sur l'API addItemToBasket

Nous avons récupéré le basketID dans l’appel précédent, et le product ID dans la partie précédente. Nous avons donc toutes les informations pour ajouter ce produit au panier.

  • Type : POST`
  • URL : /baskets/{basket_id}/items?siteId={site_id}
  • Header requis : le token Bearer
  • Contenu de l’appel : [ { "productId": "{product_id}", "quantity": 1 } ]

Bravo ! Vous venez : de chercher un produit, de créer un panier et d’ajouter un produit dans ce panier. Désormais, vous avez tout pour créer une application Headless en utilisant les API fournies par Salesforce. Dans la partie suivante, je vais vous partager une collection Postman qui permet de rejouer tous les appels qu’on a vu dans ce tutoriel, mais nous n’apprendrons rien de plus. Have fun!

Collection Postman

Je pars du principe que vous connaissez Postman et comment le logiciel fonctionne dans ce chapitre. Voici une collection Postman qui permet de faire les appels que nous avons vus dans ce tutoriel : https://github.com/EmakinaFR/salesforce-commerce-api-postman.

Vous pouvez cloner ou télécharger les fichiers JSON, et les importer dans votre logiciel. Ensuite, sélectionnez l’environnement Commerce API et modifiez les variables pour vos valeurs. L’arborescence de la collection ne devrait pas vous surprendre : une partie Shopper APIs et une partie Management APIs.

Pour s’authentifier sur la partie Shopper API, il faut utiliser les API nommées Authenticate manually registered ou Authenticate manually guest en fonction de ce que vous souhaitez. Lorsque vous exécuterez ces appels, vous aurez en retour un customerId. Pas besoin de le copier et de le coller dans les appels suivants, car dans l’onglet Tests un bout de code est mis en place pour sauvegarder ce customerID dans une variable d’environnement qui sera réutilisée par la suite.

Pour les API de type Management, il faut demander le token en cliquant sur le répertoire Management APIs et en cliquant sur le bouton Get new access token tout en bas. Le token qui sera donné sera utilisé dans toutes les API sous ce répertoire (elles héritent du token). Il y a aussi un appel nommé Authenticate manually pour les API Management mais il vaut mieux passer par le répertoire Management APIs, car il n’y a rien pour sauvegarder le token dans celle-ci. Elle est là uniquement pour que vous sachiez comment l’appel API fonctionne pour s’authentifier, au cas où vous voudriez le refaire dans votre langage de programmation favoris.

Tout le reste est dans le README.md du projet, n’hésitez pas à contribuer.

Merci !

Liens utiles