VibeFox Andreani 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), avec le thème par défaut.

PHP : 8.0 ou ultérieur.

Compte Andreani (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API de cotation d'Andreani. Andreani fournit aux clients professionnels des identifiants API, un code client et des numéros de contrat, généralement à partir d'environ 300 envois par mois. Voir developers.andreani.com ou écrire à ventapyme@andreani.com. Vous avez besoin du nom d'utilisateur et du mot de passe de l'API, du code client et du numéro de contrat. Andreani délivre un contrat distinct pour chaque service (livraison à domicile, retrait en agence). Sans accès à l'API, utilisez des tarifs fixes. Le sélecteur d'agence fonctionne sans identifiants.

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 contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_andreani-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_andreani.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_andreani-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'installeur, 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 Andreani et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page des 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. Renseignez le nom, la source des tarifs, les prix par pays (par exemple AR=5000) et, pour les tarifs en temps réel, les identifiants de l'API, le code client et le numéro de contrat (voir Configuration). Cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_andreani.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 Andreani, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page des réglages et ses champs sont les mêmes dans les deux versions.

Après l'installation, Enable/Disable et Enable second option sont désactivés, et Andreani n'est pas proposé au paiement tant que vous n'avez pas activé une option et cliqué sur Save. Si vous réinstallez l'extension après une désinstallation, les réglages Andreani conservés sont à nouveau utilisés, mais les deux options sont désactivées : activez-les et cliquez sur Save.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Andreani > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Ensuite, vous voyez Settings saved. Cached token, branches and rates were cleared. Seuls les administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

Des avertissements sur les réglages manquants apparaissent en haut de la page : tarifs API choisis sans nom d'utilisateur ni mot de passe API ou sans numéro de contrat, absence de ARS exchange rate lorsque la devise de votre boutique n'est pas l'ARS, ou absence de prix pour l'Argentine dans Country prices. Un avertissement apparaît aussi si l'unité de poids ou de longueur de la boutique n'est pas reconnue par l'extension (les poids sont alors lus en kg, et les dimensions en cm).

À l'enregistrement, un nom vide, un nom de plus de 64 caractères ou contenant l'un des caractères < > ; = # { }, un Min weight (kg) supérieur à Max weight (kg), ou un Sort order qui n'est pas un nombre entier, est refusé et rien n'est enregistré. Une valeur qui n'est pas un nombre, un nombre négatif ou un ARS exchange rate égal ou inférieur à 0 n'est pas enregistré, et un avertissement indique le champ concerné.

Général

Andreani propose deux options au paiement : l'option principale, configurée ici et dans Andreani API et Delivery and rates, et la Second option. Les deux apparaissent sous l'intitulé Andreani à l'étape du mode de livraison.

Enable/Disable : active ou désactive l'option principale Andreani. Par défaut : désactivé. La seconde option a son propre interrupteur.

Name : le nom de l'option principale affiché au client au paiement. Par défaut : Andreani. Obligatoire.

Tax status : None (the API rate is taken with IVA) (par défaut), ou l'une de vos classes de taxe. Avec une classe de taxe, OpenCart ajoute la taxe au coût de livraison, donc le tarif de l'API est pris sans IVA. Avec None, le tarif de l'API est pris TVA argentine (IVA) incluse. Utilisé par les deux options.

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

Andreani API (nécessaire pour les tarifs en temps réel)

Environment : Sandbox / QA (apisqa.andreani.com) (par défaut) ou Production (apis.andreani.com). Utilisez l'environnement auquel appartiennent vos identifiants.

API username : votre nom d'utilisateur de l'API Andreani.

API password : votre mot de passe de l'API Andreani. Après l'enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Clearing the API username removes it too. Ne saisissez une nouvelle valeur que pour la modifier.

Client code : le code client (código de cliente) fourni par Andreani, par exemple CL0000000.

Contract number : le contrat du service utilisé pour les tarifs, par exemple la livraison à domicile. La seconde option peut utiliser un autre contrat, par exemple pour le retrait en agence.

Origin branch code : agence d'origine facultative (sucursalOrigen) pour les cotations. Laissez vide pour utiliser l'agence configurée dans votre contrat.

Livraison et tarifs

Delivery modality : la modalité de l'option principale. La première partie indique où Andreani prend le colis (votre adresse ou une agence où vous le déposez). La seconde partie indique où le client le reçoit.

Rate source : la manière dont le prix est calculé.

Country prices : un prix fixe par pays de destination dans la devise par défaut de votre boutique, hors taxes, une ligne par pays au format CC=PRIX, par exemple AR=5000. Utilisé en mode fixe et comme solution de repli de l'API. Les pays sans ligne n'ont pas de prix fixe. Les lignes dans un autre format sont ignorées, et un avertissement les liste à l'enregistrement.

ARS exchange rate : Andreani cote en pesos argentins. Nécessaire uniquement si la devise par défaut de votre boutique n'est pas l'ARS : le prix de 1 ARS dans la devise de votre boutique, par exemple 0.001. Sans ce réglage, les tarifs de l'API ne sont pas utilisés.

Default product weight (kg) : utilisé pour les produits sans poids lors de la demande de tarifs à l'API et de la vérification des limites de poids. Vide signifie 0,5 kg.

Calculation type : Per order (par défaut) facture le prix une seule fois. Per item (price x number of items) multiplie le prix fixe de Country prices par le nombre d'articles du panier. Un tarif Andreani en temps réel concerne déjà tout le panier et n'est pas multiplié.

Disponibilité

Min weight (kg) : le poids minimum du panier pour que l'option apparaisse. 0 signifie sans limite (par défaut).

Max weight (kg) : le poids maximum du panier. L'option est masquée si ce poids est dépassé. Par défaut : 100. Vide signifie 100 kg, 0 signifie sans limite.

Minimum subtotal : n'affiche l'option que lorsque le sous-total du panier (produits à expédier, après le coupon, hors taxes, dans la devise par défaut de votre boutique) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Geo zone : ne propose Andreani que pour les adresses de cette zone géographique. All zones (par défaut) signifie sans limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Non utilisé lorsque Ignore shipping zones est activé.

Ignore shipping zones : propose Andreani pour les pays indiqués ci-dessous, quelle que soit la zone géographique. Par défaut : désactivé.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Utilisé uniquement lorsque Ignore shipping zones est activé.

Livraison gratuite

Free shipping : active le seuil de livraison gratuite. Par défaut : désactivé.

Free shipping from : le sous-total du panier (dans la devise par défaut de votre boutique) à partir duquel la livraison est gratuite. Nécessite que Free shipping soit activé.

Seconde option

Une seconde option Andreani avec son propre nom, sa propre modalité de livraison et son propre contrat, par exemple "a domicilio" pour l'option principale et "retiro en sucursal" ici, pour proposer les deux. Tous les autres réglages sont partagés.

Enable second option : propose la seconde option au paiement. Par défaut : désactivé.

Second option name : le nom de cette option au paiement. Par défaut : Andreani - branch pickup. Obligatoire.

Delivery modality : Use global setting ou l'une des quatre modalités. Par défaut : Door to branch (Puerta a Sucursal).

Contract number : Andreani délivre un contrat distinct par service (livraison à domicile, retrait en agence). Laissez vide pour utiliser le contrat global.

Sélecteur d'agence (affiché pour Door to branch et Branch to branch)

Province select width : la largeur CSS de la liste des provinces, par exemple 100% ou 300px. Par défaut : 100%.

Branch select width : la largeur CSS de la liste des agences, par exemple 100% ou 400px. Par défaut : 100%.

Avancé

Debug log : consigne les requêtes API et les calculs de tarifs dans storage/logs/vfd_andr_debug.log.php. Ce fichier n'est pas lisible depuis le web. Les erreurs sont toujours consignées. Les identifiants et les jetons ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_andr_debug.old.log.php et un nouveau journal est démarré.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Remove data on uninstall : si cette option est activée, la désinstallation de l'extension supprime tous les réglages Andreani et le journal. Désactivée (par défaut), ils sont conservés pour une réinstallation. Les données d'agence enregistrées dans les commandes sont toujours conservées.

Import / Export

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

Import : collez un JSON précédemment exporté 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 de l'API enregistré est conservé.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix de chaque option Andreani activée. Si une Geo zone est définie et que Ignore shipping zones est désactivé, Andreani n'est pas proposé aux adresses situées hors de la zone géographique. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. L'extension vérifie ensuite les pays (lorsque Ignore shipping zones est activé), le poids du panier (les poids des produits sont convertis en kg, et les produits sans poids utilisent Default product weight (kg)) et le Minimum subtotal. Le sous-total est le prix des produits à expédier, après la remise du coupon et avant taxes.

En mode fixe, le prix est pris dans Country prices. En modes de tarifs en temps réel, l'extension se connecte à l'API Andreani et demande une cotation avec le code postal de destination, le contrat, le code client, le poids en kg, le volume calculé à partir des dimensions des produits et la valeur déclarée (le sous-total du panier en ARS). Un tarif en temps réel n'est demandé que pour un code postal argentin valide (4 chiffres, ou un CPA comme C1425ABC). Le montant en ARS est converti avec ARS exchange rate lorsque la devise de la boutique n'est pas l'ARS. Le prix est calculé dans la devise par défaut de la boutique, arrondi à ses décimales, et affiché au client dans sa devise avec la taxe du Tax status choisi.

Le jeton de connexion est conservé jusqu'à 23 heures et renouvelé automatiquement lorsque Andreani le refuse. Les cotations sont mises en cache pendant 1 heure. Un appel API en échec n'est pas renouvelé pendant 5 minutes. Tout cela est stocké dans le cache d'OpenCart, si bien qu'une entrée n'est jamais conservée plus longtemps que la durée de vie du cache d'OpenCart (1 heure par défaut) et est alors simplement redemandée. Les erreurs de l'API ne sont jamais affichées au client : l'option est masquée, ou le prix fixe est utilisé en mode de repli. La raison est inscrite dans le journal.

Si Free shipping est activé et que le sous-total du panier atteint Free shipping from, le prix est de 0. La livraison gratuite ne s'applique que lorsque l'option a un prix : si l'API Andreani ne renvoie aucun tarif et qu'il n'existe pas de prix fixe de repli, l'option n'est pas affichée.

L'extension ne crée pas d'envois Andreani, n'imprime pas d'étiquettes et ne suit pas les colis. Utilisez le portail web d'Andreani pour ces opérations.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit une option Andreani dans la fenêtre Shipping method options. Les options fonctionnent de la même manière que sous OpenCart 3 ; la sélection d'agence est décrite dans Points de retrait.

Points de retrait

Lorsqu'une option avec Door to branch ou Branch to branch est proposée, une liste de provinces et une liste d'agences apparaissent juste sous elle, à l'étape du mode de livraison. La province est présélectionnée d'après la région de l'adresse de livraison. La liste des agences provient de l'API publique des agences Andreani et est mise en cache pendant 12 heures au maximum (dans la limite de la durée de vie du cache d'OpenCart). Les agences qui ne remettent pas de colis ne sont pas listées. L'étape de livraison elle-même n'attend jamais Andreani : si la liste n'est pas encore en cache, elle est chargée en arrière-plan et le client voit brièvement Loading Andreani branches.... S'il n'y a aucune agence disponible, le client voit No Andreani branches available right now. Please try again later or choose another shipping method.

Le choix est enregistré dès que le client le sélectionne. Seule une agence figurant dans la liste Andreani actuelle est acceptée. Sans agence, Continue à l'étape du mode de livraison ne passe pas, et le client voit Please select an Andreani pickup branch. Le serveur revérifie l'agence lorsque le client poursuit. Si l'agence ne figure plus dans la liste, le client voit The selected Andreani branch is not available. Please choose another one.

Sur OpenCart 4, la liste des provinces et la liste des agences apparaissent dans la fenêtre Shipping method options, juste sous l'option d'agence Andreani, avec les mêmes textes et contrôles. Continue dans la fenêtre sans agence est bloqué avec Please select an Andreani pickup branch. sous l'option. Si la boutique refuse l'agence lorsque le client poursuit, le message s'affiche en haut de la page de paiement et la fenêtre reste ouverte. OpenCart 4 conserve une commande pour le paiement et la met à jour à chaque confirmation ; l'agence de la commande est mise à jour avec elle, et elle est supprimée lorsque le client change la commande pour un autre mode de livraison.

Une agence choisie sous une option Andreani n'appartient pas à une commande passée avec une autre option ou un autre mode de livraison.

Le sélecteur est conçu pour le tunnel de commande en une page du thème par défaut d'OpenCart 3 et pour le tunnel de commande du thème par défaut d'OpenCart 4. Un thème dont l'étape de livraison a une autre mise en page peut nécessiter des modifications du script du sélecteur.

Commandes

La commande conserve la modalité de livraison et, pour les modalités avec agence, l'agence choisie.

Shipping method of the order : l'agence est ajoutée au texte du mode de livraison, par exemple Andreani - branch pickup: suivi du nom de l'agence. Si le nom de l'option ne mentionne pas d'agence, le texte Pickup branch: (ou Andreani pickup branch: lorsque le nom ne contient pas Andreani) est ajouté devant le nom de l'agence, par exemple Andreani - Pickup branch: suivi du nom de l'agence. Ce texte apparaît dans les e-mails de commande envoyés au client et à la boutique, dans l'historique des commandes du client, sur la facture et sur la page de commande côté administrateur. OpenCart limite le texte à 128 caractères ; les données complètes de l'agence sont conservées par l'extension. La page de confirmation de commande d'OpenCart n'affiche pas le mode de livraison.

Admin order page : dans Sales > Orders, ouvrez une commande. Un panneau Andreani affiche Andreani modality et, pour les modalités avec agence, Andreani branch (nom, ID et province). Cliquez sur Edit, choisissez une autre province et une autre agence, puis cliquez sur Save pour la modifier. Vous voyez Branch updated., et l'agence dans le texte du mode de livraison de la commande est aussi remplacée. Seules les agences de la liste Andreani peuvent être enregistrées. Si la liste n'est pas disponible, vous voyez The Andreani branch list is not available right now - the branch cannot be changed. Modifier l'agence nécessite l'autorisation de modification pour sale/order et l'accès à extension/shipping/vfd_andreani (OpenCart 3) ou extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4). Le panneau est affiché aussi pour les commandes déjà passées avec Andreani lorsque l'extension est désactivée.

Lorsque l'extension est désactivée, le panneau Andreani n'est pas affiché. Les données d'agence restent enregistrées et le texte du mode de livraison de la commande ne change pas. Les commandes existantes conservent leurs données d'agence.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Andreani est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox Andreani > Edit, 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. En dessous figurent la ligne Product: opencart-shipping-andreani et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation Modify 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 issue de 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, les options de livraison Andreani ne sont pas affichées aux clients au paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode de livraison dans la boutique, marqué (unlicensed — visible to admins only), afin de pouvoir 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. 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 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 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 licence.

Dépannage

Andreani n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé (pour la seconde option, aussi Enable second option), et que vous avez cliqué sur Save après l'installation. Vérifiez Geo zone, ou Ignore shipping zones et Countries. Vérifiez que Country prices contient une ligne pour le pays (pour les prix fixes ou en repli), les limites de poids et le Minimum subtotal. Lisez les avertissements en haut de la page Edit. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Il indique la raison : identifiants ou numéro de contrat manquants, échec de connexion (nom d'utilisateur, mot de passe ou environnement incorrects), absence de code postal argentin valide, absence de taux de change ou erreur HTTP d'Andreani. Avec Andreani API, fixed price if the API fails, les clients obtiennent toujours le prix fixe pendant que vous corrigez le problème.

Ma boutique n'est pas en pesos argentins : réglez ARS exchange rate sur la valeur de 1 ARS dans la devise par défaut de votre boutique.

La taxe sur la livraison semble incorrecte : avec une classe de taxe dans Tax status, le tarif Andreani sans IVA est utilisé et OpenCart ajoute sa propre taxe. Avec None, le tarif avec IVA est utilisé et aucune taxe n'est ajoutée. Vérifiez que les taxes sont activées dans les réglages de la boutique et que la classe de taxe comporte des taux pour l'Argentine.

Aucune agence dans la liste : l'API des agences Andreani n'a pas répondu. Une requête en échec est renouvelée après 5 minutes. Consultez le journal.

La mauvaise province est présélectionnée : la province est lue d'après la région de l'adresse de livraison. Le client peut toujours choisir une autre province.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela vide le jeton, la liste des agences et les tarifs en cache.

La page indique « Warning: You do not have permission to modify VibeFox Andreani! » : 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_andreani (OpenCart 3) ou extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : les hôtes de l'API Andreani peuvent être remplacés par le réglage vfd_andr_api_url (pour les tests) ; il n'a pas de champ sur la page des réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Andreani. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours le statut, Sort order, Tax status et Geo zone. L'extension supprime toujours ses gestionnaires de la page de paiement et de la page de commande, ainsi que le jeton, la liste des agences et les tarifs en cache. Si Remove data on uninstall est activé, tous les réglages Andreani et le journal de débogage sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les données d'agence enregistrées dans les commandes ne sont jamais supprimées, et 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, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Andreani dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet envoyé.

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