VibeFox Servientrega for WooCommerce — Aide
Prérequis
WordPress: 5.8 ou ultérieur.
WooCommerce: 5.0 ou ultérieur, installé et activé. Le plugin refuse de s'activer sans lui.
PHP: 8.0 ou ultérieur.
Compte Servientrega (pour les tarifs en temps réel uniquement): les tarifs en temps réel utilisent le Cotizador Corporativo de Servientrega (API de devis corporatifs). Vous avez besoin d'un compte entreprise (crédit) Servientrega donnant accès à celui-ci. Trois valeurs sont nécessaires : l'utilisateur, le mot de passe et le code de facturation (código de facturación, qui commence généralement par SER). Ce sont vos identifiants SISCLINET, délivrés par votre conseiller commercial Servientrega. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de compte Servientrega.
Accès serveur (pour les tarifs en temps réel uniquement): votre serveur doit pouvoir joindre web.servientrega.com en HTTP sur le port 8058 (API de devis) et sur le port 8081 (service web de chiffrement des mots de passe).
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 du plugin et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier vfd_servientrega dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Servientrega, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Pour les tarifs en temps réel, saisissez l'utilisateur, le mot de passe et le code de facturation, choisissez le produit Servientrega, saisissez le code DANE d'origine et, si la devise de votre boutique n'est pas le COP, le taux de conversion de devise (voir Configuration).
6. Vous pouvez aussi ajouter des tarifs fixes par pays et par poids ainsi qu'un coût de repli.
7. Ajoutez VibeFox Servientrega à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Servientrega. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :
Title (zone): le nom que voient les clients pour cette zone. Laissez vide pour utiliser le Method title global.
À chaque enregistrement des réglages, les devis Servientrega mis en cache et le jeton de connexion sont effacés. Si les tarifs en temps réel ne peuvent pas fonctionner avec les réglages enregistrés, un avertissement au-dessus des réglages indique la raison : utilisateur, mot de passe ou code de facturation manquant, taux de conversion manquant ou code DANE d'origine manquant.
Général
Enable/Disable: active ou désactive la méthode dans toutes les zones à la fois.
Method title: le nom de la méthode de livraison affiché dans le panier et au moment du paiement. Une zone peut le remplacer. Par défaut : Servientrega.
API Servientrega (tarifs en temps réel pour la Colombie) (facultatif ; sans identifiants, seuls les tarifs fixes sont utilisés)
User (login): votre utilisateur Servientrega / SISCLINET.
Password: votre mot de passe Servientrega / SISCLINET, tel que vous le saisissez. Le plugin le fait chiffrer par le service web de Servientrega avant la connexion, comme le fait le client officiel de Servientrega.
Billing code: le código de facturación de votre compte Servientrega, affiché dans SISCLINET. Il commence généralement par SER.
Les trois champs sont nécessaires pour les tarifs en temps réel. Les tarifs en temps réel ne sont demandés que pour les destinations en Colombie. Les autres pays utilisent les tarifs fixes.
Servientrega product: le service de votre contrat Servientrega qui est coté.
Le poids facturé est le plus élevé entre le poids réel et le poids volumétrique.
Currency conversion rate: Servientrega établit ses tarifs en COP. Si la devise de votre boutique n'est pas le COP, saisissez la valeur de 1 COP dans la devise de votre boutique, par exemple 0.00023. La valeur déclarée du colis est convertie en COP de la même façon. Laissez vide si la devise de votre boutique est le COP. Si votre boutique utilise une autre devise et que ce champ est vide, les tarifs en temps réel ne sont pas utilisés et les tarifs fixes s'appliquent. Le plugin ne récupère pas les taux de change. Le point et la virgule sont tous deux acceptés comme séparateur décimal.
Expédition depuis (utilisé pour les tarifs en temps réel)
Origin city (DANE code): le code DANE à 8 chiffres de la municipalité d'expédition, par exemple 11001000 Bogotá, 05001000 Medellín, 76001000 Cali ou 08001000 Barranquilla. Un code de municipalité à 5 chiffres est aussi accepté. Lorsqu'il est vide et que l'adresse de votre boutique dans WooCommerce > Settings > General est en Colombie, la municipalité de l'adresse de la boutique est utilisée.
Tarifs fixes (utilisés lorsqu'il n'y a pas de tarif en temps réel : pas d'identifiants, destination hors Colombie, municipalité inconnue, taux de conversion manquant, ou erreur de l'API ou absence de couverture pour la route)
Price per country: un tableau de pays et de prix dans la devise de votre boutique. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Price s'applique à tout poids. Les colonnes de poids XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg et XL >5 kg remplacent Price pour ce poids lorsqu'elles sont supérieures à 0. La ligne * Default s'applique à tous les pays qui n'ont pas leur propre ligne.
Fallback cost: utilisé lorsqu'il n'y a pas de tarif en temps réel et qu'aucune ligne du tableau ne correspond. Laissez vide pour masquer la méthode dans ce cas.
Fixed price applies: mode de facturation des tarifs fixes.
Les tarifs en temps réel de Servientrega s'appliquent toujours par envoi.
Conditions
Minimum weight (kg): masque la méthode lorsque le panier pèse moins. 0 signifie pas de limite.
Maximum weight (kg): masque la méthode lorsque le panier pèse plus. Par défaut : 50. 0 signifie pas de limite.
Minimum order amount: n'affiche la méthode que lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.
Free shipping from: la livraison est gratuite lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Cela ne s'applique que lorsque la méthode a un prix : un prix du tableau ou le coût de repli (aucune requête n'est alors envoyée à Servientrega), ou un tarif en temps réel. Laissez vide pour ne jamais proposer la livraison gratuite.
Excluded shipping classes: masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.
Tax status: Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas. Les devis Servientrega (ValorTotal) incluent déjà les frais du transporteur. Choisissez None si vous ne voulez pas ajouter de taxe en plus.
Disponibilité sans zones de livraison
Ignore shipping zones: propose Servientrega pour les pays indiqués ci-dessous, même si la méthode n'est ajoutée à aucune zone de livraison.
Countries: les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous expédiez. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.
Avancé
Debug log: écrit les calculs de tarifs et les erreurs de l'API dans le journal WooCommerce : WooCommerce > Status > Logs, source vfd_servientrega. Les identifiants, les jetons et les adresses des clients ne sont pas journalisés. Désactivez le journal lorsque vous avez terminé.
Remove data on uninstall: lorsqu'elle est activée, la suppression du plugin efface tous les réglages Servientrega, les méthodes de zone et les devis en cache. La désactivation du plugin ne supprime jamais rien.
Fonctionnement au moment du paiement
Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif au plugin. Le plugin vérifie d'abord les conditions : pays de livraison, poids du panier, montant minimum de commande et classes d'expédition exclues. Il cherche ensuite un prix : le tarif en temps réel de Servientrega, puis le tableau de tarifs fixes, puis le coût de repli. S'il n'y a pas de prix, la méthode est masquée. Si la livraison gratuite s'applique, la méthode est affichée avec un prix de 0.
Pour une destination en Colombie avec des identifiants configurés, le plugin trouve le code DANE de la municipalité du client. Il utilise un code DANE saisi comme code postal ou dans le champ ville, ou fait correspondre le département et la ville avec le tableau intégré d'environ 1 130 municipalités. Les accents et « D.C. » sont ignorés. Un nom de ville qui n'existe que dans un seul département est trouvé même sans le département.
Le plugin envoie ensuite à Servientrega un seul colis par commande : le poids total converti de l'unité de votre boutique en kg, et une boîte avec la longueur et la largeur du plus grand article ainsi que le volume total de tous les articles, converti en cm. Les produits sans dimensions comptent pour 10 × 10 × 10 cm. La valeur déclarée est le sous-total du panier converti en COP, avec un minimum de 6 000 COP. Servientrega renvoie le total en COP, et le plugin le convertit dans la devise de votre boutique.
Le jeton de connexion est conservé jusqu'à son expiration, au maximum 4 jours. Un jeton rejeté est renouvelé automatiquement une fois. Chaque devis est mis en cache pendant 1 heure par route et par colis, de sorte que le même panier ne déclenche pas une nouvelle requête. Une requête échouée (chiffrement, connexion ou devis) est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Servientrega à chaque actualisation. Le délai d'attente est de 10 secondes par requête.
S'il n'y a pas de tarif en temps réel, le prix provient du tableau de tarifs fixes, puis du Fallback cost. Si aucun ne s'applique, la méthode est masquée. Le client ne voit jamais d'erreur de l'API. La raison est écrite dans le journal de débogage.
La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS). Des traductions espagnoles (Colombie, Espagne) sont incluses.
Le plugin ne calcule que des tarifs. Il ne crée ni guides (guías), ni étiquettes ou autocollants, ne demande pas d'enlèvements, ne suit ni n'annule les envois, et ne permet pas aux clients de choisir un bureau Servientrega (Centro de Soluciones). Créez la guía dans SISCLINET ou dans votre portail Servientrega. Le paiement à la livraison (logística de recaudo) n'est pas proposé. Les devis en temps réel ne concernent que les envois nationaux à l'intérieur de la Colombie. L'Équateur, le Pérou, le Panama et les envois internationaux utilisent les tarifs fixes.
Clé de licence
Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Servientrega. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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, Servientrega n'est pas affiché aux clients au moment du paiement. Les gestionnaires de boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin 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, le plugin continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Servientrega n'apparaît pas au moment du paiement: vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à 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 amount et Excluded shipping classes. Sans tarif en temps réel, vérifiez que le pays ou * Default a un prix, ou que Fallback cost est défini.
Les tarifs en temps réel n'apparaissent pas: activez le Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd_servientrega. Causes fréquentes : taux de conversion manquant (la devise de la boutique n'est pas le COP), absence de code DANE d'origine, département ou ville du client non saisi ou non reconnu comme municipalité connue, identifiants incorrects ou absence de couverture pour la route. Les tarifs fixes couvrent ces cas si vous les avez définis.
La connexion échoue: vérifiez l'utilisateur, le mot de passe et le code de facturation auprès de votre conseiller commercial Servientrega. Après un échec de connexion, le plugin attend 10 minutes avant la tentative suivante. Enregistrez les réglages pour réessayer immédiatement.
La ville du client n'est pas reconnue: le département et la ville sont comparés au tableau DANE intégré. Pour les orthographes rares, le client peut saisir le code DANE à 8 chiffres comme code postal. Les développeurs peuvent le faire correspondre avec le filtre vfd_svtg_dane_code.
Les tarifs semblent obsolètes après une modification: enregistrez la page des réglages. Cela efface les devis Servientrega mis en cache et le jeton.
Pour les développeurs: les filtres vfd_svtg_quote_request et vfd_svtg_default_dimensions ajustent la requête de devis et les dimensions des produits qui n'en ont pas. vfd_svtg_api_base et vfd_svtg_soap_url modifient les points d'accès (endpoints), par exemple si Servientrega vous fournit un autre serveur.
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 et 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, le plugin continue de fonctionner avec le dernier statut connu.
Désinstallation
La désactivation du plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages, les méthodes de zone, les devis en cache et les jetons 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.
Servientrega est une marque commerciale de son titulaire respectif. Ce plugin n'est ni affilié à Servientrega ni approuvé par Servientrega.