Intégration personnalisée

Pour commencer, veuillez contacter notre équipe de vente pour créer un compte et signer un accord. Une fois l'accord signé, vous recevrez deux micro-dépôts dans votre compte qui doivent être vérifiés.

Veuillez envoyer ces montants de micro-dépôts à accounting@zonos.com avec votre ID de magasin Dashboard (CC votre représentant commercial).

Une fois vérifié, vos coordonnées bancaires s'afficheront dans Dashboard -> Settings -> Billing.

Après avoir créé votre compte Zonos, vous devrez configurer les paramètres dans Dashboard pour garantir que Checkout fonctionne correctement avec votre magasin. Cette section couvre toutes les configurations essentielles de Dashboard.

Configurer les paiements

Connectez un compte bancaire pour recevoir des paiements en temps voulu de Checkout. Les paiements sont traités quotidiennement avec un délai de 2 jours à partir du paiement capturé. Pour ce faire, veuillez suivre ces étapes :

1. Naviguez vers Dashboard -> Settings -> Checkout settings .
2. Cliquez sur Ajouter un compte bancaire
3. Vous serez redirigé vers un portail Stripe pour compléter la configuration et fournir les informations suivantes :
   • Informations sur le compte bancaire.
   • EIN de l'entreprise.
   • Numéro de sécurité sociale d'un propriétaire d'entreprise à 25 %. Pour plus de détails sur pourquoi cela est requis, consultez la documentation de Stripe.

Remarque : Si vous devez mettre à jour votre calendrier de paiements, veuillez contacter support@zonos.com

Configurer les domaines autorisés

Le script JS de Zonos nécessite une liste de domaines autorisés pour des raisons de sécurité. Cela empêche les sites non autorisés de charger le script et garantit qu'il ne s'exécute que sur vos domaines approuvés. Sans cette configuration, le script renverra des erreurs de permission.

Pour configurer cela :

1. Naviguez vers Dashboard -> Settings -> Checkout settings
2. Sous URLs, ajoutez votre domaine complet et tous les sous-domaines où Checkout sera utilisé. Par exemple, si votre domaine est example.com, vous devez ajouter example.com et test.example.com.

Personnaliser les paramètres de marque

Configurez vos paramètres de marque dans Dashboard pour correspondre à l'apparence et à la convivialité de votre magasin.

Pour ce faire, veuillez suivre ces étapes :

1. Naviguez vers Dashboard -> Settings -> Checkout settings -> Branding
2. Configurez les paramètres suivants :
   • Logo.
   • Couleur de marque et d'accent.
   • Thème, style et police.

Pour plus d'informations sur les paramètres de marque, consultez notre documentation.

Connecter un transporteur

Pour estimer les frais d'expédition à checkout, vous devrez connecter un transporteur à votre compte Zonos. Cela vous permettra d'activer des niveaux de service d'expédition spécifiques à checkout.

Pour connecter un transporteur, veuillez suivre ces étapes :

1. Naviguez vers Dashboard -> Settings -> Shipping -> Rates
2. Cliquez sur Ajouter un transporteur
3. Suivez les instructions de configuration du transporteur.

Pour plus de détails sur la connexion des comptes de transporteur, consultez notre documentation.

Configurer les zones d'expédition

Les zones d'expédition vous permettent de configurer quels transporteurs et niveaux de service sont disponibles pour différentes régions du monde.

Pour configurer les zones d'expédition, veuillez suivre ces étapes :

1. Naviguez vers Dashboard -> Settings -> Shipping -> Locations
2. Cliquez sur Nouvelle zone
3. Entrez un nom de zone et sélectionnez les pays vers lesquels vous souhaitez expédier.
4. Sélectionnez le transporteur et le niveau de service que vous souhaitez offrir.

Pour plus de détails sur les zones d'expédition, consultez notre documentation.

Configurer un pays d'origine de secours et un code HS

