Checkout pour Miva

Dans les 24 heures suivant votre inscription, un représentant d'onboarding dédié vous contactera pour lancer un processus d'intégration sur mesure.

Important : Les étapes listées ci-dessous sont fournies à titre de référence et vous serez guidé à travers elles par votre représentant d'onboarding.

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

3. Allez dans Settings -> Modules, recherchez Zonos, puis cliquez sur Install. Confirmez qu'il 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

Sur l'écran suivant, activez Customer Service & Sales pour permettre au jeton de créer et 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é API secrète (ne la partagez jamais).
3. Zonos Public Key : Votre clé publique.
4. Store Currency : La devise de base de votre boutique (par exemple, USD).
5. Environment : Sélectionnez Live pour la production ou Test pour les tests.
6. Checkout Button Selector : Sélecteur CSS pour votre bouton de commande (exemple : a[href*="checkout.html"]).
7. Hidden Selectors : Pour masquer les options de paiement domestiques et autres détails qui pourraient ne pas concerner les clients internationaux.
8. Import Orders : Cochez pour importer automatiquement les commandes Zonos terminées dans l'administration Miva. Cela nécessite que les webhooks soient enregistrés à l'étape suivante.

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

Les commandes sont importées via webhook dans le module 10.x. Les versions précédentes du module utilisaient à la place une URL/un endpoint de succès de commande.

Après avoir enregistré vos paramètres, cliquez sur Register Webhooks. Cela connecte votre boutique à Zonos afin que les commandes terminées soient automatiquement importées, que les annulations soient synchronisées et que les mises à jour d'expédition soient renvoyées vers Miva.

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

Faites défiler vers le bas pour compléter les champs restants :

1. Miva API Token : L'Access Token du jeton API que vous avez créé à l'étape Create an API token.
2. Miva API Signature : La Signing Key de la même entrée de jeton API.
3. Image Type : Sélectionne la taille d'image produit affichée dans le checkout Zonos (Main convient à la plupart des boutiques).
4. Additional Field Mappings : Mappez éventuellement les champs personnalisés Miva vers les attributs/métadonnées Zonos (couleur, matière, taille, etc.). Nous recommandons de mapper le code HS si vous avez défini des codes HS spécifiques au produit dans vos fiches produit Miva. Ce n'est pas requis pour produire un devis de droits et taxes puisque nous pouvons utiliser les codes HS spécifiques au produit que vous avez saisis dans Catalog ou utiliser votre code HS par défaut. Cependant, c'est recommandé ; la précision des calculs de landed cost augmentera considérablement avec des produits correctement classifiés. Pour mapper un champ dans Miva, créez un champ personnalisé pour le code HS, puis mappez-le sous Utility Settings -> Zonos.

Cliquez sur Update pour enregistrer tous les paramètres.

Maintenant que vous avez configuré votre compte et votre module, vous êtes prêt à tester en effectuant ce qui suit :

• Tester les devis d'expédition
• Passer une commande test sur votre site
• Tester le flux de commande dans vos systèmes
• Tester votre site web

Apprenez à exécuter ces tests. Vous devrez définir le champ Environment du module sur Test pendant les tests.

Après avoir terminé les tests, vous êtes maintenant prêt à passer en production ! Définissez Environment sur Live, confirmez que vos identifiants Zonos sont corrects, et assurez-vous que les webhooks sont enregistrés sur votre boutique en production.

1. Allez sur 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 (par exemple, .price).

Zonos Hello convertira et affichera automatiquement les prix dans la devise locale de l'acheteur lorsque cette option est activée.

Les dimensions d'expédition, le pays d'origine et le code HS définis dans le catalogue Miva sont automatiquement transmis à Zonos et utilisés pour les devis de landed cost / d'expédition lorsqu'ils sont renseignés. Aucun mappage supplémentaire n'est requis pour la configuration.

Si votre boutique vend des produits configurables dont toutes les variantes partagent un même SKU, les Product Shipping Rules standard de Miva stockent un seul jeu de dimensions par produit, si bien que chaque configuration est traitée comme ayant la même taille, quel que soit le choix du client.

Miva et Zonos prennent en charge les dimensions au niveau de la variante, mais cela nécessite de configurer chaque variante individuellement. Cela peut s'avérer peu pratique pour les boutiques comptant des centaines, voire des milliers de configurations qui ne correspondent pas à des variantes distinctes.

Cette fonctionnalité résout ce problème en lisant les dimensions par configuration directement depuis le panier lors du paiement, en utilisant la logique personnalisée déjà en place dans votre boutique pour les calculer -- par exemple, en extrayant les dimensions de la description du produit.

Prérequis

• Votre boutique doit déjà renseigner des colonnes de dimensions personnalisées sur les articles du panier lors de leur ajout au panier (géré côté Miva, en dehors du périmètre du module Zonos).
• Vous devrez connaître les noms exacts 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'affecte pas 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 d'expédition sont automatiquement transmis à la commande correspondante dans l'administration Miva. Cela nécessite que les webhooks soient enregistrés (voir l'étape Register webhooks ci-dessus).

Le suivi peut également être saisi directement dans Miva. Utilisez la boîte de dialogue Enter Tracking Number sur n'importe quelle commande Zonos -- le numéro de suivi et le statut d'expédition se synchroniseront automatiquement avec le Zonos Dashboard.

