VibeFox Andreani for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension ne s'active pas sans lui.

PHP : 8.0 ou ultérieur.

Compte Andreani (uniquement pour les tarifs en temps réel) : 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. Il vous faut le nom d'utilisateur et le mot de passe de l'API, le code client et le 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.

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_andreani dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Andreani, 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 et cliquez sur Activate.

5. 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).

6. Allez dans WooCommerce > Settings > Shipping > Shipping zones, ouvrez ou créez une zone pour l'Argentine et ajoutez VibeFox Andreani. Dans la fenêtre de la zone, vous pouvez définir le titre, la modalité de livraison et un contrat différent pour cette option. Vous pouvez aussi activer Ignore shipping zones et choisir des pays à la place.

Configuration

Les réglages principaux se trouvent dans WooCommerce > Settings > Shipping > VibeFox Andreani. Ils s'appliquent à toutes les zones de livraison. Les avertissements concernant les réglages manquants (identifiants de l'API, numéro de contrat, taux de change, aucun prix pour l'Argentine) s'affichent en haut de la page. Chaque fois que vous enregistrez les réglages, le jeton, la liste des agences et les tarifs en cache sont effacés.

Fenêtre de la zone (lorsque vous ajoutez la méthode à une zone de livraison)

Title : le nom de cette option au paiement. Laissez vide pour utiliser le Name général.

Delivery modality : Use global setting ou l'une des quatre modalités (voir ci-dessous). Ajoutez la méthode deux fois à une zone, par exemple du domicile au domicile et retrait en agence, pour proposer les deux.

Contract number : le contrat Andreani de cette option. Laissez vide pour utiliser le contrat général.

Général

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

Name : le nom de la méthode de livraison affiché au client au paiement. Par défaut : Andreani.

Tax status : Taxable signifie que WooCommerce ajoute la taxe au coût de livraison, donc le tarif de l'API est pris sans IVA. None signifie que le tarif de l'API est pris avec l'IVA incluse.

API Andreani (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.

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. Une zone peut utiliser un autre contrat, par exemple pour le retrait en agence.

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

Livraison et tarifs

Delivery modality : 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 de votre boutique, une ligne par pays au format CC=PRICE, par exemple AR=5000. Utilisé en mode fixe et comme solution de repli si l'API échoue. 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. Nécessaire uniquement si la devise 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. Les prix fixes sont toujours dans la devise de votre boutique.

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. Par défaut : 0.5.

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 en temps réel Andreani concerne déjà tout le panier et n'est pas multiplié.

Disponibilité

Min weight (kg) : le poids minimal du panier pour que la méthode apparaisse. 0 signifie aucune limite.

Max weight (kg) : le poids maximal du panier. La méthode est masquée si ce poids est dépassé. Par défaut : 100. 0 signifie aucune limite.

Minimum subtotal : afficher la méthode seulement lorsque le sous-total du panier atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Excluded shipping classes : si un article du panier appartient à une classe d'expédition WooCommerce sélectionnée, la méthode est masquée.

Ignore shipping zones : proposer la méthode pour les pays ci-dessous, même sans l'avoir ajoutée à une zone de livraison.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Utilisé seulement 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é.

Sélecteur d'agence au 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 : enregistre les requêtes API et les calculs de tarifs dans WooCommerce > Status > Logs (source « vfd-andreani »). Les erreurs sont toujours enregistrées. Les identifiants et les jetons ne sont jamais enregistrés.

Remove data on uninstall : lorsqu'il est activé, la suppression de l'extension efface tous ses réglages et les méthodes de zone. La désactivation ne supprime jamais rien. Les données d'agence enregistrées dans les commandes sont toujours conservées.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, l'extension vérifie le poids du panier (les poids des produits sont convertis en kg ; les produits sans poids utilisent Default product weight (kg)), le Minimum subtotal et les Excluded shipping classes.

En mode fixe, le prix est pris dans Country prices. En mode temps réel, l'extension 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 ARS exchange rate lorsque la devise de votre boutique n'est pas l'ARS.

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 : la méthode est masquée ou, en mode de repli, le prix fixe est utilisé. La raison est écrite dans le journal.

Si Free shipping est activé et que le sous-total du panier atteint Free shipping from, le tarif est de 0. La livraison gratuite ne s'applique que là où la méthode a un prix : si l'API Andreani ne renvoie aucun tarif (et qu'il n'existe aucun prix fixe de repli), la méthode n'est pas affichée. Avec Per item, le prix fixe est multiplié par le nombre d'articles.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

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 cela.

Points de retrait

Avec Door to branch ou Branch to branch, une liste de provinces et une liste d'agences apparaissent sous l'option Andreani au paiement, sur le paiement classique comme sur le bloc Paiement. 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 un message et peut choisir une autre méthode de livraison.

La commande ne peut pas être passée sans agence : le client voit Please select an Andreani pickup branch. Ce contrôle est effectué côté serveur pour les deux types de paiement.

L'agence choisie est enregistrée dans la commande. Sur l'écran de commande de l'administration, la modalité et l'agence s'affichent sous l'adresse de livraison. Cliquez sur Edit pour choisir une autre province et une autre agence. Le client voit l'agence sous le nom Andreani pickup branch sur la page de commande et dans les e-mails de commande (HTML et texte brut). 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 se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Andreani. 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, ainsi que 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, Andreani n'est pas affiché aux clients au 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 l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Andreani n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone de l'adresse du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez que Country prices contient une ligne pour le pays (pour les prix fixes ou en repli), puis contrôlez les limites de poids, le Minimum subtotal et les Excluded shipping classes. Lisez les avertissements en haut de la page des réglages.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs (source « vfd-andreani »). Le motif y apparaît : 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 de votre boutique.

La taxe de livraison semble incorrecte : avec Tax status réglé sur Taxable, le tarif Andreani sans IVA est utilisé et WooCommerce ajoute sa propre taxe. Avec None, le tarif avec IVA est utilisé et WooCommerce n'ajoute aucune taxe. Si vous utilisez Taxable, vérifiez que les taxes WooCommerce sont configurées.

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

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface le jeton, la liste des agences et 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 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, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve tous les réglages et efface seulement les caches. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension, ainsi que le jeton, la liste des agences 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 données d'agence enregistrées dans les commandes ne sont jamais supprimées.

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