VibeFox Chilexpress for OpenCart — Aide

Prérequis

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

PHP: 8.0 ou ultérieur.

Clés d'API Chilexpress (uniquement pour les tarifs en direct) : créez un compte sur le portail développeurs de Chilexpress (developers.wschilexpress.com) et souscrivez à deux produits : Rating (Cotizador) et Coverage (Coberturas / Georreferencia). Chaque produit a sa propre clé d'abonnement. Les clés de test ne fonctionnent qu'avec l'environnement de test ; les clés de production sont délivrées aux clients professionnels de Chilexpress disposant d'un contrat client. Vous avez aussi besoin du code de comuna Chilexpress de la comuna d'où vous expédiez, par exemple STGO. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de clés d'API.

Régions du Chili (uniquement pour les tarifs en direct) : les tarifs en direct nécessitent la région (zone) de l'adresse de livraison. OpenCart 3.0.5.0 contient 15 des 16 régions du Chili ; l'extension peut ajouter les régions manquantes (voir Chilean regions ci-dessous). Le pays Chili doit exister dans la boutique.

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 pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_chilexpress-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_chilexpress.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_chilexpress-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'Installer, 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 Chilexpress et cliquez sur Install (le bouton vert +).

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

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. Remplissez le tableau Country prices. Pour les tarifs en direct, saisissez les deux clés d'abonnement, le code de comuna d'origine et, si la devise de la boutique n'est pas le CLP, le taux de change en CLP. Cliquez sur Add Chilean regions si la page indique des régions manquantes, puis choisissez la source des tarifs (voir Configuration). 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_chilexpress.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 Chilexpress, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton au crayon).

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

Après l'installation, la méthode reste désactivée tant que vous n'activez pas Enable/Disable et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Chilexpress que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Après l'enregistrement, vous voyez Settings saved. Cached Chilexpress rates and comuna lists were cleared. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages, vider le journal ou ajouter des régions.

La page affiche les problèmes en haut : des tarifs API sont sélectionnés mais la clé API Rating est vide ; la clé API Coverage est vide ; le code de comuna d'origine est vide ou invalide ; la devise de la boutique n'est pas le CLP et aucun taux de change CLP n'est défini ; Country prices n'a pas de ligne pour le Chili ni pour la valeur par défaut ; le Chili n'a aucune zone dans la boutique ; l'unité de poids ou de longueur de la boutique n'est pas connue de l'extension (les poids sont alors lus en kg et les dimensions en cm ; utilisez kg, g, lb ou oz et cm, mm, m ou in dans System > Localisation). Les nombres peuvent être saisis avec un point ou une virgule. Rien n'est enregistré et la page affiche les erreurs si Name est vide, contient l'un des caractères < > ; = # { } ou dépasse 64 caractères, si un nombre est invalide ou négatif, si le CLP exchange rate vaut 0, si Min weight (kg) est supérieur à Max weight (kg), si Origin county code n'est pas un code de comuna, ou si Sort order n'est pas un nombre entier.

Général

Une méthode de livraison « Chilexpress » pour chaque zone géographique, ou pour la zone géographique choisie sous Disponibilité.

Enable/Disable: affiche ou masque Chilexpress au paiement. Par défaut : désactivé.

Name: le nom de la méthode de livraison affiché au client au paiement. Par défaut : Chilexpress. Obligatoire, jusqu'à 64 caractères.

Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Les tarifs de l'API Chilexpress sont utilisés tels qu'ils sont cotés. Choisissez No tax si la cotation inclut déjà l'IVA et que votre boutique ajouterait une taxe par-dessus.

Sort order: la position de Chilexpress parmi les méthodes de livraison au paiement. Un nombre entier.

Tarifs

Rate source: d'où vient le prix.

Les tarifs en direct ne sont disponibles que pour les destinations au Chili. Les autres pays utilisent toujours les prix fixes.

Country prices: une liste de pays de destination avec une colonne Price et des prix facultatifs par taille de colis, dans la devise par défaut de votre boutique, hors taxes. La taille dépend du poids du panier : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg, XL au-delà de 5 kg. Une taille laissée à 0 utilise Price. Cliquez sur Add country pour ajouter une ligne. La ligne * Default (other countries) s'applique aux pays sans ligne propre. Un pays sans ligne (et sans la ligne par défaut) n'a pas de prix fixe, donc la méthode y est masquée. Une ligne enregistrée dont le prix et les prix par taille valent tous 0 donne une livraison gratuite. Un tableau vide affiche une ligne pour le Chili à 0 ; saisissez donc de vrais prix avant d'enregistrer la page. Un pays en double ou un prix invalide est corrigé (le doublon est ignoré, le prix ramené à 0), et un avertissement liste les corrections.

Calculation type: Per order (par défaut) facture le prix fixe une seule fois. Per item (fixed price x number of items) le multiplie par le nombre d'articles du panier. Un tarif de l'API Chilexpress est toujours coté pour le colis entier.

API Chilexpress (tarifs en direct)

La section commence par des liens vers le portail développeurs et les pages d'abonnement Rating et Coverage.

