VibeFox Coordinadora 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 Coordinadora (uniquement pour les tarifs en direct) : les tarifs en direct proviennent du Cotizador de Coordinadora, via le service WooCommerce de Coordinadora, celui qu'utilise le plugin officiel de Coordinadora. Coordinadora délivre la clé d'API aux clients disposant d'un accord commercial actif. Demandez à votre gestionnaire de compte Coordinadora ou consultez wc.coordinadora.com. Vous avez aussi besoin du code DANE à 8 chiffres de la ville d'où vous expédiez. Sans clé, la méthode fonctionne uniquement avec des prix fixes.

Produits : pour un tarif en direct, chaque produit du panier doit avoir un poids et trois dimensions (longueur, largeur, hauteur).

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_coordinadora-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_coordinadora.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_coordinadora-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 Coordinadora 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 le champ License key du bloc de licence, en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Saisissez la clé d'API, le code DANE de la ville d'origine et, si votre devise par défaut n'est pas le COP, le taux de change en COP. Ajoutez au moins un prix fixe pour la Colombie en guise de repli (voir Configuration). Activez Enable Coordinadora et cliquez sur Save.

6. Assurez-vous que vos produits ont un poids et des dimensions.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_coordinadora.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 à côté sur Install (le bouton vert +).

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Coordinadora, 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 à 6 pour OpenCart 3. La page des 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 Coordinadora et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Coordinadora 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 Coordinadora > Edit. Les réglages s'appliquent à toutes les zones géographiques ; vous pouvez limiter la méthode à une zone géographique et à des pays dans Conditions. 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 Coordinadora rates were cleared. Les nombres peuvent être saisis avec un point ou une virgule (9,99 = 9.99). Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Rien n'est enregistré et la page affiche les erreurs si Name est vide ou dépasse 64 caractères, si un nombre ou un prix du tableau est invalide ou négatif, si COP per 1 unit of store currency vaut 0, si Min weight (kg) est supérieur à Max weight (kg), ou si Sort order n'est pas un nombre entier.

La page affiche des avertissements au-dessus des réglages lorsque les tarifs en direct ne peuvent pas fonctionner ou que la méthode serait masquée : Origin city (DANE code) est vide ou invalide ; COP per 1 unit of store currency manque alors que votre devise par défaut n'est pas le COP ; il n'existe pas de prix fixe pour la Colombie (ni pour *) ; il n'y a ni clé d'API ni prix fixe pour la Colombie, si bien que la méthode n'est jamais affichée pour les adresses colombiennes. Un avertissement apparaît aussi lorsque la boutique n'a pas de classe de poids en kg ou de classe de longueur en cm et que son unité par défaut n'est pas reconnue par l'extension ; les poids des produits 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 avertissements sont mis à jour après chaque enregistrement.

Général

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

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

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

Tarifs en direct de Coordinadora

Les tarifs en direct sont demandés pour les destinations en Colombie. Laissez la clé vide pour n'utiliser que des prix fixes.

API key : votre clé d'API WooCommerce Coordinadora. 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é n'est jamais écrite dans le journal.

Remove the saved API key : affiché uniquement lorsqu'une clé est enregistrée. Activez-le et cliquez sur Save pour supprimer la clé ; la méthode n'utilise alors que des prix fixes.

Origin city (DANE code) : le code DANE à 8 chiffres de la ville d'où vous expédiez, par exemple 11001000 Bogotá, 05001000 Medellín, 76001000 Cali ou 08001000 Barranquilla. Un code de municipalité à 5 chiffres est aussi accepté et complété à 8 chiffres.

COP per 1 unit of store currency : Coordinadora cote en pesos colombiens. Si votre devise par défaut n'est pas le COP, indiquez combien de COP valent 1 unité de votre devise, par exemple 4300. Ce taux sert aussi à transmettre la valeur déclarée en COP. Laissé vide, les tarifs en direct ne sont pas utilisés. Le taux doit être supérieur à 0. Si votre devise par défaut est le COP, laissez-le vide.

Prix fixes (utilisés en l'absence de clé d'API, pour les destinations hors Colombie, et en repli lorsqu'un tarif en direct n'est pas disponible)

Prices by country : une liste de pays avec une colonne Price et des prix facultatifs par taille de colis, dans votre devise par défaut, hors taxes. La taille dépend du poids du panier : XS jusqu'à 1 kg, S de 1 à 2 kg, M de 2 à 3 kg, L de 3 à 5 kg, XL au-delà de 5 kg. Price est utilisé lorsque la colonne de taille vaut 0 ou est vide. Cliquez sur Add country pour ajouter une ligne ; une nouvelle ligne commence avec la Colombie. Le pays * All other countries s'applique aux pays sans ligne propre. Un pays sans ligne (et sans *) n'a pas de prix fixe. Une ligne avec un Price de 0 et sans prix par taille donne une livraison gratuite.

