VibeFox Estafeta for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur avec l'extension cURL.

Compte DrEnvio (uniquement pour les tarifs en temps réel) : les tarifs Estafeta en temps réel proviennent de DrEnvio, partenaire d'Estafeta au Mexique. Créez un compte sur drenvio.com, activez Estafeta, configurez-y votre adresse d'enlèvement et copiez la clé API depuis votre tableau de bord DrEnvio. C'est la même clé que celle qu'utilise le plugin officiel DrEnvio. Si vous n'utilisez que vos propres tarifs, vous n'avez pas besoin de compte DrEnvio.

Produits : les produits doivent avoir un poids pour les tarifs en temps réel.

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

Installation

Le téléchargement est un seul fichier zip contenant les paquets des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_estafeta-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_estafeta.ocmod.zip. N'installez que le paquet de 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_estafeta-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'installateur, vous pouvez aussi copier le contenu du dossier upload du paquet dans le dossier racine de votre boutique.

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

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page de configuration.

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

5. Saisissez la DrEnvio API key et, si vous le souhaitez, le Origin postcode. Si votre devise par défaut n'est pas le MXN, saisissez le MXN exchange rate. Définissez un tarif par pays pour MX ou un Fallback cost si le mode de livraison doit rester visible lorsque DrEnvio ne propose pas de tarif. Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_estafeta.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension à partir du 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é de celui-ci.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Estafeta, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de 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 de livraison reste désactivé tant que vous n'activez pas Enable/Disable et n'enregistrez pas. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages Estafeta conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Estafeta > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le cache des tarifs DrEnvio. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

En haut de la page, l'extension affiche des avertissements : pas de clé API DrEnvio, devise par défaut autre que le MXN sans taux de change, pas de tarif par pays pour MX et pas de coût de repli (le mode de livraison est alors masqué lorsqu'il n'y a pas de tarif en temps réel, ou jamais affiché sans clé API), ou pas de classe de poids en kg (les poids des produits sont alors convertis selon le nom de l'unité de leur classe de poids, et les unités inconnues sont considérées comme des kg ; ajoutez une classe kg dans System > Localisation > Weight Classes). Les champs numériques acceptent un point ou une virgule décimale. À l'enregistrement, une valeur incorrecte est signalée puis effacée ou réinitialisée comme indiqué à chaque champ, le formulaire affiche la valeur enregistrée, et les autres réglages sont tout de même enregistrés (The other settings were saved.).

Général

Le mode de livraison est proposé pour la zone géographique ci-dessous (ou pour toutes les adresses), ou pour les pays de Availability without shipping zones.

Enable/Disable : active ou désactive la livraison Estafeta. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client lors du paiement. Par défaut : Estafeta. Obligatoire : de 1 à 64 caractères, sans < > ; = # { }. Un nom invalide est signalé et l'ancien nom est conservé.

Tax class : la classe de taxe ajoutée au coût de livraison, ou No tax (par défaut). La présence de la TVA mexicaine (IVA) dans les prix DrEnvio dépend de votre compte DrEnvio. Si elle y figure déjà, choisissez No tax.

Geo zone : propose Estafeta uniquement pour les adresses de cette zone géographique, par exemple une zone « Mexique ». All zones (par défaut) signifie sans limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Elle n'est pas utilisée lorsque Ignore shipping zones est activé.

Sort order : la position d'Estafeta parmi les modes de livraison lors du paiement. Un nombre entier.

Tarifs en temps réel (API DrEnvio)

La section indique où obtenir la clé. Le service Estafeta le moins cher pour l'adresse est proposé. Sans clé, les tarifs de Prices without a live rate sont utilisés.

DrEnvio API key : la clé API de votre tableau de bord DrEnvio. 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.

Remove the saved API key : affiché uniquement lorsqu'une clé est enregistrée. Activez-le et enregistrez pour supprimer la clé. Seuls Country prices et le Fallback cost sont alors utilisés. Une clé saisie dans le champ ci-dessus remplace la clé enregistrée.

Origin country : le code pays à deux lettres de l'adresse d'enlèvement. Par défaut : MX. Envoyé uniquement avec le code postal d'origine. Un code invalide est signalé et remis à MX.

