Checkout pour Salesforce Commerce Cloud

Une fois metadata.zip préparé, importez-le dans votre bac à sable SFCC :

1. Accédez à Business Manager > Administration > Site Development > Site Import & Export.
2. Téléversez metadata.zip à l'aide de l'option de téléversement Local.
3. Après le téléversement, repérez l'archive dans la liste et cliquez sur Import.

Cette étape crée les préférences de site, les services, les identifiants et les objets personnalisés requis par l'intégration Zonos.

Ajoutez la cartouche int_zonos au chemin des cartouches de votre site pour activer ses contrôleurs, ses scripts et ses modèles :

1. Accédez à Administration > Sites > Manage Sites > [Your Target Site] > Settings.
2. Insérez int_zonos dans le chemin des cartouches avant la cartouche de vitrine SFRA de base (app_storefront_base).

La cartouche comprend 2 pipelines personnalisés auxquels vous devez ajouter des alias de pipeline dans Business Manager :

Zonos-OrderConfirmation

Ce pipeline sert à la confirmation de commande personnalisée dans SFCC une fois la commande finalisée dans le paiement Zonos. L'utilisateur y est redirigé. Par exemple, l'alias pourrait être zonos-order-confirmation. Choisissez et ajoutez un alias adapté à votre entreprise, différent de celui que vous utilisez pour la page de confirmation de commande native du paiement SFCC/SFRA (COSummary-Submit).

Zonos-PlaceSFCCOrder

Ce pipeline sert au point de terminaison personnalisé utilisé pour créer la commande Zonos dans SFCC/SFRA, et l'alias présumé est zonos-placesfccorder. Si vous utilisez un alias différent, vous devrez en prendre note lorsque vous arriverez à la configuration des services. Comme il ne s'agit pas d'une URL publique, nous vous recommandons d'utiliser zonos-placesfccorder lors de la configuration initiale afin de simplifier l'utilisation de cette cartouche.

Pour configurer ces deux alias, dans Business Manager, accédez à Merchant Tools > URL Rules > Pipeline URLs.

L'importation de site effectuée à l'étape 2 a créé deux services SFCC (avec les profils et identifiants associés) : zonos.api.graphql et create.order.api.sfra.

Configuration pour un seul site

Si votre organisation ne compte qu'un seul site de vitrine dans votre organisation SFCC, vous n'avez rien d'autre à faire ici et pouvez passer à l'étape suivante.

Configuration pour plusieurs sites

Si votre organisation compte plusieurs sites de vitrine, ou prévoit en avoir plusieurs, dans votre organisation SFCC, vous devrez mettre à jour vos services SFCC ou en ajouter. Lorsque plusieurs sites SFCC utilisent l'intégration Zonos, il vous faut un service API de création de commande pour chaque site. Pour chaque site, procédez comme suit :

1. Créez un nouvel identifiant nommé create.order.api.[siteID].
2. Attribuez-lui l'URL suivante : https://[Sandbox Host]/s/[Site ID]/Zonos-PlaceSFCCOrder (par exemple : https://wxyz-001.dx.commercecloud.salesforce.com/s/RefArch/zonos-placesfccorder).
3. Créez un nouveau service nommé create.order.api.[siteID] et attribuez-lui le profil create.order.api ainsi que l'identifiant create.order.api.[siteID] créé à l'étape 1.

Une fois ces étapes terminées, vous devriez disposer d'un service API de création de commande pour chacun de vos sites.

Remarque : si vous n'avez pas renommé le service create.order.api.sfra d'origine pour en faire le service de création de commande de l'un de vos sites et qu'il existe toujours, vous pouvez le supprimer. Conservez le nom du service zonos.api.graphql tel quel. Même avec plusieurs sites, un seul service API Zonos suffit.

Dans Business Manager, accédez à Merchant Tools > Site Preferences > Custom Preferences, puis cliquez sur le groupe de préférences zonos pour accéder aux préférences de site personnalisées Zonos.

Définissez les préférences de site suivantes pour votre ou vos sites :

Pendant le paiement modal Zonos, les acheteurs choisissent parmi les modes d'expédition définis dans votre Zonos Dashboard. Lorsque ces commandes sont importées dans SFCC, leurs modes d'expédition doivent correspondre à un mode d'expédition SFCC valide. Pour ce faire :