Test environment: utilise l'environnement de test de Chilexpress (qaservices.wschilexpress.com). Utilisez-le avec des clés de test et désactivez-le sur une boutique en production. Par défaut : désactivé.

Rating API key: la clé d'abonnement du produit Rating (Cotizador).

Coverage API key: la clé d'abonnement du produit Coverage (Coberturas / Georreferencia). Elle sert à trouver le code de comuna Chilexpress de la comuna du client (le champ City de l'adresse, avec sa région).

Après l'enregistrement, un champ de clé 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 vous la saisissez ; seuls les espaces autour sont supprimés.

Remove the saved Rating API key et Remove the saved Coverage API key: activez l'une de ces options et cliquez sur Save pour supprimer cette clé.

Origin county code: le code de comuna Chilexpress de la ville d'où vous expédiez, 2 à 5 lettres, par exemple STGO (Santiago Centro), PROV (Providencia) ou VALP (Valparaíso). Il est vide après l'installation. Une valeur qui n'est pas un code de comuna est refusée avec une erreur.

Service: le service Chilexpress utilisé pour le tarif. S'il n'est pas proposé pour la destination, le service le moins cher proposé est utilisé.

CLP exchange rate: Chilexpress cote en pesos chiliens. Nécessaire uniquement si la devise par défaut de votre boutique n'est pas le CLP : le prix de 1 CLP dans cette devise, par exemple 0.001. Sans lui, les tarifs de l'API ne sont pas utilisés. Si la devise de la boutique est le CLP, laissez-le vide. La valeur doit être supérieure à 0.

Chilean regions: les comunas du Chili sont recherchées par région ; les tarifs en direct ont donc besoin de la région (zone) de l'adresse. Le champ indique combien de zones le Chili possède et quelles régions manquent, avec le bouton Add Chilean regions. Il n'ajoute que les régions manquantes comme zones du Chili ; les zones existantes ne sont pas modifiées et une région n'est pas ajoutée deux fois. Quand les 16 régions sont en place, le champ indique All 16 Chilean regions are zones of Chile. Si le Chili n'est pas un pays de la boutique, le champ le signale : ajoutez-le dans System > Localisation > Countries.

Disponibilité

Min weight (kg): le poids minimum du panier pour que la méthode apparaisse. 0 signifie aucune limite (par défaut).

Max weight (kg): la méthode est masquée au-delà de ce poids de panier. Par défaut : 25. 0 signifie aucune limite ; un champ vide signifie 25 kg.

Minimum subtotal: n'affiche la méthode que si le sous-total du panier (produits à expédier, après coupons, hors taxes) atteint au moins ce montant. Laissez-le vide pour l'afficher toujours.

Geo zone: propose la méthode uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Non utilisé tant que Ignore shipping zones est activé.

Ignore shipping zones: propose la méthode pour les pays ci-dessous sans vérifier la zone géographique.

Countries: les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Livraison gratuite

Free shipping: active le seuil de livraison gratuite.