Le pays d'origine et le code HS sont utilisés pour calculer les droits et taxes exacts.

Si vous ne fournissez pas de pays d'origine spécifique ou de code HS, nous utiliserons les secours configurés dans Dashboard.

Pour définir votre pays d'origine de secours et votre code HS :

1. Naviguez vers Dashboard -> Settings -> Shipping -> Catalog.
2. Pour le pays d'origine, sélectionnez le pays où la majorité de vos produits sont fabriqués.
3. Pour le code HS, entrez le code HS de votre produit le plus courant. Si vous n'avez pas de code HS, naviguez vers Classify dans Dashboard et entrez le nom et la description de votre produit pour générer un code HS précis.

Le snippet JS de Zonos est une intégration JavaScript côté client qui permet la fonctionnalité globale de checkout sur votre site. Il sert de pont entre votre plateforme de commerce électronique et les services de Zonos, gérant :

• Checkout Experience : Rendu de l'interface utilisateur de checkout et traitement des paiements.
• Services de localisation : Détecte la localisation des visiteurs et gère la conversion de devises.
• Intégration du panier : Se connecte à votre panier et système de commande existants.
• Sécurité : Valide les domaines et authentifie les requêtes API.

Le snippet est chargé de manière asynchrone pour éviter tout impact sur les performances de votre site. Il s'initialise avec les identifiants API de votre magasin et gère toutes les interactions côté client de manière sécurisée. L'implémentation est conçue pour être non intrusive, nécessitant des modifications minimales de votre flux checkout existant.

Voici un exemple complet qui inclut le chargement du script, l'initialisation et la gestion des événements à référencer lors de l'intégration de Checkout.

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

      script.addEventListener('load', () => {
        window.Zonos.init({
          checkoutSettings: {
            createCartId: async () => {
              // Replace with your server-side cart creation logic
              return {
                cartId: 'cart_73e707c0-c161-4c37-9581-4da1b1115777',
              };
            },
            placeOrderButtonSelector: '#placeOrder, .place-order', // Replace with your actual selector(s)
          },
          helloSettings: {
            currencyElementSelector: '.price',
            onInitSuccess: () => {
              Zonos.openHelloDialog();
            },
          },
          storeId: 7744, // Replace with your actual store ID
          zonosApiKey: 'credential_live_7a128f4e-f192-4232-8992-94dd09eb4437', // Replace with your actual API key
        });
      });

      document.head.appendChild(script);
    }
  })();
</script>

Remarque : Remplacez les valeurs de remplacement (storeId, zonosApiKey, selectors, etc.) par vos valeurs réelles de votre Zonos Tableau de bord.

Gestion du cache du navigateur

Nous recommandons d'ajouter un horodatage ou un autre identifiant unique à l'URL pour garantir que le script n'est pas mis en cache par le navigateur. Cela garantira que la dernière version du script est toujours chargée. Cela est montré à la ligne 10 de l'exemple complet.

      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

Authentifiez le Zonos extrait JS

Une fois que vous avez chargé le script JS de Zonos, vous devez l'authentifier en passant une clé API publique Zonos et un ID de magasin dans la fonction Zonos.init. La clé API publique utilisée pour authentifier Checkout est conçue pour être publiable, ce qui signifie qu'elle peut être utilisée en toute sécurité dans le code frontend sans exposer d'informations sensibles.

Pour trouver votre ID de magasin et votre clé API, naviguez vers Dashboard -> Settings -> Integrations. Assurez-vous de ne pas utiliser une Secret API key, car elle n'est pas conçue pour être utilisée dans le code frontend. Cela est montré dans les lignes 29 et 30 de l'exemple complet.

