VibeFox 99Minutos for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

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

Pays : 99minutos livre au Mexique, en Colombie, au Chili et au Pérou. Les pays vers lesquels vous expédiez doivent être actifs dans International > Locations.

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

Installation

1. Dans le back office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox 99Minutos dans la liste des modules puis cliquez sur Configure.

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

4. Remplissez la Price matrix (au moins une ligne, par exemple « * Default ») et, en option, la clé API et le mode de contrôle de couverture (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur 99Minutos avec le texte de délai de livraison Courier delivery. Le transporteur est affecté à toutes les zones et à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. Les zones du Mexique, de la Colombie, du Chili et du Pérou doivent rester activées pour le transporteur. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox 99Minutos > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi les résultats de couverture en cache. Après l'enregistrement, la page vous avertit si la matrice de prix est vide, si elle contient des lignes pour des pays que 99minutos ne dessert pas, si un mode de contrôle de couverture est choisi sans clé API, ou si l'unité de poids de la boutique n'est pas reconnue par le module (les poids sont alors pris en kilogrammes). Rien n'est enregistré et une erreur s'affiche si Method title dépasse 64 caractères, si un champ de poids ou de montant n'est pas un nombre égal ou supérieur à 0, ou si Min weight (kg) est supérieur à Max weight (kg). Si la page affiche The 99Minutos carrier was not found — reset the module to create it again., consultez la section Dépannage.

Général

Enable 99Minutos : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

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

Tax : la règle de taxe du transporteur, ou No tax. Avec une règle de taxe, PrestaShop ajoute la taxe au prix de livraison de la matrice.

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

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

Coverage check : si et comment le code postal est vérifié.

Avec un contrôle de couverture, le transporteur n'apparaît qu'après que le client a saisi un code postal. Les résultats sont mis en cache : couvert pendant 6 heures, non couvert pendant 30 minutes, erreur API pendant 5 minutes. Seul le code postal est envoyé à 99minutos, en majuscules et avec des lettres et des chiffres uniquement.

API key : votre clé API 99minutos, envoyée sous forme de jeton Bearer au point de terminaison 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 en début et fin sont supprimés.

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

Environment : Sandbox (test) (par défaut) ou Production. Sandbox et production utilisent des clés API différentes ; choisissez donc l'environnement correspondant à 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 panier du client.

Price matrix : un tableau des pays de destination et des prix. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille 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 de ligne propre. 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 transporteur n'est pas affiché au paiement.

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

Free shipping : active la livraison gratuite à partir d'un sous-total du panier.

Free shipping from : le sous-total du panier (après remises, hors taxes) à partir duquel le tarif est de 0. Utilisé uniquement lorsque Free shipping est activé.

Restrictions

Min weight (kg) : masque le transporteur si le panier est plus léger. 0 signifie aucune limite. Ne peut pas être supérieur à Max weight (kg). Les poids des produits sont convertis depuis l'unité de poids de votre boutique.

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

Minimum subtotal : n'affiche le transporteur que si le sous-total du panier (après remises, hors taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Restrict countries : ne propose le transporteur que pour les pays ci-dessous. C'est un filtre supplémentaire qui s'ajoute aux zones du transporteur. Utile lorsqu'une zone couvre plusieurs pays.

Countries : une sélection des pays de 99minutos (Mexique, Colombie, Chili, Pérou). Maintenez Ctrl (Cmd) pour en sélectionner plusieurs. Utilisé uniquement lorsque Restrict countries est activé. Laissez vide pour autoriser tous les pays de 99minutos.

Avancé

Debug log : écrit les calculs de tarifs dans logs/vfd_99m_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs API sont journalisées même si cette option est désactivée. Les clés API ainsi que les noms et adresses des clients ne sont jamais journalisés. Désactivez le journal lorsque vous avez terminé.

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 : lorsque l'option est activée, la désinstallation du module supprime les réglages, le transporteur, le cache de couverture et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Les commandes sont conservées dans tous les cas.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix 99Minutos. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le sous-total du panier. Le transporteur n'est proposé que lorsque 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é). Le module vérifie ensuite les limites de poids et le Minimum subtotal.

Si un mode de contrôle de couverture est activé, le module demande à l'API 99minutos si le code postal est couvert. La requête a un délai d'attente 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 API ne sont jamais affichées au client : en mode Strict, le transporteur 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 tiré de la ligne de la matrice correspondant au pays de livraison, ou de la ligne * Default. Si aucune des deux n'existe, le transporteur est masqué. Si Free shipping est activé et que le sous-total du panier atteint Free shipping from, le tarif est de 0. Le prix est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne récupère pas de tarifs en temps réel auprès de 99minutos : les prix proviennent toujours de votre matrice. Il ne crée ni envois ni commandes chez 99minutos, n'imprime pas d'étiquettes (guides), ne suit pas les colis, ne propose pas de points de retrait Punto99 et ne gère pas le paiement à la livraison. Créez les envois dans votre compte 99minutos comme d'habitude.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox 99Minutos est le premier bloc de Modules > Module Manager > VibeFox 99Minutos > Configure, au-dessus des réglages. Saisissez la clé dans License key puis cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date de fin de validité de la licence et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-99minutos et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back office (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, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, le transporteur 99Minutos n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. La vitrine de PrestaShop ne sait pas que vous êtes connecté au back office : le transporteur est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié automatiquement pendant votre travail dans le back office : 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 ou la réinitialisation du module 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 actif dans International > Locations. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et son groupe. Vérifiez que la Price matrix contient une ligne pour ce pays ou une ligne * Default, puis contrôlez les limites de poids, le Minimum subtotal et Restrict countries. Des produits peuvent aussi être limités à certains transporteurs sur la fiche produit.

Le transporteur 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 transporteur est toujours masqué en mode Strict : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Une erreur HTTP 401 ou 403 signifie que la clé API a été refusée : 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 quand même voir 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), les poids des produits et l'unité de poids de votre boutique (International > Localization). Un prix de taille vide ou égal à 0 revient au Base price. Avec une règle de taxe dans Tax, 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 du module. Cela vide les résultats de couverture en cache.

La page indique que le transporteur 99Minutos est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. Il en va de même pour le message The settings were saved, but the carrier could not be updated. Reset the module to create it again.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox 99Minutos et choisissez Uninstall. La clé de licence et le statut de licence sont toujours supprimés. Le cache de couverture est également toujours supprimé. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) ainsi que les réglages et le journal. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur enregistré le statut qu'il avait avant la désinstallation ; ainsi, Reset n'active pas un transporteur désactivé.

99minutos est une marque de son propriétaire respectif. Ce module n'est ni affilié à 99minutos, ni approuvé par cette entreprise.