VibeFox Aramex 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 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 gestionnaire de compte Aramex ou consultez l'Aramex Developers Solution Center sur le site d'Aramex. Il vous faut six valeurs : nom d'utilisateur de l'API (généralement une adresse e-mail), mot de passe, numéro de compte, PIN du compte, entité du compte (par exemple DXB) et code pays du compte (par exemple AE). Si vous n'utilisez que 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 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échargement terminé, cliquez sur Configure, ou trouvez plus tard VibeFox Aramex dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Choisissez le mode de calcul des frais de livraison, remplissez les sections correspondantes (voir Configuration) et cliquez sur Save.

À l'installation, le module crée le transporteur Aramex avec le texte de délai de livraison Courier delivery. Le transporteur est associé à toutes les zones 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 Aramex > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les tarifs Aramex mis en cache.

Général

Enable Aramex: active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title: le nom du transporteur affiché dans le panier et lors du paiement. Par défaut : Aramex. Obligatoire.

Shipping cost: mode de calcul du prix.

La raison de l'absence de tarif en temps réel est consignée 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 de l'API Aramex, généralement une adresse e-mail.

Password: votre mot de passe de l'API Aramex. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Account number: votre numéro de compte client Aramex.

Account PIN: le PIN de votre compte Aramex. Comme le mot de passe, il n'est plus affiché après l'enregistrement.

Account entity: le code d'entité (bureau) de votre compte Aramex, 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 coté comme Domestic. Tous les autres envois sont coté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 dans le 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 (un tiers). Généralement Prepaid.

API weight unit: l'unité envoyée à Aramex, KG ou LB. Les poids et dimensions des produits sont convertis depuis les unités 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 par défaut 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 par défaut de votre boutique). Laissez ce champ vide pour rejeter ces tarifs, afin qu'un client ne soit jamais facturé dans la mauvaise devise.

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, il s'agit du 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 depuis l'adresse de la boutique dans Shop Parameters > Contact > Stores.

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 par défaut de votre boutique, hors taxes. Cliquez sur Add row pour ajouter un pays et sur l'icône de corbeille pour en supprimer un. Utilisez * comme code pays pour tous les autres pays. Les pays sans prix (en l'absence de ligne *) ne reçoivent aucun tarif fixe, donc le transporteur est masqué pour eux.

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 par envoi.

Conditions

Minimum weight: masque le transporteur lorsque le panier pèse moins, en kg. 0 signifie aucune limite.

Maximum weight: masque le transporteur lorsque le panier pèse plus, en kg. Par défaut : 100. 0 signifie aucune limite.

Minimum order amount: n'affiche le transporteur que lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping: activez la livraison Aramex gratuite à partir du montant ci-dessous.

Free shipping from: le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.

Tax: la règle de taxe du transporteur, ou No tax. Les tarifs Aramex en temps réel peuvent déjà inclure la TVA. Dans ce cas, choisissez No tax pour ne pas facturer la taxe deux fois.

Countries: proposer Aramex uniquement pour ces pays de destination. Laissez vide pour autoriser tous les pays des zones du transporteur.

Avancé

Debug log: écrit les calculs de tarifs et les erreurs de l'API dans logs/vfd_armx_debug.log.php, dans le dossier du module. 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é.

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: si activé, la désinstallation du module supprime les réglages Aramex, le transporteur, les tarifs en cache et les journaux. Si désactivé, tout est conservé pour une réinstallation.

Fonctionnement lors du paiement

À l'étape de livraison, PrestaShop demande au module le prix Aramex. Seuls les produits physiques comptent : les produits virtuels n'ajoutent ni poids ni montant à la commande. Le module vérifie d'abord les conditions : pays autorisés, poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Aramex.

En mode fixe, le prix est pris dans le tableau. En modes temps réel, le module envoie à Aramex les adresses d'origine et de livraison, le poids facturable, le service et votre devise par défaut, puis utilise le total renvoyé. Un tarif en temps réel n'est demandé que si l'adresse de livraison comporte une ville ou un code postal. Le prix est calculé dans votre devise par défaut, puis affiché dans la devise du panier du client.

Chaque réponse est mise en cache pendant 1 heure, pour qu'un 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'expiration 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 transporteur est masqué, ou le prix fixe est utilisé en mode de repli. La raison est consignée dans le journal de débogage.

Si vous modifiez le 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 calcule uniquement les tarifs. Il 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 au client de choisir un bureau Aramex. Le colis est toujours envoyé à Aramex en une seule pièce.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Aramex est le premier bloc de Modules > Module Manager > VibeFox Aramex > Configure, 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 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-aramex 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 : celui 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Aramex n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester lors du paiement. Un rappel apparaît dans Modules > Module Manager, sous 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é à nouveau 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. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Aramex n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable Aramex est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et son groupe. Contrôlez Countries, les limites de poids et Minimum order amount. En mode fixe, vérifiez que le pays ou * a un prix. Les produits peuvent aussi être limités à certains transporteurs sur la page du produit.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez la page de paiement et consultez le champ Log sur la page du module. Il indique la raison : identifiants API manquants, code d'erreur Aramex, absence de ville d'origine, absence de ville ou de code postal de livraison, limite de poids ou de montant, ou tarif dans une autre devise. Avec Aramex live rates, fixed prices if the API fails, les clients reçoivent tout de même le prix fixe pendant que vous corrigez le problème.

Erreur ERR75 dans le journal : Aramex a rejeté 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 gestionnaire de compte Aramex.

Tarif dans une autre devise rejeté : Aramex a répondu dans une devise autre que votre devise par défaut. Saisissez Currency conversion rate ou demandez à Aramex de fournir son tarif dans votre devise.

La taxe est facturée deux fois sur la livraison : les totaux Aramex peuvent déjà inclure la TVA. Réglez Tax sur No tax.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs Aramex mis en cache.

La page indique que le transporteur Aramex 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 Aramex et choisissez Uninstall. La clé de licence, le statut de la licence et les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ainsi que les réglages et le journal. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module réactive le transporteur enregistré.

Aramex est une marque appartenant à son titulaire. Ce module n'est pas affilié à Aramex et n'est pas approuvé par Aramex.