VibeFox Andreani for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions plus anciennes de PHP.

Compte Andreani (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API de devis d'Andreani. Andreani délivre aux clients professionnels des identifiants d'API, un code client et des numéros de contrat, en général à partir d'environ 300 envois par mois. Consultez developers.andreani.com ou écrivez à 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 prix fixes. Le sélecteur d'agence fonctionne sans identifiants.

VibeFox license key : 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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Andreani 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. Définissez 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.

À l'installation, le module crée deux transporteurs :

Les deux transporteurs sont affectés à la zone Argentine 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 Andreani > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Après l'enregistrement, vous voyez Settings saved. Cached token, branches and rates were cleared. Les avertissements concernant les réglages manquants (identifiants de l'API, numéro de contrat, taux de change ARS, pas de prix pour l'Argentine, un transporteur supprimé) s'affichent en haut de la page. Un avertissement apparaît aussi si le module ne reconnaît pas l'unité de poids ou de dimensions de la boutique (les poids sont alors lus en kg et les dimensions en cm). À l'enregistrement, un nom de plus de 64 caractères ou un Min weight (kg) supérieur à Max weight (kg) 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é.

General

Enable/Disable : active ou désactive la livraison Andreani. C'est le même interrupteur que le statut du transporteur principal dans Shipping > Carriers. La seconde option a son propre interrupteur.

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

Tax status : None, ou Taxable avec l'une de vos règles de taxe. Avec une règle de taxe, la boutique ajoute la taxe au coût de livraison, donc le tarif de l'API est pris hors IVA. Avec None, le tarif de l'API est pris TVA incluse. Le réglage est enregistré pour les deux transporteurs Andreani.

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 devis. Laissez ce champ vide pour utiliser l'agence configurée dans votre contrat.

Livraison et tarifs

Delivery modality : la modalité du transporteur principal. 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=PRICE, par exemple AR=5000. Utilisé par le mode fixe et comme solution de repli si l'API échoue. 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 établit ses devis en pesos argentins. Ce réglage n'est nécessaire que 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 lui, les tarifs de l'API ne sont pas utilisés.

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

Calculation type : Per order 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 vaut déjà pour l'ensemble du panier et n'est pas multiplié.

Disponibilité

Min weight (kg) : le poids minimal du panier pour que le transporteur apparaisse. 0 signifie aucune limite.

Max weight (kg) : le poids maximal du panier. Le transporteur est masqué si ce poids est dépassé. Vide signifie 100 kg, 0 signifie aucune limite.

Minimum subtotal : affiche le transporteur uniquement lorsque le sous-total du panier (produits qui nécessitent une livraison, après remises, hors taxes) atteint au moins ce montant. Laissez ce champ vide pour toujours l'afficher.

Ignore shipping zones : propose Andreani pour les pays ci-dessous sans configurer de zones. Lorsque vous l'activez, les deux transporteurs sont liés à toutes les zones, et une zone créée ultérieurement est liée immédiatement. Lorsque vous le désactivez, les transporteurs retrouvent leurs zones précédentes.

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

Livraison gratuite

Free shipping : active le seuil de livraison gratuite.

Free shipping from : le sous-total du panier à partir duquel la livraison est gratuite. Nécessite que Free shipping soit activé.

Seconde option

Un second transporteur Andreani avec son propre nom, sa propre modalité de livraison et son propre contrat, par exemple « a domicilio » pour le transporteur principal et « retiro en sucursal » ici, pour proposer les deux. Tous les autres réglages sont partagés.

Enable second option : active ou désactive le second transporteur. C'est le même interrupteur que son statut dans Shipping > Carriers. Par défaut : désactivé.

Second option name : le nom de cette option au moment du 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 ce champ vide pour utiliser le contrat général.

Sélecteur d'agence au moment du paiement (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 : journalise les requêtes à l'API et les calculs de tarifs dans logs/vfd_andr_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées. Les identifiants et les jetons ne sont jamais journalisés.

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

Remove data on uninstall : lorsque ce réglage est activé, la désinstallation du module supprime tous ses réglages et les transporteurs. Lorsqu'il est désactivé, la désinstallation se contente de désactiver les transporteurs. Les données d'agence enregistrées dans les commandes sont toujours conservées.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix de chaque transporteur Andreani. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le module vérifie 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.

En mode fixe, le prix est pris dans Country prices. En mode temps réel, le module se connecte à l'API Andreani et demande un devis 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. Le montant en ARS est converti avec le ARS exchange rate lorsque la devise de votre boutique n'est pas l'ARS. Le prix est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise de panier du client.

Le jeton de connexion est mis en cache pendant 23 heures et renouvelé automatiquement lorsque Andreani le refuse. Les devis sont mis en cache pendant 1 heure. Un appel API échoué n'est pas répété pendant 5 minutes. Les erreurs de l'API ne sont jamais affichées au client : le transporteur est masqué, 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 là où le transporteur a un prix : si l'API Andreani ne renvoie aucun tarif et qu'il n'existe pas de prix fixe de repli, le transporteur n'est pas affiché.

Si vous modifiez un 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 crée pas d'envois Andreani, n'imprime pas d'étiquettes et ne suit pas les colis. Utilisez le portail web Andreani pour cela.

Points de retrait

Lorsqu'un transporteur avec Door to branch ou Branch to branch est sélectionné, une liste de provinces et une liste d'agences apparaissent en dessous à l'étape de livraison. La province est présélectionnée à partir 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. Les agences qui ne remettent pas de colis ne sont pas listées. Si aucune agence n'est disponible, le client voit No Andreani branches available right now. Please try again later or choose another shipping method.

Le choix est enregistré dans le panier dès que le client le sélectionne. Seule une agence de la liste Andreani en cours est acceptée. Sans agence, Continue à l'étape de livraison et le bouton de commande à l'étape de paiement ne passent pas, et le client voit Please select an Andreani pickup branch. Le serveur vérifie de nouveau 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.

Une agence choisie sous Andreani avant que le client ne passe à un autre transporteur n'appartient pas à la commande.

Commandes

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

Admin order page : un bloc Andreani affiche la modalité et l'agence (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. Seules les agences de la liste Andreani peuvent être enregistrées. Si la liste n'est pas disponible, l'agence ne peut pas être modifiée.

Client : l'agence est affichée sous la forme Andreani pickup branch : sur la page de confirmation de commande et sur la page de détail de commande.

E-mails : dans l'e-mail de confirmation de commande et dans l'e-mail de nouvelle commande envoyé à la boutique (module Mail alerts), l'agence est ajoutée au nom du transporteur. L'e-mail envoyé à la boutique affiche aussi l'ID de l'agence.

Les commandes existantes conservent leurs données d'agence.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Andreani est le premier bloc de Modules > Module Manager > VibeFox Andreani > Configure, 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) 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: presta-shipping-andreani 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 : le domaine 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-le dans votre compte vibefox.net.

Sans clé active, les transporteurs Andreani ne sont pas affichés aux clients au moment du paiement et aucun tarif n'est calculé. La vitrine de PrestaShop ne sait pas que vous êtes connecté au back office : les transporteurs sont donc masqués aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, dans 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é 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 licence.

Dépannage

Andreani n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable/Disable est activé (pour le second transporteur, également Enable second option). Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe de clients, ou activez Ignore shipping zones et vérifiez Countries. Vérifiez que Country prices contient une ligne pour le pays (pour les prix fixes ou comme repli), et contrôlez les limites de poids et le Minimum subtotal. Lisez les avertissements en haut de la page Configure. Les produits peuvent aussi être limités à certains transporteurs sur la page du produit.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log de la page du module. Il indique la raison : identifiants ou numéro de contrat manquants, échec de connexion (nom d'utilisateur, mot de passe ou environnement incorrects), pas encore de code postal argentin valide, pas 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 règle de taxe dans Tax status, le tarif Andreani hors IVA est utilisé et PrestaShop ajoute sa propre taxe. Avec None, le tarif TVA incluse est utilisé et aucune taxe n'est ajoutée. Vérifiez que les taxes sont activées et que la règle de taxe est configurée pour l'Argentine.

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

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide le jeton, la liste des agences et les tarifs mis en cache.

La page indique qu'un transporteur Andreani 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 Andreani et choisissez Uninstall. La clé de licence et le statut de licence sont toujours supprimés. Le jeton, la liste des agences et les tarifs mis en cache sont également toujours supprimés. Si Remove data on uninstall est activé, les transporteurs sont supprimés (les commandes conservent leur historique), et les réglages, le journal et les choix d'agence des paniers sans commande sont supprimés. S'il est désactivé, les transporteurs sont seulement désactivés et tous les réglages sont conservés. Réinstaller le module, ou une Reset du module, rend à ses deux transporteurs leur statut précédent. Les données d'agence enregistrées dans les commandes ne sont jamais supprimées.

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