Checkout pour Miva

Dans les 24 heures suivant votre inscription, un représentant attitré à votre accueil communiquera avec vous pour lancer un processus d'intégration sur mesure.

Important : Les étapes ci-dessous sont fournies à titre de référence; votre représentant à l'accueil vous guidera tout au long de celles-ci.

1. Téléchargez le module depuis le Miva App Store, ou demandez le fichier zonos.mvc directement à Zonos.
2. Dans l'administration de Miva, allez dans Domain Settings -> Modules -> Add Module, téléversez le fichier zonos.mvc, puis cliquez sur Add.

3. Allez dans Settings -> Modules, repérez Zonos, puis cliquez sur Install. Vérifiez que le module s'affiche comme Installed.

Dans Miva, allez dans Users -> API Tokens et cliquez sur Add API Token. Configurez-le comme suit :

• Name : Zonos Checkout
• Allowed IP Addresses : 0.0.0.0/0, ::/0
• Signature : Require Signature with Key -- cliquez sur Generate pour créer une clé de signature
• Timestamp : Require Timestamp Within 30 seconds

À l'écran suivant, activez Customer Service & Sales pour permettre au jeton de créer et de modifier des commandes. Cliquez sur Save.

Accédez au module Checkout dans Miva en allant dans Miva -> Utility Settings -> Zonos, puis remplissez les champs suivants :

1. Store ID : Copiez votre numéro de compte Zonos depuis Dashboard -> Settings -> Account -> Integrations.
2. Zonos API Key : Votre clé d'API secrète (ne la communiquez jamais).
3. Zonos Public Key : Votre clé publique.
4. Store Currency : La devise de base de votre boutique (p. ex., USD).
5. Environment : Sélectionnez Live pour la production ou Test pour les essais.
6. Checkout Button Selector : Le sélecteur CSS de votre bouton de paiement (exemple : a[href*="checkout.html"]).
7. Hidden Selectors : Permet de masquer les options de paiement nationales et d'autres éléments qui ne concernent pas forcément la clientèle internationale.
8. Import Orders : Cochez cette case pour importer automatiquement les commandes Zonos finalisées dans l'administration de Miva. Les webhooks doivent pour cela être enregistrés à l'étape suivante.

Cliquez sur Update en haut à droite pour enregistrer avant de continuer.

Dans le module 10.x, les commandes sont importées au moyen d'un webhook. Les versions précédentes du module utilisaient plutôt une URL ou un point de terminaison de confirmation de commande.

Après avoir enregistré vos paramètres, cliquez sur Register Webhooks. Cette action relie votre boutique à Zonos afin que les commandes finalisées soient importées automatiquement, que les annulations soient synchronisées et que les mises à jour d'expédition soient transmises à Miva.

Les webhooks doivent être enregistrés pour que l'importation des commandes, la synchronisation des annulations et les mises à jour d'expédition fonctionnent. La case Import Orders exige que les webhooks soient enregistrés.

Faites défiler la page vers le bas pour remplir les champs restants :

1. Miva API Token : L'Access Token du jeton d'API que vous avez créé à l'étape Créer un jeton d'API.
2. Miva API Signature : La Signing Key de ce même jeton d'API.
3. Image Type : Détermine la taille d'image de produit affichée dans le Checkout Zonos (Main convient à la plupart des boutiques).
4. Additional Field Mappings : Associez au besoin des champs personnalisés de Miva à des attributs ou métadonnées de Zonos (couleur, matière, taille, etc.). Nous recommandons d'associer le code HS si vous avez défini des codes HS propres à chaque produit dans vos fiches produits Miva. Ce n'est pas obligatoire pour obtenir une soumission de droits et taxes, puisque nous pouvons utiliser les codes HS propres aux produits que vous avez saisis dans Catalog ou votre code HS par défaut. C'est toutefois recommandé : des produits correctement classés améliorent grandement la précision des calculs de landed cost. Pour associer un champ dans Miva, créez un champ personnalisé pour le code HS, puis associez-le sous Utility Settings -> Zonos.

Cliquez sur Update pour enregistrer tous les paramètres.

Maintenant que votre compte et votre module sont configurés, vous pouvez effectuer les tests suivants :

• Tester les soumissions d'expédition
• Passer une commande d'essai sur votre site
• Tester le parcours des commandes dans vos systèmes
• Tester votre site Web

Découvrez comment effectuer ces tests. Pendant les tests, vous devrez régler le champ Environment du module sur Test.

Une fois les tests terminés, vous êtes prêt pour la mise en ligne! Réglez Environment sur Live, vérifiez que vos identifiants Zonos sont exacts et assurez-vous que les webhooks sont enregistrés sur votre boutique en production.

