VibeFox Blue Express 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.

Compte Blue Express (pour les tarifs en temps réel uniquement) : les tarifs en temps réel nécessitent un compte e-commerce Blue Express et sa clé API (x-api-key). Demandez-la à Blue Express : developers.bluex.cl ou gpo.integraciones@bx.cl. Le service que vous utilisez (EX, PY ou MD) doit être activé dans votre contrat Blue Express. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de clé API.

Régions chiliennes : pour un tarif en temps réel, l'adresse de livraison doit avoir une région chilienne. Si votre boutique n'a pas les régions chiliennes, l'extension peut les ajouter pour vous (voir Configuration).

Points relais : la carte Blue Express est chargée depuis widget-pudo.blue.cl dans le navigateur du client.

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_blue_express-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_blue_express.ocmod.zip. N'installez que 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_blue_express-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 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 Blue Express et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de 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. Saisissez la clé API, le service, le code du district d'origine (par exemple SCL), le taux de change CLP si la devise de votre boutique n'est pas le CLP, et les prix fixes (par exemple CL=4500). Activez Enable/Disable pour la livraison à domicile et Pickup point option si vous voulez proposer le retrait dans les points Blue Express. Cliquez sur Save. Voir Configuration.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_blue_express.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 Blue Express, 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.

À l'installation, l'extension crée une table pour les points relais des commandes. La méthode reste désactivée tant que vous n'activez pas la livraison à domicile ou l'option de point relais et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Blue Express que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Blue Express > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les tarifs Blue Express et les données de communes mis en cache. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages. Les conditions, les prix et la classe de taxe ci-dessous s'appliquent aux deux options.

Les valeurs non valides sont refusées avec une erreur et rien n'est enregistré : un nom vide ou contenant les caractères < > ; = # { }, un nom de plus de 64 caractères, un nombre négatif ou invalide, un Min weight (kg) supérieur à Max weight (kg), un Sort order qui n'est pas un nombre entier, ou une classe de taxe ou une zone géographique inconnue.

Les avertissements sur les réglages qui masqueraient les options ou le tarif en temps réel s'affichent en haut de la page : absence de clé API, devise de la boutique autre que CLP sans taux de change, tableau de prix fixes vide, aucune zone pour le Chili, et boutique sans classe de poids en kilogrammes ni classe de longueur en centimètres dont l'unité par défaut n'est pas reconnue par l'extension (les poids sont alors lus en kg et les dimensions en cm).

Général

Enable/Disable : active ou désactive la livraison Blue Express à domicile.

Name : le nom de la méthode de livraison affiché au paiement pour la livraison à domicile. Par défaut : Blue Express. Obligatoire, 64 caractères maximum.

Tax class : la classe de taxe du coût de livraison, ou None (no tax on shipping) (par défaut). Les prix Blue Express incluent la TVA (IVA). Choisissez None si OpenCart ne doit pas ajouter de taxe en plus. Cela s'applique aux deux options.

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

Retrait dans les points Blue Express (PUDO)

Pickup point option : propose la livraison dans un point Blue Express choisi par le client, comme deuxième option à côté de la livraison à domicile. Désactivée par défaut.

Pickup point name : le nom de la méthode de livraison affiché au paiement pour le retrait dans un point Blue Express. Par défaut : Blue Express pickup point. Obligatoire, 64 caractères maximum.

API Blue Express (nécessaire pour les tarifs en temps réel)

API key : votre clé API Blue Express (en-tête x-api-key). Sans elle, seuls les prix fixes sont utilisés. Après l'enregistrement, le champ reste vide et affiche A key is saved - leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Remove the saved API key : activez l'option et enregistrez pour supprimer la clé enregistrée.

Service : le service Blue Express utilisé pour le tarif : Express (EX) (par défaut), Prioritario (PY) ou SameDay (MD). Il doit être activé dans votre contrat Blue Express.

Origin district code : le code de district Blue Express du lieu d'expédition, par exemple SCL pour Santiago (par défaut). Demandez à Blue Express en cas de doute.