1. Configurez dans SFCC un ou plusieurs modes d'expédition auxquels vos modes d'expédition Zonos seront associés.
2. Dans la préférence de site personnalisée Zonos Ship Method Mapping décrite ci-dessus, établissez une ou plusieurs correspondances entre vos modes d'expédition Zonos et vos modes d'expédition SFCC.

Correspondance des modes d'expédition

Sous forme d'objet JSON, la correspondance des modes d'expédition associe vos modes d'expédition Zonos à vos modes d'expédition SFCC. Elle doit comporter une entrée pour chaque mode d'expédition Zonos (niveau de service) pouvant être sélectionné dans votre paiement Zonos. Il est fortement recommandé d'inclure aussi une entrée default, utilisée lorsqu'une commande Zonos est passée avec un mode d'expédition qui n'a pas de correspondance avec un mode d'expédition SFCC. Vous évitez ainsi les échecs en aval causés par l'absence de mode d'expédition dans la commande SFCC.

Le format de l'objet JSON est le suivant :

{
  "[Zonos Shipping Service Level Code]": "[SFCC Shipping Method ID]",
  ...
  "default": "[Default SFCC Shipping Method ID]"
}

Exemple

Supposons que vous ayez activé les niveaux de service suivants dans votre Zonos Dashboard :