1. Allez dans dashboard.zonos.com -> Hello -> Hello Settings.
2. Activez Currency behavior.
3. Saisissez le sélecteur CSS qui cible les éléments de prix de vos produits (p. ex., .price).

Une fois cette option activée, Zonos Hello convertit et affiche automatiquement les prix dans la devise locale de l'acheteur.

Les dimensions d'expédition, le pays d'origine et le code HS définis dans le catalogue Miva sont transmis automatiquement à Zonos et, lorsqu'ils sont renseignés, servent aux soumissions de landed cost et d'expédition. Aucune association supplémentaire n'est requise.

Si votre boutique vend des produits configurables dont toutes les variantes partagent un même SKU, les Product Shipping Rules standard de Miva n'enregistrent qu'un seul ensemble de dimensions par produit; chaque configuration est donc traitée comme ayant la même taille, peu importe ce que le client a choisi.

Miva et Zonos prennent en charge les dimensions au niveau des variantes, mais il faut alors configurer chaque variante individuellement. Cela peut être peu pratique pour les boutiques qui comptent des centaines, voire des milliers de configurations ne correspondant pas à des variantes distinctes.

Cette fonctionnalité règle ce problème en lisant les dimensions de chaque configuration directement dans le panier au moment du paiement, à l'aide de la logique personnalisée que votre boutique utilise déjà pour les calculer -- par exemple, en extrayant les dimensions de la description du produit.

Exigences

• Votre boutique doit déjà remplir des colonnes de dimensions personnalisées sur les articles du panier lorsqu'ils sont ajoutés au panier (ce qui est géré du côté de Miva, hors de la portée du module Zonos).
• Vous devrez connaître le nom exact des colonnes que vous utilisez.

Configuration

Saisissez ces noms de colonnes dans les trois champs correspondants de l'administration du module Zonos. Laissez-les vides pour revenir aux Product Shipping Rules standard -- cette fonctionnalité est entièrement facultative et n'a aucune incidence sur les boutiques qui ne l'utilisent pas.

Lorsqu'une étiquette d'expédition est créée ou qu'un numéro de suivi est saisi dans le Zonos Dashboard, le numéro de suivi et le statut de l'envoi sont automatiquement transmis à la commande correspondante dans l'administration de Miva. Les webhooks doivent pour cela être enregistrés (voir l'étape Enregistrer les webhooks ci-dessus).

Le suivi peut aussi être saisi directement dans Miva. Utilisez la boîte de dialogue Enter Tracking Number de n'importe quelle commande Zonos -- le numéro de suivi et le statut de l'envoi seront automatiquement synchronisés avec le Zonos Dashboard.

Le journal de débogage est accessible dans l'administration de Miva, sous les paramètres du module Zonos. Il consigne le cycle de vie complet de chaque événement de commande traité par le module -- importations, synchronisations du suivi, annulations et demandes d'annulation envoyées à Zonos -- en y intégrant directement les réussites comme les échecs.

Chaque entrée comprend le numéro de commande Zonos, le numéro de commande Miva et, s'il y a lieu, des détails propres au client, comme la réponse d'erreur de l'API de Miva ou de Zonos. C'est donc la source d'information la plus complète pour diagnostiquer les problèmes.

Le journal ne conserve que les 500 lignes les plus récentes. Les entrées plus anciennes ne sont pas archivées; consultez-le donc rapidement après un problème -- des événements antérieurs pourraient déjà avoir été écrasés.

Journal d'erreurs public (aucune connexion requise) 

Un second journal, public, est accessible au moyen d'une URL directe -- aucune connexion à l'administration de Miva n'est requise. Il ne consigne que les erreurs (aucune réussite) et ne contient ni renseignements personnels des clients ni données sensibles. Chaque entrée est précédée de la version du module (p. ex., [v10.09]) pour faciliter l'identification.

Format de l'URL :

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Exemple :

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Store Code : Le miva_store_code est renvoyé dans le tableau metadata de la réponse de l'API pour toutes les commandes du Dashboard.

Tous les remboursements doivent être traités directement dans le Zonos Dashboard. Les boutons Refund, Capture et Void de Miva sont volontairement indisponibles pour les commandes importées de Zonos. Les remboursements traités dans Zonos ne mettent pas automatiquement à jour les montants de paiement de la commande Miva correspondante -- la commande Miva conserve les montants capturés à l'origine et n'est pas synchronisée avec les remboursements effectués dans Zonos.

Pour les annulations de commande, le comportement dépend du statut actuel de la commande :

