VibeFox Aramex for WooCommerce — Aide
Prérequis
WordPress: 5.8 ou ultérieur.
WooCommerce: 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.
PHP: 8.0 ou ultérieur.
Compte Aramex (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent l'API Aramex Rate Calculator. Aramex donne accès à l'API à ses titulaires de compte. Adressez-vous à votre responsable de compte Aramex ou consultez l'Aramex Developers Solution Center sur le site d'Aramex. Il vous faut six valeurs : nom d'utilisateur API (généralement une adresse e-mail), mot de passe, numéro de compte, code PIN du compte, entité du compte (par exemple DXB) et code pays du compte (par exemple AE). Si vous utilisez uniquement des prix fixes par pays, vous n'avez pas besoin de compte Aramex.
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 téléverser le dossier vfd_aramex dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Aramex, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Choisissez le mode de calcul du coût d'expédition et remplissez les sections correspondantes (voir Configuration).
6. Ajoutez VibeFox Aramex à 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 Aramex. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez le mode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :
Title (zone): le nom que les clients voient pour cette zone. Laissez-le vide pour utiliser le Method title global.
Chaque fois que vous enregistrez les réglages, les tarifs Aramex mis en cache sont effacés.
Général
Enable/Disable: active ou désactive le mode dans toutes les zones à la fois.
Method title: le nom du mode de livraison affiché dans le panier et lors du paiement. Par défaut : Aramex.
Shipping cost: le mode de calcul du prix.
La raison de l'absence de tarif en temps réel est écrite dans le journal de débogage. Elle n'est jamais affichée au client.
Compte API Aramex (nécessaire uniquement pour les tarifs en temps réel ; les six champs sont obligatoires)
Username: votre nom d'utilisateur API Aramex, généralement une adresse e-mail.
Password: votre mot de passe API Aramex.
Account number: le numéro de votre compte client Aramex.
Account PIN: le code PIN de votre compte Aramex.
Account entity: le code de l'entité (bureau) Aramex de votre compte, par exemple DXB, AMM ou RUH.
Account country code: le code pays à 2 lettres de votre compte Aramex, par exemple AE.
Service Aramex (utilisé pour les tarifs en temps réel)
Si l'adresse de livraison se trouve dans le pays d'origine, l'envoi est calculé comme Domestic. Tous les autres envois sont calculés comme International express.
International service: le produit Aramex pour les envois à l'étranger : PPX Priority Parcel Express (par défaut), PDX Priority Document Express, PLX Priority Letter Express, DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express ou GDX Ground Document Express.
Domestic service: le produit Aramex pour les envois à l'intérieur du pays d'origine : ONP Overnight Parcel (par défaut), OND Overnight Document, SMP Same Day Parcel, SMD Same Day Document, SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express ou HVY Heavy (20 kg et plus).
Payment type: qui paie Aramex pour l'envoi : Prepaid (l'expéditeur paie), Collect (le destinataire paie) ou Third party (tiers). Généralement Prepaid.
API weight unit: l'unité envoyée à Aramex, KG ou LB. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. Le poids facturable est le plus élevé entre le poids réel et le poids volumétrique (longueur × largeur × hauteur en cm / 5000). Le minimum est de 0,5 kg, ce qui couvre aussi les produits sans poids.
Currency conversion rate: Aramex est invité à établir son tarif dans la devise de votre boutique. S'il répond tout de même dans une autre devise, le tarif est multiplié par ce nombre (1 unité de la devise Aramex = X unités de la devise de votre boutique). Laissez vide pour rejeter ces tarifs, afin que le client ne soit jamais facturé dans une mauvaise devise. Le point et la virgule sont tous deux acceptés comme séparateur décimal.
Expédition depuis (adresse d'origine) (utilisé pour les tarifs en temps réel)
Origin country: le pays depuis lequel vous expédiez. Par défaut, le pays de votre boutique.
Origin city: la ville depuis laquelle vous expédiez. Aramex l'exige.
Origin state / emirate: facultatif.
Origin postcode: facultatif.
Si le pays d'origine est le pays de votre boutique, les champs vides sont repris de l'adresse de la boutique dans WooCommerce > Settings > General.
Prix fixes (utilisés en mode fixe et comme solution de repli pour les tarifs en temps réel)
Price per country: un tableau de codes pays à 2 lettres et de prix dans la devise de votre boutique. Cliquez sur Add row pour ajouter un pays et sur la croix pour en supprimer un. Utilisez * comme code pays pour tous les autres pays. Les pays sans prix (en l'absence de ligne *) n'ont pas de tarif fixe, le mode leur est donc masqué.
Fixed price applies: Per order facture le prix une seule fois. Per item le multiplie par le nombre d'articles du panier. Les tarifs Aramex en temps réel sont toujours calculés par envoi.
Conditions
Minimum weight (kg): masque le mode lorsque le panier pèse moins. 0 signifie pas de limite.
Maximum weight (kg): masque le mode lorsque le panier pèse davantage. Par défaut : 100. 0 signifie pas de limite.
Minimum order amount: n'affiche le mode que lorsque le sous-total du panier (après remises, hors taxes) atteint ce montant. Laissez vide pour l'afficher dans tous les cas.
Excluded shipping classes: masque le mode lorsque le panier contient un produit appartenant à l'une de ces classes de livraison WooCommerce.
Free shipping: active la livraison Aramex gratuite à partir du montant ci-dessous.
Free shipping from: le sous-total du panier (après remises, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.
Tax status: Taxable ajoute la taxe WooCommerce au coût d'expédition, None ne l'ajoute pas. Les tarifs Aramex en temps réel peuvent déjà inclure la TVA. Dans ce cas, choisissez None pour ne pas facturer la taxe deux fois.
Disponibilité sans zones de livraison
Ignore shipping zones: propose Aramex pour les pays ci-dessous, même si le mode n'est ajouté à 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 d'API dans logs/vfd_armx_debug.log.php, dans le dossier de l'extension. Le fichier ne peut pas être ouvert depuis le web. Les mots de passe, le PIN, le numéro de compte et les adresses des clients sont masqués. Désactivez le journal lorsque vous avez terminé.
Remove data on uninstall: lorsque l'option est activée, la suppression de l'extension efface tous ses réglages, méthodes de zone, tarifs en cache et journaux. La désactivation de l'extension ne supprime jamais rien.
Fonctionnement lors du paiement
Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : pays de livraison, poids du panier, montant minimum de commande et classes de livraison exclues. Si la livraison gratuite s'applique, le client voit le mode Aramex (free) et aucune requête n'est envoyée à Aramex.
En mode fixe, le prix est pris dans le tableau. Dans les modes en temps réel, l'extension envoie à Aramex les adresses d'origine et de livraison, le poids facturable, le service et la devise de votre boutique, puis affiche le total renvoyé. Un tarif en temps réel n'est demandé qu'après que le client a saisi une ville ou un code postal. Chaque réponse est mise en cache pendant 1 heure, afin que le même panier ne déclenche pas une nouvelle requête. Une requête échouée est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Aramex à chaque actualisation. Le délai d'attente de l'API est de 10 secondes.
Si Aramex renvoie une erreur, un montant nul ou un tarif dans une autre devise sans taux de conversion, le client ne voit aucune erreur. Le mode est masqué, ou le prix fixe est utilisé en mode de repli. La raison est écrite dans le journal de débogage.
Le mode fonctionne avec le paiement classique ainsi qu'avec les blocs Panier et Paiement. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L'extension ne calcule que les tarifs. Elle ne crée pas d'envois Aramex, n'imprime pas d'étiquettes, ne réserve pas d'enlèvements, ne suit pas les colis et ne permet pas aux clients de choisir un bureau Aramex. Le colis est toujours envoyé à Aramex en une seule pièce.
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 Aramex. 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 l'emplacement de son domaine. Libérez-le dans votre compte vibefox.net.
Sans clé active, Aramex n'est pas affiché aux clients lors du 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 Extensions 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
Aramex n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode est ajouté à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids, Minimum order amount et Excluded shipping classes. En mode fixe, vérifiez que le pays ou * a un prix.
Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez la page de paiement et ouvrez logs/vfd_armx_debug.log.php dans le dossier de l'extension. Il indique la raison : identifiants API manquants, code d'erreur Aramex, ville d'origine absente, ville ou code postal de livraison pas encore renseigné, limite de poids ou de montant, ou tarif dans une autre devise. Avec Aramex live rates, fixed prices if the API fails, les clients obtiennent toujours le prix fixe pendant que vous résolvez le problème.
Erreur ERR75 dans le journal : Aramex a refusé la connexion. Vérifiez le nom d'utilisateur, le mot de passe, le numéro de compte, le PIN, l'entité et le code pays auprès de votre responsable de compte Aramex.
Tarif dans une autre devise refusé : Aramex a répondu dans une devise autre que celle de votre boutique. Saisissez le Currency conversion rate, ou demandez à Aramex de répondre dans votre devise.
La taxe est facturée deux fois sur l'expédition : les totaux Aramex peuvent déjà inclure la TVA. Réglez le Tax status sur None.
Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs Aramex mis en cache.
Environnement de test Aramex (sandbox) : l'extension utilise l'Aramex Rate Calculator de production. Les développeurs peuvent modifier l'adresse de l'API avec le filtre vfd_armx_api_url. Les filtres vfd_armx_rate_request, vfd_armx_number_of_pieces et vfd_armx_volumetric_divisor permettent d'ajuster la requête, le nombre de pièces et le diviseur volumétrique.
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 toutes les données. 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 sont toujours supprimés. Les réglages, méthodes de zone, tarifs en cache et journaux 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 d'expédition.
Aramex est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Aramex ni approuvée par cette dernière.