CLP per 1 (your currency): l'étiquette affiche la devise par défaut de votre boutique, par exemple CLP per 1 EUR. Les prix Blue Express sont en pesos chiliens (CLP). Saisissez la valeur en CLP d'une unité de la devise par défaut de votre boutique, par exemple 1050. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés. Ignoré lorsque la devise de la boutique est le CLP.

Prix

Rate source : la manière dont le prix est calculé. Le tarif en temps réel nécessite une adresse chilienne avec région et commune (ville). Les erreurs sont inscrites dans le journal, jamais montrées au client.

Fixed prices : une ligne par pays au format CODE_PAYS=PRIX, dans la devise par défaut de la boutique, hors taxes, par exemple CL=4500 dans une boutique en CLP ou CL=4.50 dans une boutique en EUR. La virgule ou le point est accepté comme séparateur décimal. Les lignes invalides sont ignorées et listées dans un avertissement lors de l'enregistrement. Un pays sans ligne n'a pas de prix fixe ; les options lui sont donc masquées lorsque le prix fixe est nécessaire. Les prix fixes peuvent être utilisés pour n'importe quel pays.

Fixed price per : Order (par défaut) facture le prix une seule fois. Item (price x quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'au prix fixe. Le tarif de l'API est toujours pour l'envoi complet.

Conditions

Min weight (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie aucune limite (par défaut).

Max weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 100. 0 signifie aucune limite ; un champ vide signifie 100 kg.

Minimum order subtotal : n'affiche la méthode qu'à partir de ce sous-total du panier (devise de la boutique, produits à expédier, après coupon, hors taxes). Laissez le champ vide pour l'afficher toujours.

Livraison gratuite

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

Free from subtotal : le sous-total du panier (devise de la boutique, produits à expédier, après coupon, hors taxes) à partir duquel la livraison est gratuite. Aucune requête n'est alors envoyée à Blue Express. Utilisé uniquement lorsque Free shipping est activé.

Disponibilité

Geo zone : propose Blue Express 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 vérifié avec Ignore shipping zones.

Ignore shipping zones : propose les deux options dans toutes les zones géographiques. Les pays sont alors limités par la liste ci-dessous.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Utilisé uniquement avec Ignore shipping zones.

Régions chiliennes (affiché uniquement lorsque des régions chiliennes manquent dans votre boutique)

Blue Express a besoin de la région d'une adresse chilienne (RM, VS, etc.) pour le tarif en temps réel. La région est prise dans la zone de l'adresse, d'après son code ou son nom. La section indique combien de zones le Chili a dans votre boutique et quelles régions manquent (une boutique OpenCart 3.0.5 standard en a 15 sur 16, sans Ñuble). Cliquez sur Add Chilean regions pour ajouter les régions manquantes en tant que zones du Chili, avec les codes utilisés par Blue Express. Les régions que vous avez déjà, par code ou par nom, ne sont pas ajoutées une seconde fois. Rien n'est modifié tant que vous ne cliquez pas sur le bouton. Vous pouvez aussi les ajouter vous-même dans System > Localisation > Zones.

Avancé

Debug log : enregistre les requêtes et les décisions dans storage/logs/vfd_blex_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours enregistrées. La clé API et les adresses des clients ne sont jamais enregistrées. Désactivez le journal lorsque vous avez terminé. Le journal est tourné lorsqu'il atteint 5 Mo.

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

Remove data on uninstall : lorsque cette option est activée, la désinstallation de l'extension supprime les réglages, les tarifs en cache et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les points relais 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 le 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 au paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le prix de chaque option activée. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Blue Express n'est pas proposé. Avec Ignore shipping zones, c'est la liste Countries qui décide. Seuls les produits dont Requires Shipping est sur Yes comptent : les autres n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. L'extension vérifie le poids du panier et le Minimum order subtotal. Le sous-total 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 boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Blue Express.

Pour un tarif en temps réel, l'adresse doit être au Chili, avec une région et une ville (commune). L'extension demande d'abord à Blue Express de reconnaître la commune, puis demande le prix du service, du district d'origine, de la destination et des colis. Chaque produit est envoyé avec son poids et ses dimensions convertis en kg et en cm à partir de ses classes de poids et de longueur. Les produits sans poids ni taille sont envoyés comme 0,01 kg, 10 x 10 x 10 cm. La valeur déclarée est envoyée en CLP. Le prix en CLP est converti dans la devise par défaut de la boutique, arrondi à ses décimales et affiché au client dans sa devise, avec la taxe de la Tax class sélectionnée.

Les tarifs sont mis en cache pendant 1 heure et les données de communes jusqu'à 12 heures, sans dépasser la durée de vie du cache d'OpenCart (1 heure par défaut). Un appel API échoué est retenu pendant 5 minutes, et le délai d'attente est de 10 secondes, afin qu'une API lente ou indisponible ne ralentisse pas chaque actualisation du paiement. Les erreurs de l'API ne sont jamais affichées au client : l'option est masquée, ou le prix fixe est utilisé en mode de secours. La raison est inscrite dans le journal.

L'extension ne crée pas d'envois ni d'étiquettes dans Blue Express, n'attribue pas de numéros de suivi et n'affiche pas de mises à jour de suivi. Créez l'envoi dans votre compte Blue Express. Il n'existe pas de tableaux tarifaires régionaux par commune : utilisez le tarif de l'API Blue Express ou un prix fixe par pays. Les tarifs en temps réel ne fonctionnent que pour le Chili.

Sur OpenCart 4, le client clique sur Choose dans le bloc des méthodes de livraison de la page de paiement, puis choisit Blue Express ou Blue Express pickup point dans la fenêtre Shipping method options. Les options fonctionnent de la même façon que sur OpenCart 3 ; le cadre du point relais est décrit dans Points relais.

Points relais

Lorsque l'option de point relais est activée, une zone avec le bouton Choose pickup point apparaît sous Blue Express pickup point à l'étape Delivery Method du paiement OpenCart. Le bouton ouvre la carte officielle de Blue Express, où le client choisit un point. Le point choisi s'affiche avec son nom et son adresse, et le bouton devient Change pickup point. Le point est enregistré pour la session de paiement, et le tarif est recalculé avec le prix de retrait (PUDO) de Blue Express. Si le prix change, l'option affiche le nouveau prix. Si l'option n'est plus proposée pour ce point, l'étape de livraison se recharge. Tant qu'aucun point n'est choisi, l'option affiche le prix de la livraison à domicile.

Le client ne peut pas poursuivre sans point : Continue à l'étape de livraison est refusé avec Please choose a Blue Express pickup point. Cela est vérifié dans le navigateur, puis à nouveau par la boutique. Un code de point mal formé est refusé avec The selected Blue Express pickup point is not valid. Please choose it again on the map., et le choix précédent est conservé. Si l'enregistrement échoue, le client voit The pickup point could not be saved. Please try again.

Sur OpenCart 4, le client clique sur Choose dans le bloc des méthodes de livraison de la page de paiement. La fenêtre Shipping method options affiche le même cadre avec Choose pickup point sous Blue Express pickup point tant que cette option est sélectionnée. Lorsque le prix change avec le point choisi, l'option dans la fenêtre affiche le nouveau prix, et si l'option de retrait était déjà enregistrée pour le paiement, le champ de la méthode de livraison et le bloc de confirmation de la commande sont aussi mis à jour. Si l'option n'est plus proposée pour ce point, la fenêtre se ferme et la liste des méthodes de livraison est rechargée. Continue dans la fenêtre sans point est bloqué avec Please choose a Blue Express pickup point. dans le cadre, et la boutique le vérifie à nouveau. OpenCart 4 garde une seule commande pour le paiement et la met à jour à chaque confirmation ; le point relais de la commande est mis à jour avec elle, et il est supprimé lorsque la commande passe à une autre méthode de livraison.

Lorsque la commande est passée, le point est enregistré dans la commande avec son code d'agence Blue Express, son nom, son adresse et sa région. Il est aussi ajouté à la méthode de livraison de la commande après le nom de l'option de retrait, par exemple Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, afin que le client le voie dans les e-mails de commande et sur les pages de commande de son compte.

Sur la page de commande de l'administration (Sales > Orders, View), le point s'affiche dans le panneau Blue Express pickup point avec son code et sa région. Si la commande n'a pas de point, le panneau affiche Not chosen. Cliquez sur Edit pour choisir un autre point avec Choose on the Blue Express map ou pour saisir à la main l'Agency code, le Name et l'Address, puis cliquez sur Save pickup point. Le texte de la méthode de livraison de la commande est aussi mis à jour, et le changement est ajouté à l'historique de la commande sans notifier le client (Blue Express pickup point changed: ancien code -> nouveau code). Modifier le point nécessite seulement l'autorisation de modifier les commandes, et non l'accès aux réglages de l'extension. Les commandes existantes conservent les données de leur point relais.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Blue Express est le premier bloc de Extensions > Extensions > Shipping > VibeFox Blue Express > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau l'état, 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-blue-express et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation de modification pour l'extension peuvent changer 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 état connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de 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, Blue Express n'est pas affiché aux clients au moment du 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é. 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 son statut.

Dépannage

Blue Express n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable (ou Pickup point option) est activé. Lisez les avertissements en haut de la page de l'extension. Vérifiez Geo zone (ou Ignore shipping zones et Countries), les limites de poids, le Minimum order subtotal, et que Fixed prices comporte une ligne pour le pays si vous utilisez les prix fixes ou la solution de secours. Vérifiez que les produits ont Requires Shipping sur Yes.

Les tarifs en temps réel n'apparaissent pas : avec Blue Express API only, les options sont masquées lorsqu'il n'y a pas de tarif. Activez Debug log, rechargez le paiement et regardez le champ Log sur la page de l'extension. Causes fréquentes : pas de clé API, devise de la boutique autre que CLP sans taux de change, région ou commune manquante dans l'adresse, commune non reconnue par Blue Express, ou erreur de l'API (par exemple HTTP 401 ou 403 lorsque la clé API est rejetée). Avec Blue Express API, fixed price if the API gives no rate, les clients continuent de recevoir le prix fixe pendant que vous corrigez le problème.

Les adresses chiliennes n'ont pas de région : la page affiche un avertissement sur les régions manquantes. Cliquez sur Add Chilean regions sur la page de l'extension. Les clients dont les adresses ont été enregistrées sans région doivent modifier l'adresse et choisir la région.

La taxe s'ajoute au prix Blue Express : les prix Blue Express incluent la TVA (IVA). Réglez Tax class sur None (no tax on shipping).

La carte ne s'ouvre pas : la carte est chargée depuis widget-pudo.blue.cl dans le navigateur du client ; cette adresse doit donc être accessible et ne pas être bloquée sur votre site.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs et les données de communes mis en cache.

La page affiche « Warning: You do not have permission to modify VibeFox Blue Express! » : votre groupe d'utilisateurs administrateurs n'a peut-être que le droit de consultation des réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_blue_express (OpenCart 3) ou extension/vfd_blue_express/shipping/vfd_blue_express (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : les adresses de l'API Blue Express et de la carte peuvent être remplacées par les réglages vfd_blex_api_url et vfd_blex_widget_url (pour les tests) ; ils n'ont 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 Blue Express. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours l'état de la méthode, 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 Blue Express et le journal sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lorsque vous réinstallez l'extension. Les points relais enregistrés dans les commandes ne sont jamais supprimés, et le texte de la méthode de livraison des commandes existantes conserve le point relais.

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

Blue Express est une marque appartenant à son titulaire respectif. Cette extension n'est ni affiliée à Blue Express ni approuvée par Blue Express.