VibeFox 99Minutos for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

PHP : 8.0 ou ultérieur.

Clé d'API 99minutos (pour le contrôle de couverture uniquement) : obtenez-la auprès de votre gestionnaire de compte 99minutos ou sur le portail développeurs de 99minutos (developers.99minutos.com). Les clés sandbox et production sont différentes. Si vous n'utilisez que la matrice des prix, vous n'avez pas besoin de clé d'API.

Pays : 99minutos livre au Mexique, en Colombie, au Chili et au Pérou. Les pays vers lesquels vous expédiez doivent être activés dans System > Localisation > Countries.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_99minutos-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_99minutos.ocmod.zip. Installez uniquement le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_99minutos-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD, vous n'avez donc pas besoin d'actualiser Extensions > Modifications. Au lieu de l'installeur, vous pouvez copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox 99Minutos et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page des réglages.

4. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Renseignez la Price matrix (au moins une ligne, par exemple « * Default ») et, si vous le souhaitez, la clé d'API et le mode de contrôle de couverture (voir Configuration). Activez Enable 99Minutos et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_99minutos.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées sur la même page. Cliquez sur Install (le bouton vert +) à côté.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox 99Minutos, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page des réglages et ses champs sont les mêmes dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous n'avez pas activé Enable 99Minutos et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages 99minutos que vous aviez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi les résultats de couverture mis en cache. Si une valeur est incorrecte, rien n'est enregistré et la page indique la raison, par exemple Enter a method title (1 to 64 characters)., un message indiquant qu'un champ doit être un nombre égal ou supérieur à 0, ou que Min weight (kg) ne doit pas être supérieur à Max weight (kg). Après l'enregistrement, des avertissements au-dessus des réglages vous signalent quand le mode ne peut pas fonctionner tel que configuré : la matrice des prix est vide, un mode de contrôle de couverture est choisi sans clé d'API, la matrice contient des lignes pour des pays que 99minutos ne dessert pas, ou la boutique n'a pas de classe de poids « kg » et son unité de poids n'est pas reconnue par l'extension (les poids sont alors lus en kilogrammes). Seuls les administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

Général

Les réglages s'appliquent à toutes les zones géographiques. 99Minutos n'est proposé que pour le Mexique, la Colombie, le Chili et le Pérou comme pays de destination.

Enable 99Minutos : affiche ou masque 99Minutos au paiement. Par défaut : désactivé.

Method title : le nom du mode de livraison affiché au client dans le panier et au paiement. Par défaut : 99Minutos. Obligatoire, jusqu'à 64 caractères.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Avec une classe de taxe, OpenCart ajoute la taxe au prix de la matrice.

Sort order : la position de 99Minutos parmi les modes de livraison au paiement. Un nombre entier.

API 99minutos (contrôle de couverture) (facultatif)

L'API sert uniquement à vérifier si 99minutos livre au code postal du client. Le prix provient toujours de la matrice.

Coverage check : si le code postal est contrôlé et comment.

Off — matrix price for every postcode: aucune requête vers l'API. Par défaut.

Strict — show only if the API confirms coverage: le mode n'est affiché que si l'API de 99minutos confirme que le code postal est desservi. Si l'API est indisponible, si aucun code postal n'est saisi ou si aucune clé d'API n'est définie, le mode est masqué.

Soft — hide if not covered; if the API is unavailable, still show the matrix price: le mode n'est masqué que lorsque l'API répond que le code postal n'est pas desservi. En cas d'erreur d'API, sans code postal ou sans clé d'API, le prix de la matrice est utilisé.

Avec un contrôle de couverture, le mode n'apparaît qu'après la saisie d'un code postal par le client. Les résultats sont mis en cache : desservi pendant 6 heures, non desservi pendant 30 minutes, erreur d'API pendant 5 minutes, mais jamais plus longtemps que la durée de vie du cache d'OpenCart (1 heure par défaut). Seul le code postal est envoyé à 99minutos, en majuscules et avec uniquement des lettres et des chiffres.

API key : votre clé d'API 99minutos, envoyée comme jeton Bearer au point d'accès de couverture de 99minutos. Obligatoire lorsque le contrôle de couverture est activé. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. La clé est enregistrée telle que saisie ; seuls les espaces qui l'entourent sont supprimés.