Le journal de débogage est accessible dans l'administration Miva, sous les paramètres du module Zonos. Il enregistre l'intégralité du cycle de vie de chaque événement de commande traité par le module -- importations, synchronisations de suivi, annulations et demandes d'annulation sortantes vers Zonos -- y compris les succès et les échecs, directement dans le journal.

Chaque entrée inclut l'ID de commande Zonos, l'ID de commande Miva et, le cas échéant, des détails au niveau du client, comme la réponse d'erreur de l'API Miva ou Zonos. Cela en fait la source d'information la plus complète pour diagnostiquer les problèmes.

Le journal ne conserve que les 500 dernières lignes. Les entrées plus anciennes ne sont pas archivées ; vérifiez-le donc rapidement après un incident -- les événements antérieurs pourraient déjà avoir été écrasés.

Journal d'erreurs public (sans connexion requise) 

Un second journal, public, est disponible via une URL directe -- aucune connexion à l'administration Miva n'est requise. Il n'enregistre que les erreurs (aucun succès) et ne contient aucune donnée personnelle identifiable (PII) du client ni aucune donnée sensible. Chaque entrée est préfixée par la version du module (par exemple, [v10.09]) pour une identification rapide.

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 API pour toutes les commandes du dashboard.

Tous les remboursements de paiement doivent être traités directement via le Zonos dashboard. Les boutons Refund, Capture et Void dans Miva ne sont volontairement pas disponibles pour les commandes importées depuis Zonos. Tout remboursement effectué dans Zonos ne mettra pas automatiquement à jour les montants de paiement sur la commande Miva correspondante -- la commande Miva conserve les montants initialement capturés et n'est pas synchronisée avec l'activité de remboursement dans Zonos.

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

• Open (pas encore expédiée) : L'annuler dans Miva l'annulera également dans Zonos et annulera 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 séparé n'est nécessaire.
• Shipped or Completed : L'annuler dans Miva marquera la commande Miva comme annulée, mais Zonos rejettera l'annulation car la commande a déjà été traitée et n'est plus éligible à l'annulation automatique. Dans ce cas, une note réservée à l'administration est ajoutée à la commande Miva -- visible uniquement par le personnel de la boutique et jamais par le client -- expliquant que la commande doit être traitée dans Zonos. Une notification par e-mail est également envoyée à l'adresse e-mail principale du compte de la boutique, alertant le marchand qu'une action est nécessaire 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 n'apparaît dans l'administration Miva.

Cause : Zonos envoie un webhook ORDER_CREATED (HTTP POST) à l'endpoint /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. Les causes courantes sont :

• HTTP Basic Auth -- Si le site de développement affiche une invite de mot de passe (Plesk, cPanel, .htaccess, etc.), le webhook est rejeté avec une erreur 401 Unauthorized. Ajoutez les IP de Zonos à la liste blanche dans votre configuration .htaccess ou Plesk afin qu'elles contournent l'invite d'authentification.
• Cloudflare WAF / IP Access Rules -- Si le site est proxifié via 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 pour autoriser les requêtes POST dont le chemin d'URL contient /mm5/json.mvc, ou ajoutez directement les IP de Zonos à la liste blanche dans les IP Access Rules de Cloudflare.
• Server-level IP allowlist -- Si le site de développement restreint le trafic à des IP spécifiques uniquement (courant sur les environnements de staging verrouillés aux IP du bureau ou de la plateforme), les requêtes webhook de Zonos sont silencieusement rejetées, sans réponse. Ajoutez toutes les IP de livraison des webhooks Zonos à la liste blanche de votre serveur (Plesk IP Access Restriction Manager, cPanel IP Blocker, ou les règles de sécurité de votre pare-feu/panneau d'hébergement).

IP de livraison 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

Cela n'affecte généralement que les sites de développement/staging -- les sites Miva en production sont généralement publics et n'ont pas besoin de mise en liste blanche des IP. En cas de doute sur la configuration, contactez votre hébergeur ou le support Miva.

Les informations produit peuvent avoir un impact sur le montant des droits et taxes dus et sur le coût d'expédition. Plus vous fournissez d'informations produit à Zonos, plus le devis renvoyé sera précis. Zonos peut générer un devis même lorsque ces informations ne sont pas disponibles, mais recommande de fournir les détails produit clés suivants pour améliorer la précision :

• Poids : Le poids impacte votre coût d'expédition, ce qui peut affecter les droits ou taxes. Les poids dans vos fiches produit Miva sont automatiquement utilisés par Zonos lorsqu'ils sont présents.
• Dimensions : Les dimensions peuvent impacter votre coût d'expédition, ce qui peut affecter les droits ou taxes. Zonos peut utiliser les dimensions produit (longueur, largeur et hauteur) définies sur chaque produit dans Miva, mais vous devez les mapper dans l'application Zonos pour une intégration correcte.
• Codes HS : Les codes HS impactent les taux de droits et peuvent parfois affecter les taxes. Zonos peut utiliser les codes HS définis dans vos fiches produit Miva, mais vous devez mapper le champ code HS dans l'application Zonos.
• Pays d'origine : Le pays d'origine d'un produit impacte les taux de droits et peut affecter les taxes. Miva ne peut pas envoyer le pays d'origine de vos produits à Zonos, ils doivent donc être ajoutés via Zonos Catalog.

Détails produit transmis à Zonos par Miva 

Note : Vous pouvez également saisir l'une des informations ci-dessus dans Catalog, remplaçant les informations stockées et transmises depuis Miva.

En savoir plus sur les informations produit par plateforme.