Zonos.init({
  // ... other fields
  zonosApiKey: 'Your API KEY', // Replace with your actual API key (found in Dashboard)
  storeId: 'Your STORE ID', // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

Hello est requis lors de l'utilisation de Checkout.

Hello est responsable de la détection de l'emplacement, de la langue et de la devise du visiteur, et d'afficher les informations appropriées. Vous pouvez configurer tous les paramètres de Hello dans le Dashboard ou dans le script JS de Zonos. Si vous avez déjà configuré Hello dans le Dashboard, le script chargera ces paramètres et les utilisera. Si vous spécifiez des valeurs dans la propriété helloSettings de la fonction Zonos.init, le script utilisera ces valeurs à la place comme indiqué ci-dessous.

Configurer la conversion de devise dans Hello dans le script JS

Hello utilise des sélecteurs CSS pour identifier les éléments de votre site qui affichent des informations sur la devise. Passez ces sélecteurs à la propriété helloSettings.currencyElementSelector de la fonction Zonos.init afin que Hello puisse détecter et afficher la bonne devise de l'acheteur international.

Vous pouvez utiliser n'importe quel sélecteur CSS valide ici, par exemple #price, .price pour sélectionner plusieurs éléments différents. Cela est montré dans les lignes 23 et 24 de l'exemple complet.

Zonos.init({
  // ... other fields
  helloSettings: {
    currencyElementSelector: '.price', // Replace with your actual selector
  },
  // ... other fields
});

Ouvrir automatiquement Hello au chargement de la page

Par défaut, Hello ne s'ouvrira que lorsque le visiteur cliquera sur le bouton de drapeau. Si vous souhaitez ouvrir automatiquement Hello lorsque la page se charge, vous pouvez appeler la fonction Zonos.openHelloDialog() une fois que le script Zonos a été chargé. Cela est montré dans les lignes 25 et 26 de l'exemple complet.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Checkout est responsable de permettre au client d'entrer ses informations d'expédition et de facturation, de calculer landed cost, de collect le paiement et de finaliser la commande.

Checkout partagera des données contextuelles avec Hello, telles que la localisation, la langue et la devise du visiteur. Cela garantit que l'expérience du client est cohérente tout au long du processus d'achat.

Vous pouvez configurer tous les paramètres de Checkout à la fois dans le Dashboard et dans le script JS de Zonos. Si vous avez déjà configuré Checkout dans le Dashboard, le script chargera ces paramètres et les utilisera. Si vous spécifiez des valeurs dans la propriété checkoutSettings de la fonction Zonos.init, le script utilisera ces valeurs à la place.

Configurer le bouton 'passer la commande' dans le script JS

Le script JS de Zonos reconnaîtra automatiquement les acheteurs internationaux et les dirigera vers le flux de Checkout. Cependant, vous devrez configurer le bouton 'passer la commande' sur votre plateforme pour ouvrir Checkout lorsqu'il est cliqué. Cela peut être fait en passant un sélecteur CSS à la propriété checkoutSettings.placeOrderButtonSelector de la fonction Zonos.init.

Si vous avez plusieurs boutons qui peuvent être utilisés pour passer une commande, assurez-vous de passer un sélecteur pour chaque bouton. Par exemple, #placeOrder, .place-order.

Cela est montré à la ligne 21 de l'exemple complet.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

Créer en toute sécurité les détails du panier côté serveur

Pour afficher les détails du panier au client, vous devez créer une fonction côté serveur qui appellera l'API Zonos pour créer un panier, puis renverra cet ID de panier à votre frontend. Cela garantira que les détails du panier ne sont pas exposés au client d'une manière qui peut être manipulée.

Votre appel API backend utilisera un jeton d'identification GraphQL secret, qui est différent du jeton public que vous utilisez pour authentifier le script JS Zonos. Ce jeton peut être récupéré dans Dashboard -> Settings -> Integrations. Le jeton secret doit être passé en tant qu'en-tête dans votre appel API.

La mutation cartCreate accepte une liste d'articles, qui doit être formatée selon le schéma d'article de panier.

// Create new cart from serverside
async function createCart() {
  /**
   * Full cart mutation schema: https://zonos.com/developer/mutations/cartCreate
   * */
  const graphql = JSON.stringify({
    query: `
mutation cartCreate($input: CartCreateInput!){
  cartCreate(input: $input) {
    id
    adjustments {
      amount
      currencyCode
      description
      productId
      sku
      type
    }
    items {
      id
      name
      amount
      currencyCode
      quantity
      sku
      description
      metadata {
        key
        value
      }
    }
    metadata {
      key
      value
    }
  }
}`,
    variables: {
      /**
       * input for the cartCreate is this schema https://zonos.com/developer/types/CartCreateInput
       */
      input: {
        /**
         * Cart adjustment input: https://zonos.com/developer/types/CartAdjustmentInput
         */
        adjustments: [
          {
            amount: -10,
            currencyCode: 'USD',
            /**
             * Enum value: https://zonos.com/developer/types/CartAdjustmentType
             */
            type: 'CART_TOTAL',
          },
        ],
        /**
         * Cart item input: https://zonos.com/developer/types/ItemInput
         */
        items: [
          {
            name: 'Item 1',
            amount: 150.99,
            currencyCode: 'USD',
            description: 'Item 1 description',
            quantity: 2,
          },
        ],
        /**
         * Cart metadata input: https://zonos.com/developer/types/CartMetadataInput
         */
        metadata: [
          {
            key: 'key1',
            value: 'value1',
          },
        ],
      },
    },
  });

  const response = await fetch('https://api.zonos.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      credentialToken: 'credential_live_xxxxxxxxx', // Replace with your actual SECRET credential token (found in Dashboard)
    },
    body: graphql,
  });

  const { data } = await response.json();
  return data.cartCreate.id; // Return the cart ID to your frontend
}