Origin postcode : le code postal à 5 chiffres de l'adresse d'enlèvement. Laissez-le vide pour utiliser l'adresse d'origine enregistrée dans votre compte DrEnvio. Un code postal qui ne comporte pas 5 chiffres est effacé et signalé à l'enregistrement.

MXN exchange rate : DrEnvio établit ses devis en pesos mexicains. Nécessaire uniquement si votre devise par défaut n'est pas le MXN : la valeur de 1 MXN dans votre devise par défaut, par exemple 0.05. Sans lui, les tarifs en temps réel ne sont pas utilisés. Il doit être supérieur à 0. Si la devise de la boutique est le MXN, laissez-le vide.

Tarifs sans tarif en temps réel

Utilisés lorsqu'il n'y a pas de clé API ou que DrEnvio ne renvoie aucun tarif Estafeta (API indisponible, code postal inconnu, code postal pas encore saisi). Les prix sont exprimés dans la devise par défaut de votre boutique, hors taxes.

Country prices : un pays de destination par ligne, au format CC:PRIX, par exemple MX:150. Utilisez un point ou une virgule décimale, sans séparateur de milliers. Les parties dans un autre format sont ignorées et signalées à l'enregistrement.

Fallback cost : le prix lorsqu'il n'y a ni tarif en temps réel ni tarif par pays. Laissez-le vide pour masquer le mode de livraison ; 0 signifie livraison gratuite.

Calculation type : Per order (par défaut) facture le prix une seule fois. Per item (price x number of items) le multiplie par le nombre d'articles du panier. Cela s'applique aux Country prices et au Fallback cost. Un tarif DrEnvio en temps réel correspond toujours au prix de l'ensemble du colis.

Conditions

Free shipping from : la livraison est gratuite lorsque le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint ce montant. Aucune requête n'est alors envoyée à DrEnvio. Laissez-le vide pour ne jamais offrir la livraison gratuite.

Minimum subtotal : affiche le mode de livraison uniquement si le même sous-total atteint au moins ce montant. Laissez-le vide pour l'afficher toujours.

Min weight (kg) : le poids minimum du panier pour que le mode de livraison apparaisse. 0 signifie sans limite (par défaut).

Max weight (kg) : le poids maximum du panier. Le mode de livraison est masqué s'il est dépassé. Par défaut : 30. 0 signifie sans limite.

Si Min weight est supérieur à Max weight, l'enregistrement affiche une erreur et les deux poids restent inchangés. Les poids des produits sont convertis en kg à partir de la classe de poids de chaque produit.

Disponibilité sans zones de livraison

Ignore shipping zones : propose le mode de livraison pour les pays ci-dessous sans vérifier la zone géographique. Par défaut : désactivé.

Countries : les pays de destination pour ce mode. Laissez-le vide pour tous les pays. Utilisé uniquement lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les requêtes API et les calculs de tarifs dans storage/logs/vfd_est_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_est_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours enregistrées, même lorsque le journal est désactivé. La clé API et les adresses des clients ne sont jamais enregistrées. Désactivez le journal lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_est_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 : lorsqu'elle est activée, la désinstallation de l'extension supprime tous ses réglages et le journal. Lorsqu'elle est désactivée (par défaut), tout est conservé pour une réinstallation. Les services Estafeta enregistrés dans les commandes sont toujours conservés.

Import / Export

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

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

Fonctionnement lors du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Estafeta. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Estafeta n'est pas proposé. Seuls les produits dont Requires Shipping est défini sur Yes sont pris en compte : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le sous-total correspond au prix de ces produits après la remise du coupon et avant taxes ; les cartes cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. L'extension vérifie ensuite les conditions : la liste Countries (lorsque Ignore shipping zones est activé), le poids du panier et le sous-total minimum. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à DrEnvio.

Sinon, l'extension envoie à DrEnvio le pays et le code postal de destination, le poids du panier, le nombre d'articles et le sous-total en MXN, ainsi que le code postal d'origine si vous en avez défini un. Les codes postaux mexicains doivent comporter 5 chiffres ; tant que le client n'a pas saisi d'adresse de livraison avec un tel code, aucune requête n'est envoyée. DrEnvio renvoie les devis de tous les transporteurs de votre compte. L'extension n'utilise que les devis Estafeta, ignore les prix nuls, retient le moins cher et le convertit dans votre devise par défaut. Le prix est arrondi aux décimales de cette devise et affiché au client dans sa devise, avec la taxe de la Tax class sélectionnée.