Fixed price per : Order (par défaut) facture le prix une seule fois. Item (price × quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'aux prix fixes ; un tarif en direct de Coordinadora couvre toujours la commande entière.

Conditions

Min weight (kg) : masque la méthode en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Max weight (kg) : masque la méthode au-delà de ce poids de panier. Par défaut : 25 (utilisé aussi lorsque le champ est vide). 0 signifie aucune limite.

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

Free shipping : active la livraison gratuite à partir du sous-total ci-dessous.

Free shipping from : le sous-total (après le coupon, avant 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.

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 de livraison au tarif. Choisissez No tax si vos prix ou le tarif de Coordinadora incluent déjà la taxe.

Geo zone : proposez Coordinadora 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.

Countries : proposez Coordinadora uniquement pour ces pays de destination. Laissez vide pour autoriser tous les pays. Cette limite s'applique en complément de Geo zone.

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_crd_debug.log.php (sur OpenCart 4, system/storage/logs/vfd_crd_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API et les réglages incomplets sont toujours journalisés, même si cette option est désactivée. La clé d'API et les adresses des clients ne sont jamais journalisées. Quand le fichier atteint 5 Mo, il est déplacé vers vfd_crd_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 les réglages Coordinadora, les tarifs en cache et les journaux. Si désactivé (par défaut), tout est conservé pour une réinstallation.

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 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é d'API enregistrée est conservée.

Fonctionnement au paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le prix Coordinadora. Si une Geo zone est définie et que l'adresse est hors de celle-ci, Coordinadora 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 tarif. Le sous-total correspond au 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. L'extension vérifie d'abord les conditions : pays autorisés, poids du panier et sous-total minimum de la commande. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Coordinadora.

Pour une adresse en Colombie avec une clé d'API, l'extension recherche le code DANE de la ville de destination dans cet ordre : un code DANE dans le champ de ville (les modules de paiement colombiens pour les départements et les villes l'inscrivent, par exemple MEDELLIN (ANT) (05001000)), un code postal à 8 chiffres, ou la liste intégrée des chefs-lieux de département et d'une quarantaine de plus grandes villes. Si l'adresse a une région (département), une ville de la liste est vérifiée par rapport à celle-ci. Les accents et la casse sont ignorés.

Ensuite, l'extension envoie à Coordinadora le code DANE de destination et chaque produit avec la ville d'origine, son poids (kg), ses dimensions (cm), sa quantité et sa valeur déclarée (COP). La valeur déclarée est le total de la ligne du produit avant taxes, après la remise du coupon. Les classes de poids et de longueur des produits sont converties automatiquement. Coordinadora renvoie le prix en COP ; l'extension le convertit dans votre devise par défaut, l'arrondit aux décimales de cette devise et l'affiche dans la devise du client avec la taxe de la Tax class sélectionnée. Chaque cotation est mise en cache pendant 1 heure. Une requête échouée est retenue pendant 10 minutes, afin qu'une panne de Coordinadora ne ralentisse jamais chaque actualisation du paiement. Le délai d'attente de l'API est de 10 secondes.

Lorsqu'un tarif en direct n'est pas disponible (erreur de l'API, ville inconnue, produit sans poids ou dimensions, réglages incomplets), le prix fixe est utilisé. S'il n'en existe pas, la méthode est masquée pour ce panier. Les détails des erreurs vont dans le journal de débogage, jamais au client.

L'extension ne calcule que des tarifs. Elle ne crée pas d'envois ni de guías, n'imprime pas d'étiquettes, ne réserve pas d'enlèvements (recogidas), ne suit pas les colis, n'encaisse pas de paiement à la livraison (recaudo) et ne propose pas de points de retrait Droop ; utilisez le portail de Coordinadora pour cela. Elle n'ajoute rien aux commandes : la commande affiche le nom de la méthode et le coût de livraison comme toute autre méthode de livraison OpenCart. Les destinations internationales 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 Coordinadora dans la fenêtre Shipping method options. La méthode fonctionne de la même façon 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 Coordinadora est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox Coordinadora > 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 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: opencart-shipping-coordinadora 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 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 indiquée 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, Coordinadora n'est pas affichée 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), ce qui vous permet de configurer et de 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 ; sans clé active, la méthode est donc masquée 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 concernées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance 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 la licence.

Dépannage

Coordinadora n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Coordinadora est activé. Consultez les avertissements en haut de la page de l'extension, Geo zone, Countries, les limites de poids et Minimum order subtotal. Sans tarif en direct, un prix fixe doit exister pour le pays ou pour *. Vérifiez que les produits ont Requires Shipping sur Yes.

Le tarif en direct n'est pas affiché, seul le prix fixe l'est : activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Raisons habituelles : la ville de destination n'est pas reconnue, un produit n'a pas de poids ou de dimensions, le code DANE d'origine ou le taux de change en COP manque, ou Coordinadora a renvoyé une erreur.

La ville de destination n'est pas reconnue : installez un module de paiement colombien pour les départements et les villes qui inscrit le code DANE dans le champ de ville. Les développeurs peuvent ajouter d'autres villes ou modifier l'adresse de l'API grâce aux événements OpenCart vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane et vfd_coordinadora/api_url ; l'adresse de l'API peut aussi être remplacée par le réglage vfd_crd_api_url (pour les tests), qui n'a pas de champ sur la page de réglages.

Le tarif inclut-il la taxe ? Le tarif est celui que cote Coordinadora. Avec une Tax class, OpenCart ajoute la taxe de livraison au tarif ; choisissez No tax si le tarif l'inclut déjà.

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

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Coordinadora. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Coordinadora, Sort order, Tax class et Geo zone. Les cotations en cache sont toujours supprimées. Si Remove data on uninstall est activé, les réglages Coordinadora et le journal sont aussi supprimés. Sinon, les autres réglages sont conservés et réutilisés lorsque vous réinstallez l'extension. Les commandes existantes conservent leur méthode 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 Coordinadora dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléversé.

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