• Open (pas encore expédiée) : L'annulation dans Miva annule aussi la commande dans Zonos et annule l'autorisation de paiement. Comme Zonos ne capture le paiement qu'à l'expédition de la commande, le client n'est jamais réellement débité et aucun remboursement distinct n'est nécessaire.
• Shipped or Completed : L'annulation dans Miva marque la commande Miva comme annulée, mais Zonos refuse l'annulation, car la commande a déjà été exécutée et n'est plus admissible à l'annulation automatique. Dans ce cas, une note réservée à l'administration est ajoutée à la commande Miva -- visible seulement par le personnel de la boutique et jamais par le client -- pour indiquer que la commande doit être traitée dans Zonos. Une notification par courriel est également envoyée à l'adresse courriel principale du compte de la boutique pour avertir le marchand d'intervenir dans le Zonos Dashboard, où il peut traiter manuellement tout remboursement applicable.

Symptôme : Les commandes sont finalisées dans Zonos Checkout et apparaissent dans le Zonos Dashboard, mais rien ne s'affiche dans l'administration de Miva.

Cause : Zonos envoie un webhook ORDER_CREATED (HTTP POST) au point de terminaison /mm5/json.mvc de votre boutique. Sur les sites de développement, la sécurité au niveau du serveur bloque souvent cette requête avant qu'elle n'atteigne Miva. Causes fréquentes :

• HTTP Basic Auth -- Si le site de développement demande un mot de passe (Plesk, cPanel, .htaccess, etc.), le webhook est refusé avec une erreur 401 Unauthorized. Ajoutez les adresses IP de Zonos à la liste d'autorisation de votre configuration .htaccess ou Plesk afin qu'elles contournent la demande d'authentification.
• Cloudflare WAF / IP Access Rules -- Si le site passe par le mandataire de Cloudflare, ses règles de sécurité peuvent bloquer la requête POST avant qu'elle n'atteigne votre serveur. Ajoutez une règle WAF qui autorise les requêtes POST dont le chemin d'URL contient /mm5/json.mvc, ou ajoutez directement les adresses IP de Zonos à la liste d'autorisation dans les IP Access Rules de Cloudflare.
• Liste d'autorisation d'adresses IP au niveau du serveur -- Si le site de développement n'accepte que le trafic de certaines adresses IP (ce qui est courant pour les environnements de préproduction limités aux adresses IP du bureau ou de la plateforme), les requêtes webhook de Zonos sont rejetées silencieusement, sans réponse. Ajoutez toutes les adresses IP d'envoi des webhooks Zonos à la liste d'autorisation de votre serveur (Plesk IP Access Restriction Manager, cPanel IP Blocker, ou les règles de sécurité de votre pare-feu ou de votre panneau d'hébergement).

Adresses IP d'envoi des webhooks Zonos

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

Ce problème ne touche généralement que les sites de développement ou de préproduction -- les sites Miva en production sont habituellement publics et n'exigent pas d'autoriser des adresses IP. En cas de doute sur la configuration, communiquez avec votre hébergeur ou avec le soutien de Miva.

Les informations sur les produits peuvent influer sur le montant des droits et taxes exigibles ainsi que sur les frais d'expédition. Plus vous fournissez d'informations sur vos produits à Zonos, plus la soumission obtenue sera précise. Zonos peut produire une soumission même en l'absence de ces informations, mais recommande de fournir les détails clés suivants pour améliorer la précision :

• Poids : Le poids influe sur vos frais d'expédition, ce qui peut avoir une incidence sur les droits ou les taxes. Lorsqu'ils sont présents, les poids de vos fiches produits Miva sont utilisés automatiquement par Zonos.
• Dimensions : Les dimensions peuvent influer sur vos frais d'expédition, ce qui peut avoir une incidence sur les droits ou les taxes. Zonos peut utiliser les dimensions (longueur, largeur et hauteur) définies pour chaque produit dans Miva, mais vous devez les associer dans l'application Zonos pour une intégration adéquate.
• Codes HS : Les codes HS influent sur les taux de droits et peuvent parfois avoir une incidence sur les taxes. Zonos peut utiliser les codes HS définis dans vos fiches produits Miva, mais vous devez associer le champ du code HS dans l'application Zonos.
• Pays d'origine : Le pays d'origine d'un produit influe sur les taux de droits et peut avoir une incidence sur les taxes. Miva ne peut pas transmettre le pays d'origine de vos produits à Zonos; il faut donc l'ajouter au moyen de Zonos Catalog.

Détails sur les produits transmis à Zonos par Miva 

Remarque : Vous pouvez aussi saisir n'importe laquelle de ces informations dans Catalog, ce qui remplace les informations enregistrées dans Miva et transmises par celui-ci.

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