Free shipping from: le sous-total du panier (produits à expédier, après coupons, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé. Dans ce cas, aucune requête n'est envoyée à l'API.

Avancé

Debug log: écrit les requêtes API et les calculs de tarifs dans storage/logs/vfd_chx_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées, même si cette option est désactivée. Les clés API et les adresses des clients ne sont jamais journalisées. Quand le fichier atteint 5 Mo, il est déplacé vers vfd_chx_debug.old.log.php et un nouveau journal commence.

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 activé, la désinstallation de l'extension supprime tous ses réglages, les tarifs en cache et le journal. Si désactivé (par défaut), tout est conservé pour une réinstallation. Les commandes et les services Chilexpress enregistrés avec elles sont toujours conservés.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Les clés API ne sont pas exportées.

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. Les clés API enregistrées sont conservées.

Fonctionnement au paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le prix Chilexpress. Si une Geo zone est définie, que Ignore shipping zones est désactivé et que l'adresse est hors de la zone, Chilexpress n'est pas proposé. Seuls les produits dont Requires Shipping est sur Yes comptent : les autres n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Les poids sont convertis en kilogrammes et les dimensions en centimètres, à partir des classes de poids et de longueur des produits. Le sous-total correspond au prix des produits à expédier, après la remise du coupon, hors taxes, dans la devise par défaut de votre boutique. Les cartes cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. L'extension vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et sous-total minimum. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Chilexpress.

Pour une adresse au Chili avec une source de tarifs API, l'extension prend la région (zone) de l'adresse et la comuna du champ City, puis cherche le code de comuna Chilexpress dans la liste des comunas de cette région (API Coverage). Les accents, les espaces et les variantes d'écriture sont ignorés : Ñuñoa et Nunoa correspondent, et Santiago correspond à Santiago Centro. Un code de comuna saisi dans le champ City est aussi accepté. Ensuite, l'extension envoie à l'API Rating les codes de comuna d'origine et de destination, le poids du panier (au moins 0,1 kg), les dimensions du colis (longueur et largeur du produit le plus grand, hauteurs empilées) et le sous-total du panier en CLP comme valeur déclarée. Chilexpress renvoie ses services ; l'extension utilise le service choisi ou le moins cher, et convertit le montant en pesos dans la devise par défaut de votre boutique. Le prix est arrondi aux décimales de cette devise, puis affiché dans la devise du client avec la taxe de la Tax class sélectionnée.

Les tarifs sont mis en cache pendant 1 heure. Les listes de comunas sont mises en cache jusqu'à 7 jours, mais pas plus longtemps que ne conserve le cache d'OpenCart (1 heure par défaut). Une requête échouée est retenue pendant 5 minutes, afin qu'une API lente ou indisponible ne ralentisse pas chaque actualisation du paiement. Le délai d'attente de l'API est de 10 secondes. Si Chilexpress renvoie une erreur, aucun service avec un prix, ou si la comuna ou la région est inconnue, le client ne voit aucune erreur. La méthode est masquée en mode API seule, ou le prix fixe est utilisé. La raison est écrite dans le journal de débogage.

L'extension ne calcule que des tarifs. Elle ne crée pas d'envois ni d'ordres de transport (OT), n'imprime pas d'étiquettes, ne réserve pas d'enlèvements et ne suit pas les colis ; réservez l'envoi dans votre compte Chilexpress. Les clients ne peuvent pas choisir un bureau Chilexpress, et il n'existe pas de sélecteur de comuna : le client saisit la comuna dans le champ City standard. Les envois internationaux utilisent les prix fixes.

Sur OpenCart 4, le client clique sur Choose dans le bloc des méthodes de livraison de la page de paiement et choisit Chilexpress dans la fenêtre Shipping method options, par exemple Chilexpress - $5.49. La méthode fonctionne de la même façon que sur OpenCart 3.

Commandes

Lorsqu'une commande est passée avec Chilexpress, l'extension enregistre la façon dont son prix a été calculé. Dans Sales > Orders, la page de la commande affiche un panneau Chilexpress avec Chilexpress service (pour un tarif en direct, le service coté par Chilexpress, par exemple Express ; sinon un tiret) et Price : Live rate (Chilexpress Rating API), Fixed price ou Free shipping. Le panneau est aussi affiché lorsque la méthode est désactivée. Sur OpenCart 4, le panneau Chilexpress s'affiche au-dessus de History, et lorsqu'une commande est confirmée à nouveau au paiement ou passe à une autre méthode de livraison, le panneau suit le changement.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Chilexpress est le premier bloc de Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit, au-dessus des réglages. Collez 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: opencart-shipping-chilexpress 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 dans la configuration d'OpenCart. Retirer 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, Chilexpress n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (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 à l'administration, donc sans clé active la méthode est masquée pour tout le monde. Une fois la page Edit ouverte une fois, 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 concerné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é automatiquement à nouveau lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : 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 la licence.

Dépannage

Chilexpress n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Contrôlez Geo zone (ou Ignore shipping zones et Countries), les limites de poids et Minimum subtotal. Avec des prix fixes, vérifiez que le pays ou * Default (other countries) a une ligne. Vérifiez que les produits ont Requires Shipping sur Yes.

La livraison au Chili est gratuite alors qu'elle ne devrait pas l'être : la ligne de Country prices pour le Chili (ou la ligne par défaut) a 0 dans Price et dans les colonnes de taille. Saisissez les prix et cliquez sur Save.

Le tarif en direct n'est pas affiché, le prix fixe est utilisé : vérifiez d'abord les avertissements en haut de la page de l'extension. Sinon, activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Causes typiques : l'adresse n'a pas de région, ou il manque des régions au Chili (utilisez Add Chilean regions), une comuna que Chilexpress ne reconnaît pas (vérifiez le champ City et la région), une clé pour le mauvais produit ou environnement, ou une destination sans couverture Chilexpress.

HTTP 401 ou 403 dans le journal : la clé d'abonnement est incorrecte, inactive, ou destinée à un autre produit ou environnement. Les clés de test ne fonctionnent qu'avec Test environment activé.

Les tarifs API ne sont pas utilisés dans une boutique avec une autre devise : saisissez le CLP exchange rate.

Les tarifs API incluent-ils l'IVA ? Ils sont utilisés tels que Chilexpress les cote. Si votre boutique ajoute une taxe à la livraison et que la cotation inclut déjà l'IVA, 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 les tarifs et listes de comunas en cache.

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

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Chilexpress. 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 et listes de comunas en cache sont toujours supprimés. Si Remove data on uninstall est activé, les autres réglages et le journal de débogage sont aussi supprimés. Sinon, ils sont conservés et réutilisés lorsque vous réinstallez l'extension. Les services Chilexpress enregistrés avec les commandes ne sont jamais supprimés, et les commandes existantes gardent leur méthode et leur coût de livraison. Les régions du Chili ajoutées avec Add Chilean regions restent dans la boutique.

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 Chilexpress dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléchargé.

Chilexpress est une marque commerciale de son titulaire respectif. Cette extension n'est pas affiliée à Chilexpress et n'est pas approuvée par elle.