Nous vous suggérons de créer un point de terminaison API sur votre serveur et ensuite d'appeler ce point de terminaison depuis votre intégration JS côté frontend, ce qui est détaillé à l'étape suivante.

Passer l'ID du panier à Checkout via le frontend

Une fois que vous avez créé un panier sur votre serveur, vous devez passer l'ID du panier au script JS de Zonos. Cela peut être fait en utilisant le rappel createCartId qui fait partie de la fonction Zonos.init. Checkout récupérera ensuite en toute sécurité les détails du panier depuis Zonos lorsqu'il sera ouvert, empêchant toute falsification du panier. Voir l'exemple de code ci-dessous.

La valeur de createCartId ne peut pas être une valeur statique, elle doit être une fonction.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // Replace with your actual selector(s)
    createCartId: async () => {
      const response = await fetch('https://api.merchant.com/api/get-cart', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      });
      const json = await response.json();

      return json.id; // Only need to return the cart ID
    },
  },
});

Pour synchroniser les commandes entre votre système et le Zonos Dashboard, implémentez ces appels API et webhooks :

Mutations requises

Webhooks requis

Avant de mettre en ligne votre intégration Checkout, il est important de tester minutieusement tous les aspects de l'intégration pour garantir une expérience client fluide. Cela inclut le test du flux checkout, le traitement des paiements, la création de commandes et la fonctionnalité des webhooks.

Suivez notre guide de test pour vérifier que votre intégration fonctionne correctement et pour identifier et corriger tout problème avant le lancement en production.

Voici quelques questions fréquentes concernant le processus d'intégration.

Comment Zonos gère-t-il la confirmation de commande ?

Zonos fournit une page de remerciement intégrée que vous pouvez utiliser pour les confirmations de commande. Cette page sera toujours affichée, même si une commande échoue à s'importer dans votre système, garantissant que les clients reçoivent toujours une confirmation de leur achat.

Puis-je être notifié lorsqu'une commande est créée ?

Oui. Si vous souhaitez recevoir des notifications lorsqu'une commande est créée, dans le Dashboard sous la section Email des paramètres de Checkout, vous pouvez entrer l'adresse e-mail des membres de l'équipe qui doivent être notifiés lorsqu'une commande est créée, expédiée ou annulée.