VibeFox Coordinadora for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Clé API Coordinadora (uniquement pour les tarifs en temps réel) : les tarifs en temps réel proviennent du Cotizador de Coordinadora via le service WooCommerce de Coordinadora, le même que celui qu'utilise l'extension officielle de Coordinadora. Coordinadora délivre la clé API aux clients ayant un accord commercial actif. Demandez à votre responsable de compte Coordinadora ou consultez wc.coordinadora.com. Il vous faut aussi le code DANE à 8 chiffres de la ville d'expédition. Sans clé, le mode de livraison ne fonctionne qu'avec des prix fixes.

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

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

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_coordinadora dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Coordinadora, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page, puis cliquez sur Activate.

5. Saisissez la clé API, le code DANE de la ville d'expédition et, si la devise de votre boutique n'est pas le COP, le taux de change en COP. Ajoutez au moins un prix fixe pour la Colombie comme solution de repli (voir Configuration).

6. Ajoutez VibeFox Coordinadora à une zone de livraison couvrant la Colombie dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez des pays.

7. Vérifiez que vos produits ont un poids et des dimensions.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Coordinadora. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez le mode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone) : le nom du mode de livraison affiché au client pour cette zone. Laissez vide pour utiliser le Name général.

La page des réglages affiche des avertissements en haut lorsque les tarifs en temps réel ne peuvent pas fonctionner ou que le mode serait masqué : code DANE d'origine manquant ou invalide, taux de change COP manquant, ou aucun prix fixe pour la Colombie. À chaque enregistrement des réglages, les tarifs en cache sont effacés. Les nombres peuvent être saisis avec un point ou une virgule (9,99 = 9.99).

Général

Enable/Disable : active ou désactive Coordinadora dans toutes les zones à la fois.

Name : le nom du mode de livraison affiché au client à la caisse. Par défaut : Coordinadora. Le Title d'une zone le remplace.

Tax status : Taxable ajoute la taxe de livraison WooCommerce au tarif, None ne l'ajoute pas. Choisissez None 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 n'utiliser que les prix fixes.

API key : votre clé API WooCommerce Coordinadora. Elle n'est jamais écrite dans le journal.

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 la devise de votre boutique 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 temps réel ne sont pas utilisés. Si la devise de votre boutique est le COP, laissez-le vide.

Prix fixes (utilisés en l'absence de clé API, pour les destinations hors Colombie et en solution de repli 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 facultatifs par taille de colis, dans la devise de votre boutique. 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 une 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 concerne que les prix fixes ; un tarif Coordinadora en temps réel couvre toujours la commande entière.

Conditions

Min weight (kg) : masque le mode en dessous de ce poids du panier. 0 signifie sans limite.

Max weight (kg) : masque le mode au-dessus de ce poids du panier. Par défaut : 25. 0 signifie sans limite.

Minimum order subtotal : n'affiche le mode que si le sous-total du panier atteint au moins ce montant. Laissez vide pour l'afficher toujours.

Excluded shipping classes : masque le mode si un article du panier appartient à l'une de ces classes d'expédition WooCommerce.

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

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

Disponibilité sans zones de livraison

Ignore shipping zones : propose le mode pour les pays indiqués ci-dessous, même s'il n'est pas ajouté à une zone de livraison.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels la boutique livre. Ce champ n'est utilisé que si Ignore shipping zones est activé.

Avancé

Debug log : consigne les calculs de tarifs dans WooCommerce > Status > Logs, source vfd-coordinadora. Les erreurs de l'API sont toujours consignées, même lorsque cette option est désactivée. La clé API et les adresses des clients ne sont jamais consignées.

Remove data on uninstall : lorsque l'option est activée, supprimer l'extension efface ses réglages, ses méthodes de zone et les tarifs en cache. La désactivation ne supprime jamais de données.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, sous-total minimum de la commande et classes de livraison exclues. Si la livraison gratuite s'applique, le client obtient un tarif gratuit et aucune requête n'est envoyée à Coordinadora.

Pour une adresse en Colombie avec une clé API, l'extension recherche le code DANE de la ville de destination dans cet ordre : un code DANE dans le champ ville (les extensions de départements et villes colombiens pour le paiement 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. Une ville de la liste est vérifiée par rapport au département sélectionné. Les accents et la casse sont ignorés.

L'extension envoie ensuite à 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). Les unités de la boutique sont converties automatiquement. Coordinadora renvoie le prix en COP, et l'extension le convertit dans la devise de votre boutique. Chaque tarif est mis en cache pendant 1 heure. Une requête échouée est mémorisée pendant 10 minutes, afin qu'une panne de Coordinadora ne ralentisse jamais chaque actualisation de la page de 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 ou dimensions, réglages manquants), le prix fixe est utilisé. S'il n'en existe pas, le mode est masqué. Les détails des erreurs sont consignés dans le journal WooCommerce, jamais affichés au client.

Le mode fonctionne sur le paiement classique ainsi que sur les blocs Panier et Paiement. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

L'extension calcule uniquement des tarifs. Elle ne crée ni envois ni 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 paiement à la livraison (recaudo) et ne propose pas de points relais Droop ; pour cela, utilisez le portail Coordinadora. Elle ne propose pas de livraison le jour même, et les destinations internationales utilisent les prix fixes.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Coordinadora. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site 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é aux clients sur la page de paiement. Les gestionnaires de la boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. 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. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Coordinadora n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode est ajouté à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, Minimum order subtotal et Excluded shipping classes. Sans tarif en temps réel, un prix fixe doit exister pour le pays ou pour *.

Le tarif en temps réel n'apparaît pas, seul le prix fixe s'affiche : activez Debug log, rechargez la page de paiement et ouvrez WooCommerce > Status > Logs, source vfd-coordinadora. Causes fréquentes : 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 COP est manquant, ou Coordinadora a renvoyé une erreur.

La ville de destination n'est pas reconnue : installez une extension de départements et villes colombiens pour le paiement qui écrit le code DANE dans le champ ville. Les développeurs peuvent associer d'autres villes avec les filtres vfd_crd_dane_cities et vfd_crd_destination_dane.

Le tarif inclut-il la taxe ? Le tarif est celui que Coordinadora calcule. Avec Tax status réglé sur Taxable, WooCommerce ajoute la taxe de livraison ; choisissez None si le tarif l'inclut déjà.

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs en cache.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net, puis cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier état connu.

Désinstallation

La désactivation de l'extension conserve tous les réglages ; elle efface seulement les tarifs en cache. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence, l'état de licence de cette extension et les tarifs en cache sont toujours supprimés. Les réglages et les méthodes de zone ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs lignes de livraison.

Coordinadora est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à Coordinadora ni approuvée par elle.