VibeFox Servientrega for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé avec la version 3.0.5.0) ou 4.0.2 et ultérieur (testé avec la version 4.1.0.3).

PHP : 8.0 ou ultérieur.

Compte Servientrega (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent le Cotizador Corporativo de Servientrega (API de devis entreprise). Vous avez besoin d'un compte entreprise (crédit) Servientrega ayant accès à celui-ci. Il vous faut trois informations : l'utilisateur, le mot de passe et le code de facturation (código de facturación, généralement qui commence par SER). Ce sont vos identifiants SISCLINET, délivrés par votre conseiller commercial Servientrega. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de compte Servientrega.

Accès au serveur (uniquement pour les tarifs en temps réel) : 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

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_servientrega-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_servientrega.ocmod.zip. Installez uniquement 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_servientrega-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 aussi copier le contenu du dossier upload du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions, choisissez le type d'extension Shipping, repérez VibeFox Servientrega et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des 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. 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 de l'origine et, si la devise de votre boutique n'est pas le COP, le taux de conversion de devise.

6. Facultativement, ajoutez des prix fixes par pays et par poids ainsi qu'un coût de repli, activez Enable Servientrega et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_servientrega.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é de lui.

3. Allez dans Extensions > Extensions, choisissez le type d'extension Shipping, repérez VibeFox Servientrega, 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 à 6 pour OpenCart 3. La page des réglages et ses champs sont identiques dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous n'activez pas Enable Servientrega et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Servientrega conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. Les sections sont listées à gauche. Elles s'appliquent à toutes les zones géographiques. Un seul bouton Save, en bas, enregistre toute la page sans la recharger. Chaque enregistrement efface les devis Servientrega en cache et le jeton de connexion. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Si les tarifs en temps réel ne peuvent pas fonctionner avec les réglages enregistrés, un avertissement au-dessus des réglages vous indique la raison : utilisateur, mot de passe ou code de facturation manquant, taux de conversion manquant, ou code DANE d'origine manquant. Un avertissement apparaît aussi si la boutique n'a pas de classe de poids en kg ni de classe de longueur en cm et si son unité par défaut n'est pas connue de l'extension ; les poids sont alors lus en kg et les dimensions en cm. Lors de l'enregistrement, une valeur qui n'est pas un nombre, un nombre négatif, un taux de conversion de 0, un poids minimum supérieur au poids maximum, un prix erroné dans le tableau, un titre de mode vide, supérieur à 64 caractères ou contenant < > ; = # { }, ou un ordre de tri qui n'est pas un nombre entier est refusé avec une erreur, et rien n'est enregistré.

Général

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

Method title : le nom du mode de livraison affiché au client dans le panier et au paiement. Par défaut : Servientrega. Obligatoire, 64 caractères maximum.

Sort order : la position de Servientrega parmi les modes de livraison au paiement. Un nombre entier.

API Servientrega (tarifs en temps réel pour la Colombie) (facultatif ; sans identifiants, seuls les prix fixes sont utilisés)

User (login) : votre utilisateur Servientrega / SISCLINET. Le vider supprime aussi le mot de passe enregistré.

Password : votre mot de passe Servientrega / SISCLINET, tel que vous le saisissez. L'extension le fait chiffrer par le service web de Servientrega avant la connexion. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Billing code : le código de facturación (code de facturation) de votre compte Servientrega, tel qu'il apparaît 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 prix fixes.

Servientrega product : le service de votre accord avec 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 devis en COP. Si la devise par défaut 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. Si la devise de votre boutique est le COP, le champ indique qu'aucune conversion n'est nécessaire : laissez-le vide. 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 prix fixes s'appliquent. L'extension ne récupère pas de taux de change. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Ship from (utilisé pour les tarifs en temps réel)

Origin city (DANE code) : le code DANE à 8 chiffres de la municipalité depuis laquelle vous expédiez, par exemple 11001000 Bogotá, 05001000 Medellín, 76001000 Cali ou 08001000 Barranquilla. Un code de municipalité à 5 chiffres est aussi accepté. L'adresse de la boutique dans OpenCart est un texte libre : l'origine n'en est donc jamais tirée. Sans ce champ, il n'y a pas de tarifs en temps réel.

Fixed prices (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, erreur de l'API ou absence de couverture pour la liaison)

Price per country : un tableau de pays et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add country pour ajouter une ligne et sur le bouton de suppression pour en supprimer une. Price s'applique à tout poids. Les colonnes de poids XS (jusqu'à 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) et XL (plus de 5 kg) le remplacent pour ce poids lorsqu'elles sont supérieures à 0. La ligne * Default s'applique à tous les pays sans ligne propre. Une nouvelle ligne commence comme * Default. Une ligne sans aucun prix n'est pas enregistrée.

Fallback cost : utilisé lorsqu'il n'y a pas de tarif en temps réel et qu'aucune ligne du tableau ne correspond. Laissez-le vide pour masquer le mode dans ce cas.

Fixed price applies : la manière dont les prix fixes sont facturés.

Les tarifs Servientrega en temps réel sont toujours par envoi.

Conditions

Minimum weight (kg) : masque le mode en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Maximum weight (kg) : masque le mode au-dessus de ce poids de panier. Par défaut : 50. 0 signifie aucune limite.

Minimum order amount : affiche le mode uniquement lorsque le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint ce montant. Laissez vide pour l'afficher toujours.

Free shipping from : la livraison est gratuite lorsque ce sous-total atteint ce montant, et aucune requête n'est envoyée à Servientrega. Cela s'applique à toute destination où le mode est proposé, y compris aux pays sans ligne dans le tableau des prix. Laissez vide pour ne jamais proposer la livraison gratuite.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Les devis Servientrega (ValorTotal) incluent déjà les frais du transporteur. Choisissez No tax si vous ne voulez pas ajouter de taxe en plus.

Geo zone : proposer Servientrega 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. Elle n'est pas vérifiée lorsque Ignore shipping zones est activé.

Availability without geo zone

En général, le mode est proposé dans la zone géographique sélectionnée dans Conditions, ou partout.

Ignore shipping zones : proposer Servientrega pour les pays ci-dessous, quelle que soit la zone géographique.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays activés de votre boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Advanced

Debug log : écrit les calculs de tarifs et les erreurs de l'API dans storage/logs/vfd_svtg_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les identifiants, jetons et adresses des clients ne sont pas journalisés. Lorsque le journal est désactivé, rien n'est écrit, y compris les erreurs de l'API. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_svtg_debug.old.log.php et un nouveau journal est démarré. Désactivez le journal lorsque vous avez terminé.

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 cette option est activée, la désinstallation de l'extension supprime tous les réglages Servientrega et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les devis en cache sont toujours supprimés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le mot de passe n'est pas exporté.

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 contrôlées comme lors d'un enregistrement normal. Le mot de passe enregistré est conservé tant que l'utilisateur est défini.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Servientrega. Si une Geo zone est définie et que l'adresse se trouve en dehors, Servientrega n'est pas proposé (sauf si Ignore shipping zones est activé). Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le montant de la commande est le prix de ces produits après la remise du coupon et avant taxes. Les cartes cadeaux et les points de fidélité ne sont pas pris en compte. L'extension vérifie d'abord les conditions : le pays de livraison (avec Ignore shipping zones), le poids du panier et le montant minimum de commande. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Servientrega. Elle recherche ensuite un prix : le tarif Servientrega en temps réel, puis le tableau des prix, et enfin le coût de repli. S'il n'y a pas de prix, le mode est masqué pour ce panier.

Pour une destination en Colombie avec des identifiants configurés, l'extension trouve le code DANE de la municipalité du client. Elle utilise un code DANE saisi dans le champ code postal ou ville, ou fait correspondre le département et la ville avec le tableau intégré d'environ 1 130 municipalités. Le département correspond à la Region / State de l'adresse : OpenCart dispose déjà des 33 départements colombiens. Les accents et « D.C. » sont ignorés. Une ville qui n'existe que dans un seul département est trouvée même sans le département.

L'extension envoie ensuite à Servientrega un seul colis par commande : le poids total converti de la classe de poids du produit en kg, et une boîte dont la longueur et la largeur correspondent à l'article le plus grand et dont le volume correspond au volume total de tous les articles, converti en cm. Les produits sans dimensions comptent comme 10 × 10 × 10 cm. La valeur déclarée est le montant de la commande converti en COP, avec un minimum de 6 000 COP. Servientrega renvoie le total en COP. L'extension le convertit dans la devise par défaut de votre boutique et l'arrondit à ses décimales. Le client le voit dans sa devise avec la taxe de la Tax class sélectionnée.

Le jeton de connexion est conservé jusqu'à son expiration, au maximum 4 jours. Un jeton refusé est renouvelé automatiquement une fois. Chaque devis est mis en cache pendant 1 heure par trajet 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.

Le client ne voit jamais d'erreur de l'API. La raison est écrite dans le journal de débogage lorsqu'il est activé.

L'extension calcule uniquement des tarifs. Elle ne crée pas de bordereaux (guías), d'étiquettes ni d'autocollants, ne demande pas d'enlèvement, ne suit ni n'annule les envois, et ne permet pas au client de choisir un bureau Servientrega (Centro de Soluciones). Créez le bordereau dans SISCLINET ou dans votre portail Servientrega. Le paiement à la livraison (logística de recaudo) n'est pas coté. Les devis en temps réel ne concernent que les envois nationaux à l'intérieur de la Colombie. L'extension n'ajoute rien aux commandes : la commande affiche le nom du mode et le coût de livraison comme tout autre mode de livraison OpenCart.

Sur OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement et choisit Servientrega dans la fenêtre Shipping method options, où le nom du mode s'affiche avec le prix. Le mode 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 Servientrega est le premier bloc de Extensions > Extensions > Shipping > VibeFox Servientrega > Edit, au-dessus des réglages. Saisissez la clé dans License key puis 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) et 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-servientrega et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de 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 statut 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-le dans votre compte vibefox.net.

Sans clé active, le mode de livraison Servientrega n'est pas affiché aux clients au paiement et aucun tarif n'est demandé ni calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode dans la boutique, marqué (unlicensed — visible to admins only), ce qui vous permet de configurer et 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, donc sans clé active le mode est masqué pour tout le monde. Une fois la page Edit ouverte une première fois, 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 à l'ouverture du Dashboard ou de la page Edit de l'administration : 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

Servientrega n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Servientrega est activé. Vérifiez Geo zone, ou activez Ignore shipping zones et vérifiez Countries. Vérifiez les limites de poids et le Minimum order amount. Sans tarif en temps réel, vérifiez que le pays ou * Default a un prix, ou que Fallback cost est défini. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Raisons courantes : 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 encore saisi ou non reconnu comme municipalité, identifiants erronés, absence de couverture pour la liaison, ou serveur incapable de joindre web.servientrega.com sur les ports 8058 et 8081. Les prix fixes couvrent ces cas si vous les configurez.

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 une connexion échouée, l'extension attend 10 minutes avant la prochaine tentative. Enregistrez les réglages pour réessayer immédiatement.

La ville du client n'est pas reconnue : le client doit choisir le département dans le champ Region / State. Pour les orthographes rares, le client peut saisir le code DANE à 8 chiffres comme code postal.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela efface les devis Servientrega en cache et le jeton.

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

Pour les développeurs : les événements OpenCart vfd_servientrega/dane_code et vfd_servientrega/quote_request permettent à une autre extension de modifier le code DANE de destination et la requête de devis.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Servientrega. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Servientrega, Sort order, Tax class et Geo zone. Les devis en cache, les jetons et le mot de passe chiffré sont toujours supprimés. Si Remove data on uninstall est activé, les autres réglages et le journal sont également supprimés. S'il est désactivé, ils sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les commandes existantes conservent leur mode de livraison et leur coût.

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 Servientrega dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet téléversé.

Servientrega est une marque déposée de son titulaire. Cette extension n'est ni affiliée à Servientrega ni approuvée par Servientrega.