VibeFox Coordinadora 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 Coordinadora (uniquement pour les tarifs en temps réel) : les tarifs en temps réel proviennent du Cotizador de Coordinadora par l'intermédiaire du service Coordinadora WooCommerce, le même que celui qu'utilise l'extension officielle de Coordinadora. Coordinadora délivre la clé API aux clients disposant d'un accord commercial actif. Renseignez-vous auprès de votre responsable de compte Coordinadora ou consultez wc.coordinadora.com. Vous avez aussi besoin du code DANE à 8 chiffres de la ville d'expédition. Sans clé, le transporteur fonctionne uniquement avec des prix fixes.

Produits : pour un tarif en temps réel, chaque produit du panier doit avoir un poids et des dimensions (largeur, hauteur, profondeur).

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Coordinadora dans la liste des modules et 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. Saisissez la clé API, le code DANE de la ville d'expédition 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 comme solution de secours (voir Configuration). Cliquez sur Save.

5. Vérifiez que la Colombie est active dans votre boutique et que vos produits ont un poids et des dimensions.

À l'installation, le module crée le transporteur Coordinadora avec le texte de délai de livraison Courier delivery in Colombia. Le transporteur est assigné à 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. 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 Coordinadora > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs Coordinadora. Les nombres peuvent être saisis avec un point ou une virgule (9,99 = 9.99).

La page refuse l'enregistrement et affiche une erreur lorsqu'un nombre ou un prix du tableau est invalide ou négatif, que COP per 1 unit of store currency vaut 0, que Min weight est supérieur à Max weight, ou que Name dépasse 64 caractères. Rien n'est enregistré tant que vous n'avez pas corrigé.

La page affiche des avertissements en haut lorsque les tarifs en temps réel ne peuvent pas fonctionner ou que le transporteur serait masqué : 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, ou il n'existe pas de prix fixe pour la Colombie (ou *). Sans clé API et sans ce prix fixe, le transporteur n'est jamais affiché pour les adresses colombiennes. Un avertissement apparaît aussi lorsque l'unité de poids ou de dimension de la boutique, dans International > Localization (Local units), n'est pas reconnue par le module ; les poids des produits sont alors lus en kg et les dimensions en cm.

Général

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

Name : le nom du transporteur affiché au client lors du paiement. Par défaut : Coordinadora. Obligatoire.

Tax : la règle de taxe du transporteur, ou No tax. Avec une règle, PrestaShop ajoute la taxe de livraison au tarif. Choisissez No tax si vos prix ou le tarif Coordinadora incluent déjà la taxe.

Tarifs Coordinadora en temps réel

Les tarifs en temps réel sont demandés pour les destinations en Colombie. Laissez la clé vide pour utiliser uniquement les prix fixes.

API key : votre clé API Coordinadora WooCommerce, fournie par Coordinadora. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement 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é ; le transporteur n'utilise alors que des prix fixes.

Origin city (DANE code) : le code DANE à 8 chiffres de la ville d'expédition, 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. Si vous le laissez vide, les tarifs en temps réel 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é API, pour les destinations hors Colombie, et en secours lorsqu'un tarif en temps réel n'est pas disponible)

Prices by country : un tableau de pays avec une colonne Price et des prix optionnels 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 1–2 kg, M 2–3 kg, L 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 et sur la croix pour en supprimer une. 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 Price à 0 et sans prix par taille donne la livraison gratuite.

Fixed price per : Order 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 Coordinadora en temps réel couvre toujours la commande entière.

Conditions

Min weight : masque le transporteur en dessous de ce poids de panier, en kg. 0 signifie aucune limite.

Max weight : masque le transporteur au-dessus de ce poids de panier, en kg. Par défaut : 25 (utilisé aussi lorsque le champ est vide). 0 signifie aucune limite. Il ne peut pas être inférieur à Min weight.

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

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

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

Countries : propose Coordinadora uniquement pour ces pays de destination. Seuls les pays actifs sont listés. Laissez vide pour autoriser tous les pays des zones du transporteur.

Avancé

Debug log : écrit les calculs de tarifs dans logs/vfd_crd_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API et les réglages incomplets sont toujours journalisés, même lorsque cette option est désactivée. La clé API et les adresses des clients ne sont jamais journalisées.

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 Coordinadora, le transporteur, les tarifs en cache et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix Coordinadora. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le tarif. Le module 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 de 0 et aucune requête n'est envoyée à Coordinadora.

Pour une adresse en Colombie avec une clé API, le module trouve le code DANE de la ville de destination dans cet ordre : un code DANE dans le champ ville (les modules de paiement pour les départements et villes colombiens l'écrivent, 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 des plus grandes villes. Si l'adresse comporte un département (état), une ville de la liste est vérifiée par rapport à lui. Les accents et la casse sont ignorés.

Ensuite, le module 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 produit avant taxes et avant remises du panier. Les unités de la boutique sont converties automatiquement. Coordinadora renvoie le prix en COP ; le module le convertit dans votre devise par défaut, puis dans la devise du panier du client. Chaque tarif est mis 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 temps réel n'est pas disponible (erreur de l'API, ville inconnue, produit sans poids ni dimensions, réglages manquants), le prix fixe est utilisé. S'il n'y en a pas, le transporteur est masqué pour ce panier. Les détails d'erreur vont dans le journal de débogage, jamais au 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 calcule que les tarifs. Il ne crée pas d'envois ni de guías (guías), n'imprime pas d'étiquettes, ne réserve pas d'enlèvements (recogidas), ne suit pas les colis, n'encaisse pas de contre-remboursement (recaudo) et ne propose pas de points relais Droop ; utilisez le portail Coordinadora pour cela. Les destinations internationales utilisent les prix fixes.

Clé de licence

Le module 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 Modules > Module Manager > VibeFox Coordinadora > Configure, 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 jusqu'à laquelle la licence est active 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. Sous ces boutons se trouvent la ligne Product: presta-shipping-coordinadora 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 : celui 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Coordinadora n'est pas affiché aux clients lors du paiement, et aucun tarif n'est calculé. La vitrine 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 moment du paiement. Un rappel apparaît dans Modules > Module Manager, sur 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é à nouveau 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 la licence.

Dépannage

Coordinadora n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Coordinadora est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et son groupe de clients. Contrôlez Countries, les limites de poids et Minimum order subtotal. Sans tarif en temps réel, un prix fixe pour le pays ou pour * doit exister. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le tarif en temps réel n'est pas affiché, seul le prix fixe l'est : activez Debug log, rechargez la page de paiement et consultez le champ Log sur la page du module. Causes habituelles : la ville de destination n'est pas reconnue, un produit n'a pas de poids ni 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 pour les départements et villes colombiens qui écrit le code DANE dans le champ ville. Les développeurs peuvent associer d'autres villes avec les hooks du module actionVfdCrdDaneCities et actionVfdCrdDestinationDane, ou modifier l'adresse de l'API avec actionVfdCrdApiUrl.

Le tarif inclut-il la taxe ? Le tarif est celui que cote Coordinadora. Avec une règle Tax, PrestaShop ajoute la taxe de livraison ; 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 du module. Cela vide le cache des tarifs.

La page indique que le transporteur Coordinadora est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Coordinadora et choisissez Uninstall. La clé de licence, le statut de la licence et les tarifs en cache sont toujours supprimés. 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, ou un Reset, rend au transporteur enregistré le statut qu'il avait auparavant : un transporteur que vous aviez désactivé reste désactivé.

Coordinadora est une marque de son propriétaire respectif. Ce module n'est ni affilié à Coordinadora ni approuvé par elle.