VibeFox Aramex for OpenCart — Aide

Prérequis

OpenCart: 3.0.x (testé avec 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

PHP: 8.0 ou ultérieur.

Compte Aramex (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API Aramex Rate Calculator. Aramex donne accès à l'API à ses titulaires de compte. Demandez à 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, code 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 d'un compte Aramex.

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_aramex-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_aramex.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_aramex-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'installateur, 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 Aramex et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de 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. Choisissez le mode de calcul du coût de livraison, remplissez les sections correspondantes (voir Configuration), activez Enable Aramex et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_aramex.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 Aramex, 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, le mode de livraison reste désactivé tant que vous n'avez pas activé Enable Aramex et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages Aramex que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Aramex > Edit. Les sections sont listées à gauche. Un seul bouton Save, en bas, enregistre toute la page sans la recharger. Chaque enregistrement vide aussi les tarifs Aramex en cache. Si une valeur est incorrecte, rien n'est enregistré et la page indique la raison, par exemple Enter a method title (1 to 64 characters)., un message indiquant qu'un champ doit être un nombre, ou The account country code must have 2 letters, e.g. AE. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode à une zone géographique et à certains pays dans Conditions.

Enable Aramex: affiche ou masque Aramex au moment du paiement. Par défaut : désactivé.

Method title: le nom du mode de livraison affiché au client dans le panier et au moment 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 écrite dans le journal de débogage. Elle n'est jamais affichée au client.

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

Compte API Aramex (requis 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. Le vider efface aussi le mot de passe enregistré.

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

Account number: le numéro de client de votre compte Aramex. Le vider efface aussi le code PIN enregistré.

Account PIN: le code 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) 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 (documents de moins de 0,5 kg), 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 (shipper pays) (par défaut), Collect (receiver pays) ou Third party. Généralement Prepaid.

API weight unit: l'unité envoyée à Aramex : Kilograms (KG) (par défaut) ou Pounds (LB). Les poids des produits sont convertis depuis leur classe de poids, et les dimensions depuis leur classe de longueur. 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 s'applique aussi aux 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 malgré tout dans une autre devise, le tarif est multiplié par ce nombre (1 unité de la devise d'Aramex = X unités de la devise par défaut de votre boutique). Laissez le champ vide pour rejeter ces tarifs, afin qu'un client ne soit jamais débité dans une devise erronée.

Expédition depuis (utilisé pour les tarifs en temps réel)

Origin country: le pays depuis lequel vous expédiez. La première option, Store country, utilise le pays de votre boutique.

Origin city: la ville depuis laquelle vous expédiez. Aramex l'exige. L'adresse de boutique dans OpenCart est un texte libre : la ville n'en est donc jamais reprise, saisissez-la ici.

Origin state / emirate: facultatif.

Origin postcode: facultatif.

Si le pays d'origine est le pays de votre boutique, un état vide est repris de la région de votre boutique dans System > Settings > Store > Local.

Prix fixes (utilisés lorsque Shipping cost est sur Fixed prices, et en secours pour les tarifs en temps réel)

Price per country: une liste de pays et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add country pour ajouter une ligne et sur le bouton × pour en retirer une. Choisissez * All other countries pour un prix appliqué à tout pays sans ligne propre. Les pays sans prix (lorsqu'il n'y a pas de ligne *) n'ont pas de tarif fixe : le mode est donc masqué pour eux.

Fixed price applies: Per order (par défaut) facture le prix une seule fois. Per item (price × quantity) 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 en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Maximum weight (kg): masque le mode au-dessus de ce poids de panier. Par défaut : 100. 0 signifie aucune limite. Si vous laissez le champ vide, 100 kg sont utilisés.

Minimum order amount: n'afficher le mode que si le sous-total des produits à expédier (après le coupon, hors taxes) atteint ce montant. Laissez le champ vide pour l'afficher toujours.

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

Free shipping from: le sous-total des produits à expédier (après le coupon, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.

Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Les tarifs Aramex en temps réel incluent parfois déjà la TVA. Dans ce cas, choisissez No tax pour ne pas appliquer la taxe deux fois sur la livraison.

Geo zone: proposer Aramex uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Countries: proposer Aramex uniquement pour ces pays de destination. Laissez le champ vide pour autoriser tous les pays. Cette limite s'applique en complément de Geo zone.

Avancé

Debug log: écrit les calculs de tarifs et les erreurs de l'API dans storage/logs/vfd_armx_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les mots de passe, le code PIN et les adresses des clients ne sont jamais journalisés. Désactivez le journal une fois terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_armx_debug.old.log.php et un nouveau journal commence.

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: lorsqu'il est activé, la désinstallation de l'extension supprime les réglages Aramex, les tarifs en cache et le journal. Désactivé (par défaut), ils sont conservés pour une réinstallation.

Importation / exportation

Exporter : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le mot de passe et le code PIN ne sont pas exportés.

Importer : collez le JSON exporté précédemment et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Le mot de passe et le code PIN enregistrés sont conservés.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Aramex. Si une Geo zone est définie et que l'adresse se trouve en dehors, Aramex n'est pas proposé. Seuls les produits dont Requires Shipping est sur Yes comptent : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite les conditions : pays autorisés, poids du panier et montant minimum de commande. Le montant de la commande est le prix des produits à expédier, après réduction du coupon et avant taxes. Les cartes-cadeaux, les points de fidélité et le crédit de boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Aramex.

En mode prix fixes, le prix est pris dans le tableau. Dans les modes en temps réel, l'extension envoie à Aramex les adresses d'expédition 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, arrondi à ses décimales, puis affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

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, pour 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 secours. La raison est écrite dans le journal de débogage.

L'extension calcule uniquement 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. Elle n'ajoute rien aux commandes : la commande affiche le nom du mode et le coût de livraison comme pour tout autre mode de livraison OpenCart. Le colis est toujours envoyé à Aramex comme une seule pièce.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Aramex dans la fenêtre Shipping method options. Le mode fonctionne de la même manière que sous OpenCart 3.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Aramex est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox Aramex > 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) et 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 se trouvent la ligne Product: opencart-shipping-aramex et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation de modification pour l'extension peuvent changer 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 dans 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, le mode de livraison Aramex n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode 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

Aramex n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Aramex est activé. Contrôlez Geo zone, Countries, les limites de poids et Minimum order amount. En mode prix fixes, vérifiez que le pays ou * All other countries a un prix. Vérifiez que les produits ont Requires Shipping sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Il indique la raison : identifiants API manquants, code d'erreur Aramex, aucune ville d'origine, aucune ville ou aucun code postal de livraison, une limite de poids ou de montant, ou un 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 corrigez 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 code 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 la devise par défaut de votre boutique. Saisissez Currency conversion rate, ou demandez à Aramex de répondre 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 class sur No tax.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs Aramex en cache.

La page affiche "Warning: You do not have permission to modify VibeFox Aramex!" : 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_aramex (OpenCart 3) ou extension/vfd_aramex/shipping/vfd_aramex (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API Aramex peut être remplacée avec le réglage vfd_armx_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 Aramex. OpenCart réinitialise toujours Enable Aramex, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Aramex 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. 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 Aramex dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet envoyé.

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