Chaque réponse est mise en cache pendant 1 heure. Une requête échouée ou un trajet sans tarif Estafeta est retenu pendant 5 minutes, afin qu'une API lente ou défaillante ne ralentisse jamais chaque mise à jour du paiement. Le délai d'attente de l'API est de 12 secondes. Dans ces cas, le client ne voit aucune erreur : le tarif par pays ou le coût de repli est utilisé, ou le mode de livraison est masqué si aucun n'est défini. La raison est inscrite dans le journal.

Le client ne voit que le nom du mode de livraison et le prix. L'extension calcule uniquement les tarifs. Elle ne crée pas d'envois, n'imprime pas d'étiquettes (guías) et ne suit pas les colis ; créez l'envoi dans votre compte DrEnvio ou Estafeta. Le client ne peut pas choisir un service Estafeta précis ni un bureau Estafeta, et les taux de change ne sont pas mis à jour automatiquement.

Sur OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement, puis choisit Estafeta dans la fenêtre Shipping method options. Le mode fonctionne de la même façon que sur OpenCart 3.

Commandes

Lorsqu'une commande avec Estafeta est passée, l'extension enregistre le tarif affiché au client, sans nouvelle requête à DrEnvio. Les modifications ultérieures de la commande dans l'administration ne le changent pas. Sur OpenCart 4, le paiement conserve une seule commande et la met à jour à chaque nouvelle confirmation du client ; le tarif enregistré est donc remplacé par le dernier tarif du paiement. Si le client passe à un autre mode de livraison, le panneau n'est plus affiché pour cette commande.

La page de commande dans Sales > Orders affiche un panneau Estafeta :

Estafeta service : le service Estafeta du devis DrEnvio et son délai de livraison. Affiché uniquement pour les tarifs en temps réel.

Price source : Live DrEnvio rate, Country price (no live rate), Fallback cost (no live rate) ou Free shipping threshold.

Shipping cost : le prix de livraison calculé lors du paiement dans votre devise par défaut, hors taxes.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Estafeta est le premier bloc de Extensions > Extensions > Shipping > VibeFox Estafeta > 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 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 supprimer la clé de cette boutique. En dessous se trouvent la ligne Product: opencart-shipping-estafeta 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 : l'adresse de la boutique issue de la configuration d'OpenCart. Supprimer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, Estafeta n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode de livraison 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

Estafeta n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez Geo zone, ou Ignore shipping zones et Countries. Vérifiez les avertissements en haut de la page de l'extension, les limites de poids et Minimum subtotal. Sans clé API, ou lorsque DrEnvio ne propose pas de tarif Estafeta, le mode de livraison a besoin d'un tarif par pays pour la destination ou d'un coût de repli. Vérifiez que les produits ont Requires Shipping défini sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Il indique la raison : pas de clé API, pas de taux de change pour une boutique dont la devise par défaut n'est pas le MXN, code postal absent ou invalide, clé API refusée (HTTP 401 ou 403 de DrEnvio, vérifiez la clé API), pas de tarif Estafeta pour le trajet (le journal liste les transporteurs renvoyés par DrEnvio), ou un tarif dans une devise autre que le MXN.

Le prix inclut-il la TVA (IVA) ? Cela dépend de votre compte DrEnvio. Si les prix DrEnvio incluent déjà la TVA, réglez Tax class sur No tax.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide le cache des tarifs DrEnvio.

La page de commande n'a pas de panneau Estafeta : le panneau n'est affiché que pour les commandes passées avec Estafeta alors que l'extension était installée et activée.

La page affiche « Warning: You do not have permission to modify VibeFox Estafeta! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_estafeta (OpenCart 3) ou extension/vfd_estafeta/shipping/vfd_estafeta (OpenCart 4) dans System > Users > User Groups.

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Estafeta. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Estafeta et le journal de débogage sont également 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 services Estafeta enregistrés dans les commandes sont conservés dans les deux cas, et les commandes gardent leur mode et leur coût de livraison.

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

Estafeta et DrEnvio sont des marques de leurs propriétaires respectifs. Cette extension n'est ni affiliée ni approuvée par Estafeta ou DrEnvio.