Remove the saved API key : affiché seulement lorsqu'une clé est enregistrée. Activez-le et cliquez sur Save pour supprimer la clé.

Environment : Sandbox (test) (par défaut) ou Production. Sandbox et production utilisent des clés d'API différentes ; choisissez l'environnement qui correspond à votre clé.

Tarifs

Les prix sont exprimés dans la devise par défaut de votre boutique, hors taxes, et sont utilisés tels que saisis. Le prix final est affiché dans la devise du client.

Price matrix : un tableau de pays de destination et de prix. Cliquez sur Add country pour ajouter une ligne et sur le bouton × pour en supprimer une. Chaque ligne comporte un Country (* Default, Mexique, Colombie, Chili ou Pérou), un Base price et des prix pour les tailles XS (jusqu'à 1 kg), S (jusqu'à 2 kg), M (jusqu'à 3 kg), L (jusqu'à 5 kg) et XL (plus de 5 kg). Un prix de taille vide ou égal à 0 revient au Base price. La ligne * Default s'applique aux pays qui n'ont pas leur propre ligne. Si un pays a plusieurs lignes, la première est utilisée. Le point et la virgule sont tous deux acceptés comme séparateur décimal ; les prix vides, invalides ou négatifs sont enregistrés à 0. Tant que la matrice ne contient pas au moins une ligne, le mode n'est pas affiché au paiement.

Calculation : Per order — size by the total cart weight (par défaut) applique un seul prix selon la taille du colis de tout le panier. Per item — each unit priced by its own weight tarifie chaque unité selon la taille de son propre poids et additionne les prix.

Free shipping : active la livraison gratuite à partir d'un montant de commande.

Free shipping from : le sous-total des produits à expédier (après le coupon, avant taxes) à partir duquel le tarif est de 0. Utilisé seulement lorsque Free shipping est activé.

Restrictions

Min weight (kg) : masque le mode si le panier est plus léger. 0 signifie sans limite (par défaut). Ce poids ne peut pas être supérieur à Max weight (kg). Les poids des produits sont convertis depuis leur classe de poids.

Max weight (kg) : masque le mode si le panier est plus lourd. Par défaut : 25. 0 signifie sans limite ; un champ vide signifie 25 kg.

Minimum subtotal : n'affiche le mode que si le sous-total des produits à expédier (après le coupon, avant taxes) atteint ce montant. Laissez le champ vide pour toujours l'afficher.

Geo zone : ne propose 99Minutos que pour les adresses de cette zone géographique. All zones (par défaut) signifie sans limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Restrict countries : ne propose le mode que pour les pays indiqués ci-dessous. C'est un filtre supplémentaire, en plus de la Geo zone.

Countries : une liste des pays de 99minutos (Mexique, Colombie, Chili, Pérou). Utilisée seulement lorsque Restrict countries est activé. Laissez-la vide pour autoriser tous les pays de 99minutos.

Avancé

Debug log : enregistre les calculs de tarifs dans storage/logs/vfd_99m_debug.log.php. Ce fichier n'est pas lisible depuis le web. Les erreurs d'API sont journalisées même lorsque cette option est désactivée. Les clés d'API ainsi que les noms et adresses des clients ne sont jamais journalisés. Désactivez le journal une fois terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_99m_debug.old.log.php et un nouveau journal est démarré.

Log : affiche la taille et les dernières entrées du journal de débogage. Cliquez sur Clear log pour le vider.

Remove data on uninstall : si cette option est activée, la désinstallation de l'extension supprime les réglages 99minutos, le cache de couverture et le journal. Désactivée (par défaut), ils sont conservés pour une réinstallation. Les commandes sont conservées dans tous les cas.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé d'API n'est pas exportée.

Import : collez un JSON précédemment exporté et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont contrôlées comme lors d'un enregistrement normal. La clé d'API enregistrée est conservée.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix de 99Minutos. Si une Geo zone est définie et que l'adresse se trouve en dehors, 99Minutos n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. Le mode n'est proposé que si le pays de livraison est le Mexique, la Colombie, le Chili ou le Pérou (et figure dans la liste Countries si Restrict countries est activé). L'extension vérifie ensuite les limites de poids et le Minimum subtotal. Le montant de la commande est le prix des produits à expédier, après la remise du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et le crédit magasin ne sont pas pris en compte.