Pour une raison ou une autre (p. ex. des exigences du système administratif, l'intégration d'un service d'expédition tiers supplémentaire, etc.), vous pourriez être limité aux modes d'expédition suivants dans SFCC pour votre site :

Lorsqu'une nouvelle commande Zonos est reçue puis créée dans SFCC, son mode d'expédition doit faire partie de cette liste.

Pour établir votre correspondance, connectez-vous à votre Zonos Dashboard, accédez à Shipping > Manage Rates, puis cliquez sur chacun des Enabled service levels affichés. Vous verrez un écran semblable à celui-ci :

Pour chacun, cliquez sur Edit details afin d'obtenir (ou de définir) le code du niveau de service d'expédition Zonos (voir ci-dessous).

À l'aide du code du niveau de service d'expédition, créez une entrée qui l'associe au mode d'expédition SFCC que vous voulez voir figurer sur vos commandes SFCC lorsque ce niveau de service (mode d'expédition Zonos) est choisi dans le paiement Zonos.

Une fois que vous avez ajouté une entrée pour chaque code de niveau de service d'expédition activé, ainsi qu'une correspondance default, votre objet JSON Zonos Ship Method Mapping devrait ressembler à ceci :

{
  "ups.worldwide_saver": "004",
  "ups.standard": "002",
  "ups.worldwide_expedited": "012",
  "ups.worldwide_express": "012",
  "default": "001"
}

Remarque : puisqu'il s'agit uniquement d'une correspondance des modes d'expédition Zonos vers les modes d'expédition SFCC, seul importe le fait d'y inclure tous les modes d'expédition Zonos. Il n'est pas nécessaire d'y inclure chacun de vos modes d'expédition SFCC.

L'installation comprend deux tâches (jobs) SFCC qui prennent en charge l'intégration Zonos :

CreateOrdersFromZonos

Cette tâche recherche les références de commandes Zonos nouvellement créées dans le magasin d'objets personnalisés zonosOrders, récupère tous les détails des commandes auprès de Zonos et crée les commandes correspondantes dans SFCC.

Planification : vous pouvez planifier cette tâche selon les besoins de votre entreprise, mais elle devrait généralement s'exécuter à intervalles réguliers, assez souvent (p. ex. toutes les 5 à 10 minutes), tous les jours de la semaine.

Paramètres personnalisés : la tâche CreateOrdersFromZonos ne comporte aucun paramètre personnalisé.

CreateMissingZonosOrders

Bien que ce soit rare, il est possible qu'en raison de circonstances imprévues, des commandes passées dans Zonos n'arrivent pas dans votre instance SFCC par le processus normal. C'est pourquoi nous avons inclus la tâche CreateMissingZonosOrders. Cette tâche effectue une vérification croisée entre votre historique de commandes Zonos et SFCC afin de repérer et d'importer les commandes manquantes.

Planification : vous pouvez planifier cette tâche selon les besoins de votre entreprise, mais elle devrait s'exécuter moins souvent que la tâche CreateOrdersFromZonos. Voici quelques éléments à prendre en compte pour déterminer la fréquence d'exécution de cette tâche :

1. Comme pour toutes les tâches, après avoir tenu compte de tous les facteurs, y compris la charge de traitement, la bande passante et les besoins de votre entreprise, planifiez cette tâche pour qu'elle s'exécute le moins souvent possible.
2. Puisque cette tâche interroge toutes les commandes sur une période donnée, les sites à volume élevé devraient l'exécuter plus souvent (pour traiter moins de commandes par exécution), alors que les sites à volume plus faible peuvent se contenter d'une fréquence moindre.
3. La fréquence de base que nous suggérons pour CreateMissingZonosOrders, et qui devrait convenir à la plupart des sites, est d'une fois toutes les 90 minutes.

Paramètres personnalisés : deux paramètres personnalisés associés à l'étape de la tâche CreateMissingZonosOrders doivent être définis :

1. LookBackHours : nombre d'heures (à partir du moment où la tâche s'exécute) sur lesquelles la tâche remonte dans le temps pour interroger Zonos à la recherche de commandes manquantes. Selon la fréquence planifiée de la tâche, cette valeur doit être au moins égale à l'intervalle entre deux exécutions et devrait idéalement prévoir un chevauchement. Par exemple, si la tâche est planifiée toutes les 90 minutes, réglez LookBackHours à 2 (heures). Valeur par défaut (si aucune valeur n'est définie) : 2
2. OrderSize : nombre maximal de commandes à récupérer par requête interne à Zonos. Il s'agit en quelque sorte de la taille de page qu'utilise la tâche pour interroger Zonos au sujet des commandes. Valeur par défaut (si aucune valeur n'est définie) : 20

Zonos Hello offre des fonctionnalités de localisation côté client, comme la sélection dynamique de la langue, les messages sur les droits et taxes et la conversion des devises directement sur la page. Une fois Zonos activé dans les préférences de site, Hello se charge automatiquement sur votre vitrine au moyen du script client Zonos.

Les scripts client Zonos sont ajoutés au moyen d'une inclusion distante (remote include) SFCC du point de terminaison Zonos-ClientScriptInclude, située au bas des modèles de superposition suivants :

• /cartridge/templates/default/common/layout/page.isml
• /cartridge/templates/default/common/layout/checkout.isml

Si votre projet remplace ces modèles dans des cartouches de priorité supérieure, assurez-vous d'ajouter l'inclusion distante à vos versions personnalisées :

<isinclude url="${URLUtils.url('Zonos-ClientScriptInclude', 'pageType', pdict.action)}"/>

En savoir plus sur Zonos Hello.

Zonos Hello convertit automatiquement les prix affichés sur la vitrine dans la devise locale de l'acheteur. Pour que cela fonctionne correctement :

1. Les prix doivent être encadrés par des éléments HTML dotés de noms de classe ou d'ID pouvant être sélectionnés avec jQuery. Par exemple : <p class="text-right sub-total zonos-price">${pdict.totals.subTotal}</p>
2. Ces sélecteurs doivent figurer dans la préférence de site Currency Element Selector (ou dans votre Zonos Dashboard).

Modifications du code d'affichage des prix

La cartouche Zonos comprend les modèles de superposition suivants pour les endroits où les prix s'affichent sur le site de l'architecture de référence. Ils utilisent les noms de classe zonos-list-price, zonos-sales-price et zonos-price, attribués aux éléments HTML qui contiennent ces différents prix :

• /cartridge/templates/default/cart/productCard/cartCouponDisplay.isml
• /cartridge/templates/default/cart/cartTotals.isml
• /cartridge/templates/default/checkout/billing/billingSummary.isml
• /cartridge/templates/default/checkout/cart/miniCart.isml
• /cartridge/templates/default/chackout/productCard/productCardProductTotalPrice.isml
• /cartridge/templates/default/product/components/pricing.isml
• /cartridge/templates/default/product/components/setPrice.isml

Si aucune cartouche contenant ces modèles n'est configurée au-dessus de int_zonos dans le chemin des cartouches, aucune modification de code n'est nécessaire pour que Zonos Hello convertisse les devises de ces prix sur votre site. Si vous avez des versions personnalisées de ces modèles dans une ou plusieurs cartouches placées au-dessus de int_zonos dans le chemin des cartouches, vous devrez ajouter un nom de classe unique aux éléments HTML qui encadrent vos prix (comme illustré ci-dessus) dans ces modèles personnalisés.

Configurer la chaîne de sélecteur des éléments de prix

La chaîne de sélecteur de devise est une chaîne de sélecteur de type jQuery qu'utilise le script Zonos pour repérer les éléments HTML contenant des prix qui doivent faire l'objet d'une conversion des devises. Cette valeur doit être une liste, séparée par des espaces, des noms de classe CSS et des ID attribués aux éléments HTML qui encadrent les prix de votre site décrits à l'étape précédente; les noms de classe sont précédés de . et les ID de # (sans les guillemets). Par exemple, si votre site utilise les modèles d'affichage des prix inclus dans la cartouche Zonos, la chaîne de sélecteur sera .zonos-list-price .zonos-sales-price .zonos-price (sans les guillemets).

La chaîne de sélecteur de devise peut être configurée dans votre Zonos Dashboard ou dans la préférence de site Currency Element Selector de vos préférences de site personnalisées Zonos dans Business Manager.

Remarque : si elle est configurée aux deux endroits, la valeur de Business Manager a préséance.

En savoir plus sur la conversion des devises de Zonos Hello.

La chaîne de sélecteur du bouton de paiement est une chaîne de sélecteur jQuery qu'utilise le script Zonos pour repérer les éléments HTML de votre site qui servent de boutons et qui, lorsqu'on clique dessus, amènent le client dans le parcours de paiement de votre site.

Lorsque les acheteurs cliquent sur un bouton de paiement correspondant à la chaîne de sélecteur configurée, Zonos intercepte automatiquement l'action et ouvre la fenêtre modale de paiement.

La chaîne de sélecteur du bouton de paiement peut être configurée dans votre Zonos Dashboard ou dans la préférence de site Place Order (Checkout) Button Selector de vos préférences de site personnalisées Zonos dans Business Manager.

Lorsque l'utilisateur finalise une commande dans le paiement hébergé par Zonos, il est redirigé vers un pipeline personnalisé qui affiche une confirmation de commande dans SFCC (Zonos-OrderConfirmation). Le principal modèle de rendu de cette confirmation de commande est /int_zonos/cartridge/templates/default/checkout/confirmation/zonosConfirmation.isml.

Cette page de confirmation de commande utilise le même style que la page de confirmation de commande native de SFCC/SFRA et partage certains fichiers .isml avec celle-ci. Il faudra peut-être en ajuster le style pour l'harmoniser avec les personnalisations de style déjà apportées au site. Les modèles de rendu de base utilisés par le modèle de confirmation de commande Zonos comprennent :

• app_storefront_base\cartridge\templates\default\checkout\confirmation\confirmationDetails.isml
• app_storefront_base\cartridge\templates\default\checkout\shipping\shippingSummary.isml
• int_zonos\cartridge\templates\default\checkout\billing\billingSummary.isml
• app_storefront_base\cartridge\templates\default\checkout\orderProductSummary.isml
• app_storefront_base\cartridge\templates\default\checkout\orderTotalSummary.isml

Au-delà de l'affichage d'une confirmation de commande à l'utilisateur, la fonction sous-jacente de ce pipeline personnalisé repose sur un nouveau type d'objet personnalisé inclus dans l'importation de données : zonosOrders. Lorsque la confirmation de commande s'affiche pour l'utilisateur, SFCC utilise l'ID de commande Zonos figurant dans l'URL de la confirmation et crée un objet personnalisé correspondant, dont l'attribut clé (Key Attribute) est l'ID de commande Zonos. Cet objet sert ensuite à créer la commande dans SFCC au moyen de la tâche CreateOrdersFromZonos. Cette tâche parcourt tous les objets personnalisés de type zonosOrders dont createdStatus = - None -. Elle effectue alors quelques opérations :

1. Interroger Zonos pour obtenir les détails de la commande.
2. Utiliser cette réponse pour créer la commande dans SFCC selon les paramètres configurés dans les préférences de site pour le mode d'expédition et le mode de paiement, ainsi que les détails des articles, de l'expédition, de la facturation et du client contenus dans la réponse.
3. Mettre à jour Zonos avec le numéro de commande SFCC au moyen d'une mutation, afin de l'associer au numéro de commande Zonos dans le Zonos Dashboard.

Si les étapes ci-dessus réussissent, l'attribut d'objet personnalisé createdStatus est réglé à created, ce qui exclut l'objet des traitements ultérieurs. Si elles échouent, l'attribut createdStatus est réglé à failed et un message d'erreur est consigné dans l'objet, dans l'attribut errorResponse (Zonos) ou sfccErrorResponse (SFCC), selon le système qui a renvoyé l'erreur pendant le processus.

Pour tenter de nouveau de créer la commande, il suffit de remettre createdStatus à - None -; elle sera alors prise en compte lors de la prochaine exécution de la tâche.

Facultatif — Les paramètres suivants sont des paramètres avancés. Des valeurs par défaut sont en place, aucune action n'est donc requise. Si vous souhaitez les ajuster, suivez ces directives :

Create invoice on import

Réglé à Yes par défaut. Zonos crée une facture lors de l'importation de la commande. Si vous désactivez cette fonctionnalité, vous devrez créer votre propre facture, et Zonos placera la commande en attente d'examen pour fraude, au statut zonos_hold. Une fois l'attente pour fraude levée, nous rétablirons le statut précédent.

Customer login

Réglé à No par défaut. Si vous voulez exiger un compte pour le paiement, passez à Yes. Vous devrez également aller dans Customer configuration > Login options et régler Redirect Customer to Account Dashboard after Logging In à No.

SFCC order export

Si vous utilisez ou prévoyez d'utiliser l'exportation des commandes SFCC (SFCC Order Export), assurez-vous que les attributs personnalisés Zonos attribués aux objets Order et Product sont inclus dans vos fichiers d'exportation des commandes SFCC. Dans Merchant Tools > Site Preferences > Orders, réglez la version du schéma d'exportation des commandes à la plus récente.

Maintenant que vous avez configuré votre compte et votre application, vous êtes prêt à tester votre intégration. Vous devrez activer Checkout et Hello dans SFCC pendant les tests. Pour ce faire :

1. Accédez à Merchant Tools > Site Preferences > Custom Preferences > zonos.
2. Réglez Zonos Enabled à Yes.

Une fois les renseignements de votre compte Zonos configurés dans les préférences de site personnalisées de votre site et le commutateur de fonctionnalité Zonos Enabled réglé à YES, vous pouvez tester les fonctionnalités Zonos sur votre vitrine en ajoutant le paramètre suivant à l'URL de votre site : zCountry=[code d'un pays que vous avez activé dans votre Zonos Dashboard]

Par exemple, si vous avez activé le Canada : https://abcd-001.dx.commercecloud.salesforce.com/on/demandware.store/Sites-RefArch-Site?zCountry=CA

Remarque : cette étape n'est nécessaire que pour les tests dans des environnements autres que de production, où votre Public API Token Zonos est configuré avec un jeton d'identifiant de test. Lorsqu'il est configuré avec votre jeton API réel (de production), le paramètre d'URL zCountry n'est ni nécessaire ni attendu.

Si vous n'êtes pas encore prêt à passer en production, n'oubliez pas de remettre Zonos Enabled à No une fois les tests terminés. Une fois les tests terminés, activez Zonos en suivant les mêmes étapes que ci-dessus.

Les renseignements sur les produits peuvent influer sur le montant des droits et taxes exigibles ainsi que sur les frais d'expédition. Plus vous fournissez de renseignements sur les produits à Zonos, plus la soumission obtenue sera précise. Zonos peut générer une soumission même lorsque ces renseignements ne sont pas disponibles, mais recommande de fournir les principaux détails suivants pour améliorer la précision :

• Poids : le poids influe sur vos frais d'expédition, qui peuvent à leur tour influer sur les droits ou les taxes. Les poids indiqués dans vos fiches produits SFCC sont automatiquement utilisés par Zonos lorsqu'ils sont présents.
• Dimensions : les dimensions peuvent influer sur vos frais d'expédition, qui peuvent à leur tour influer sur les droits ou les taxes. Zonos peut utiliser les dimensions (longueur, largeur et hauteur) définies pour chaque produit dans SFCC, mais vous devez les associer dans les préférences de site personnalisées Zonos pour assurer une intégration adéquate.
• Codes HS : les codes HS influent sur les taux de droits et peuvent parfois influer sur les taxes. Zonos peut utiliser les codes HS définis dans vos fiches produits SFCC, mais vous devez associer le champ du code HS dans les préférences de site personnalisées Zonos.
• Pays d'origine : le pays d'origine d'un produit influe sur les taux de droits et peut influer sur les taxes. Le pays d'origine défini dans vos fiches produits SFCC est automatiquement utilisé par Zonos lorsqu'il est présent.

Remarque : vous pouvez aussi saisir ces renseignements dans Catalog, ce qui remplace les renseignements stockés et transmis par SFCC.

En savoir plus sur les renseignements sur les produits selon la plateforme.