Si un contrôle de couverture est activé, l'extension demande à l'API de 99minutos si le code postal est desservi. Le délai d'attente des requêtes est de 10 secondes et la réponse est mise en cache, si bien que le même code postal ne déclenche pas une nouvelle requête. Les erreurs d'API ne sont jamais affichées au client : en mode Strict, le mode est masqué ; en mode Soft, le prix de la matrice est utilisé. La livraison gratuite ne contourne pas le contrôle de couverture.

Le prix est pris dans la ligne de la matrice du pays de livraison, ou dans la ligne * Default. Si aucune des deux n'existe, le mode est masqué. Si Free shipping est activé et que le montant de la commande atteint Free shipping from, le tarif est de 0. Le prix est calculé dans la devise par défaut de votre boutique, arrondi à ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

L'extension ne récupère pas de tarifs en temps réel auprès de 99minutos : les prix proviennent toujours de votre matrice. Elle ne crée ni envois ni commandes chez 99minutos, n'imprime pas d'étiquettes (guides), ne suit pas les colis, ne propose pas les points de retrait Punto99 et ne gère pas le paiement à la livraison. Elle n'ajoute rien aux commandes : la commande affiche le nom du mode et le coût de livraison comme tout autre mode OpenCart. Créez vos envois dans votre compte 99minutos comme d'habitude.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit 99Minutos dans la fenêtre Shipping method options. Le mode fonctionne de la même manière que sur OpenCart 3.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox 99Minutos est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour supprimer la clé de cette boutique. En dessous, il y a la ligne Product: opencart-shipping-99minutos et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation Modify pour l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine. Vous gérez vos licences et vos domaines dans votre compte vibefox.net.

Sans clé active, le mode de livraison 99Minutos n'est pas affiché aux clients au paiement, et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit encore le mode dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion administrateur, donc sans clé active le mode est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation de l'extension supprime toujours la clé de licence et le statut de licence.

Dépannage

99Minutos n'apparaît pas au paiement : vérifiez que la licence est active et que Enable 99Minutos est activé. Le pays de livraison doit être le Mexique, la Colombie, le Chili ou le Pérou, et être activé dans System > Localisation > Countries. Vérifiez Geo zone et Restrict countries. Vérifiez que la Price matrix contient une ligne pour ce pays ou une ligne * Default, puis contrôlez les limites de poids et le Minimum subtotal. Vérifiez que les produits ont Requires Shipping réglé sur Yes. Les avertissements affichés après Save signalent les réglages qui masquent le mode.

Le mode n'apparaît qu'après la saisie d'un code postal : c'est normal avec un contrôle de couverture. En mode Strict, il n'apparaît que lorsque l'API confirme la couverture.

Le mode est toujours masqué en mode Strict : activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Une erreur HTTP 401 ou 403 signifie que l'API a rejeté la clé : vérifiez la clé et que Environment correspond (les clés sandbox et production sont différentes). Utilisez le mode Soft si les clients doivent malgré tout obtenir le prix de la matrice lorsque l'API est indisponible.

Le prix n'est pas celui attendu : vérifiez Calculation (par commande ou par article), ainsi que les poids et classes de poids des produits. Un prix de taille vide ou égal à 0 revient au Base price. Avec une Tax class, la taxe s'ajoute au prix de la matrice.

Les résultats de couverture semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela vide les résultats de couverture mis en cache.

La page indique « Warning: You do not have permission to modify VibeFox 99Minutos! » : votre groupe d'utilisateurs administrateurs n'a peut-être que le droit de consulter les réglages. Accordez au groupe le droit de modification pour extension/shipping/vfd_99minutos (OpenCart 3) ou extension/vfd_99minutos/shipping/vfd_99minutos (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API 99minutos peut être remplacée par le réglage vfd_99m_api_url (pour les tests) ; il n'a pas de champ sur la page des réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox 99Minutos. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable 99Minutos, Sort order, Tax class et Geo zone. Les résultats de couverture mis en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages 99minutos et le journal de débogage sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les commandes existantes conservent leur mode de livraison et leur coût.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox 99Minutos dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléversé.

99minutos est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à 99minutos ni approuvée par elle.