VibeFox CTT for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Compte e-commerce CTT (uniquement pour les tarifs en temps réel et les points CTT) : les tarifs en temps réel et la livraison dans un point CTT utilisent l'API e-commerce de CTT. Il vous faut un compte e-commerce CTT sur enviosecommerce.ctt.pt (pour les clients sous contrat CTT Expresso, ou demandez une proposition à CTT). Sur la page de gestion des clés de ce compte, créez une paire de clés publique et privée. L'App ID (X-APPID) est attribué par CTT pour votre intégration : demandez-le à votre contact e-commerce CTT. CTT décide aussi des fonctions de l'API (estimation de coût, points CTT) que votre App ID peut utiliser. Enfin, il vous faut le Carrier ID de CTT dans votre compte. La page de configuration affiche les transporteurs de votre compte une fois les clés enregistrées. Si vous n'utilisez que la grille tarifaire et la livraison à l'adresse, vous n'avez pas besoin de clés API.

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_ctt-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_ctt.ocmod.zip. N'installez que 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_ctt-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 CTT et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page de configuration.

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. Renseignez la grille tarifaire (au moins une ligne Portugal ou * Default), activez Enable/Disable et/ou Enable CTT point option, puis cliquez sur Save. Vous pouvez également renseigner les clés API de CTT, l'App ID et le Carrier ID, puis activer Live rates (voir Configuration).

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_ctt.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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 sur Install (le bouton vert +) à côté de celui-ci.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox CTT, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence et les paramètres comme aux étapes 4 et 5 pour OpenCart 3. La page de configuration et ses champs sont identiques dans les deux versions.

Après la première installation, les deux modes de livraison sont désactivés tant que vous n'en activez pas un et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation sans suppression des données, les paramètres conservés sont réutilisés et l'extension est de nouveau activée si l'une des options était activée.

Configuration

Tous les paramètres se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox CTT > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Les tarifs et les conditions s'appliquent aux deux options CTT. Chaque enregistrement efface les réponses CTT mises en cache : le jeton API, les transporteurs, les tarifs et les listes de points CTT. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les paramètres.

Des avertissements en haut de la page signalent une grille tarifaire vide, un tarif manquant pour le Portugal, des clés API incomplètes alors que les tarifs en temps réel ou l'option de point CTT sont activés, un Carrier ID manquant, une devise de boutique autre que l'EUR sans taux de change, un échec de connexion à l'API CTT, et une boutique sans classe de poids en kg ou classe de longueur en cm (les unités des produits sont alors converties selon leur nom d'unité ; vérifiez System > Localisation > Weight Classes et Length Classes). Si un nom est vide, invalide ou dépasse 64 caractères, si Min weight (kg) est supérieur à Max weight (kg), ou si Sort Order, la classe de taxe ou la zone géographique est invalide, la page affiche une erreur et rien n'est enregistré. Les autres valeurs invalides sont signalées comme avertissements et le reste est enregistré : un nombre invalide n'est pas enregistré, un taux de change égal ou inférieur à 0 est effacé, une taille de produit invalide revient à la valeur par défaut, une destination inconnue ou une ligne en double dans la grille tarifaire est supprimée, un tarif de grille invalide reste vide.

Général

L'extension propose jusqu'à deux options au paiement : livraison CTT à l'adresse du client et livraison dans un point CTT ou une consigne automatique. Les tarifs et les conditions s'appliquent aux deux.

Enable/Disable: active ou désactive la livraison CTT à l'adresse du client.

Name: le nom du mode de livraison affiché au client lors du paiement, par exemple « CTT Expresso ». Par défaut : CTT. Jusqu'à 64 caractères.

Tax class: la classe de taxe du coût de livraison. OpenCart ajoute cette taxe (par exemple IVA) aux tarifs. --- None --- signifie que les tarifs sont définitifs. Utilisé par les deux options.

Sort Order: la position de CTT parmi les modes de livraison proposés au paiement. Un nombre entier.

Livraison dans un point CTT ou une consigne automatique

La seconde option CTT. Le client recherche des points CTT par code postal ou par ville (l'adresse de livraison est recherchée automatiquement) et doit en choisir un avant de continuer. Elle nécessite les clés API de CTT et le Carrier ID. Sans eux, il s'agit d'une option sans sélection de point.

Enable CTT point option: propose la livraison dans un point CTT ou une consigne automatique. Par défaut : désactivé.

CTT point option name: le nom de cette option au paiement. Par défaut : CTT point / parcel locker. Jusqu'à 64 caractères.

API e-commerce CTT (tarifs en temps réel, points CTT) (facultatif ; sans clés, la grille tarifaire est utilisée)

Public key: la clé publique de la page de gestion des clés de votre compte e-commerce CTT.

Private key: la clé secrète utilisée pour signer chaque requête (HMAC-SHA256). Elle n'est jamais envoyée à CTT ni écrite dans le journal.

Les deux clés ne sont plus jamais affichées après l'enregistrement. La description du champ indique alors Saved - leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. Cochez Remove the saved public and private key et enregistrez pour supprimer les deux clés. Lorsqu'aucune clé n'est enregistrée, la section affiche No keys saved.

App ID (X-APPID): la clé d'application délivrée par CTT, envoyée dans l'en-tête X-APPID.

Carrier ID: l'identifiant du transporteur CTT dans votre compte, utilisé pour les tarifs en temps réel et la recherche de points CTT. Une fois les clés et l'App ID enregistrés, les transporteurs de votre compte sont listés sous le champ (Carriers of your CTT account:), ceux qui prennent en charge les points CTT étant marqués CTT points. Chiffres uniquement.

Live rates: demande à CTT le tarif (estimation de coût) dès que le client a saisi la rue, le code postal et la ville. La grille tarifaire est utilisée tant que l'adresse est incomplète et chaque fois que CTT ne fournit pas de tarif. CTT appelle ce tarif une estimation. Par défaut : désactivé.

Service ID: facultatif. Lorsque CTT renvoie plusieurs services, celui qui porte ce ServiceId est utilisé. Laissez vide pour utiliser le moins cher.

Exchange rate: les tarifs CTT sont en euros. Si la devise par défaut de votre boutique est différente, indiquez combien d'unités de la devise de votre boutique valent 1 unité de la devise CTT. Sans cette valeur, les tarifs en temps réel dans une autre devise ne sont pas utilisés et la grille tarifaire s'applique.

Default product size (cm): longueur x largeur x hauteur envoyées à CTT pour les produits sans dimensions. Par défaut : 30x20x15. Les produits qui ont des dimensions utilisent les leurs. Les dimensions sont converties en cm et les poids en grammes à partir des classes de longueur et de poids des produits.

Tarifs (le titre de la section affiche la devise par défaut de votre boutique)

Saisissez les tarifs de votre contrat CTT ou de la grille publique de CTT disponible sur ctt.pt, dans la devise par défaut de la boutique, hors taxes. Lorsque les tarifs en temps réel sont désactivés, cette grille fixe le tarif. Lorsqu'ils sont activés, elle sert de solution de repli.

Price table: une ligne par destination. Choisissez un pays, Portugal - Azores, Portugal - Madeira ou * Default (other destinations). Chaque ligne comporte un Price de base et des tarifs facultatifs pour les tailles XS (jusqu'à 1 kg), S (jusqu'à 2 kg), M (jusqu'à 3 kg), L (jusqu'à 5 kg) et XL (au-delà de 5 kg). Un tarif de taille vide (ou égal à 0) utilise le tarif de base. Une ligne dont les deux tarifs sont vides masque le mode de livraison. La ligne Azores s'applique aux codes postaux portugais 9500-9999, la ligne Madeira aux codes 9000-9499. Sans elles, la ligne Portugal s'applique. Cliquez sur Add destination pour ajouter une ligne et sur le bouton × pour en supprimer une. Les tarifs acceptent le point ou la virgule comme séparateur décimal. La grille est vide après l'installation.

Calculation: la manière dont le tarif de la grille est déterminé.

Un tarif CTT en temps réel s'applique toujours à l'envoi complet.

Conditions

Min weight (kg): le poids minimum du panier pour que les options CTT apparaissent. 0 signifie aucune limite.

Max weight (kg): les options CTT sont masquées au-delà de ce poids de panier. Par défaut : 30 (les colis CTT pèsent jusqu'à 30 kg). 0 signifie aucune limite. Min weight (kg) ne peut pas être supérieur à Max weight (kg).

Minimum order amount: affiche les options CTT uniquement lorsque le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint ce montant. Laissez vide pour les afficher en permanence.

Livraison gratuite

Free shipping: active la livraison CTT gratuite à partir du montant indiqué ci-dessous.

Free shipping from: le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel les options CTT coûtent 0. Ne s'applique qu'aux destinations ayant un tarif. Utilisé uniquement lorsque Free shipping est activé.

Disponibilité

En règle générale, les options CTT sont proposées dans la zone géographique sélectionnée ci-dessous. All Zones signifie partout. Avec Ignore shipping zones, la zone géographique n'est pas vérifiée et c'est Countries qui décide.

Geo Zone: la zone géographique de l'adresse de livraison. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones: ne pas vérifier la zone géographique ; proposer CTT dans les pays ci-dessous.

Countries: les pays de destination pour ce mode. Par défaut : Portugal. Laissez vide pour autoriser tous les pays. Utilisé uniquement avec Ignore shipping zones.

Avancé

Debug log: enregistre le calcul des tarifs et les appels à l'API CTT dans storage/logs/vfd_ctt_debug.log.php (sous OpenCart 4, dans system/storage/logs/vfd_ctt_debug.log.php). Ce fichier ne peut pas être lu depuis le web. Les erreurs de l'API CTT sont toujours journalisées, même lorsque cette option est désactivée. Les clés, les jetons et les adresses des clients ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_ctt_debug.old.log.php et un nouveau journal est créé.

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

Remove data on uninstall: lorsqu'elle est activée, la désinstallation de l'extension supprime les paramètres, le journal et les points CTT des paiements non finalisés. Lorsqu'elle est désactivée (par défaut), les paramètres sont conservés pour une nouvelle installation. Les commandes, y compris le point CTT choisi, ne sont jamais modifiées.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les paramètres dans un fichier JSON. Les clés publique et privée ne sont pas exportées.

Import: collez un JSON exporté précédemment et cliquez sur Import pour restaurer les paramètres, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Les clés enregistrées sont conservées.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif CTT. Avec Ignore shipping zones, CTT n'est proposé que pour un pays de Countries (vide = tous les pays) ; sinon, si une Geo Zone est définie, uniquement pour les adresses situées dans cette zone. Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie le poids du panier et le montant minimum de commande. Lorsque Live rates est activé et que l'adresse est complète, elle envoie à CTT l'adresse de livraison et, pour chaque ligne du panier, la quantité, le poids en grammes et les dimensions en cm, puis utilise le tarif renvoyé. Sinon, ou lorsque CTT ne fournit pas de tarif (erreur API, délai dépassé, zone non couverte, fonction non activée pour votre App ID), le tarif provient de la grille. Si la livraison gratuite s'applique, le tarif est de 0. Les deux options reçoivent le même tarif. Le tarif est calculé dans la devise par défaut de votre boutique, arrondi selon ses décimales, puis affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Un tarif CTT est mis 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 mémorisée pendant 5 minutes, pour que le paiement n'attende pas CTT à chaque actualisation. Le jeton API, la liste des transporteurs et les listes de points CTT sont également mis en cache, au plus pour la durée de vie du cache d'OpenCart (1 heure par défaut). Les erreurs de l'API n'atteignent jamais le client : le tarif de la grille est utilisé, ou le mode de livraison est masqué si la destination n'a pas de tarif.

Lorsque les clés API sont renseignées, l'extension envoie à CTT l'adresse de livraison, les poids et dimensions des produits ainsi que l'URL de votre boutique, pour obtenir un tarif ou les points CTT les plus proches.

L'extension ne crée pas d'expéditions, n'imprime pas d'étiquettes, ne demande pas d'enlèvements, ne fournit pas de numéros de suivi et n'affiche pas de carte des points CTT. Il existe une seule grille tarifaire et un seul jeu de paramètres API pour les deux options.

Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit une option CTT dans la fenêtre Shipping method options. Les tarifs sont les mêmes que sous OpenCart 3.

Points de retrait

Lorsque le client sélectionne l'option de point CTT à l'étape du mode de livraison, un champ de recherche et une liste apparaissent dessous. Le code postal de l'adresse de livraison est renseigné et recherché automatiquement. Le client peut rechercher d'autres points CTT par code postal ou par ville (bouton Search) et en choisir un dans la liste. Le choix est enregistré immédiatement. Seul un point figurant dans la liste CTT pour cette recherche est accepté.

Un point doit être choisi avant que le client puisse continuer. Lorsque le client clique sur Continue, l'extension vérifie le point sur le serveur. Sans point, le client voit Please select a CTT point. ; avec un point absent de la liste CTT, The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Si CTT est injoignable, le client voit CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

La sélection de point n'est active que lorsque la clé publique, la clé privée, l'App ID et le Carrier ID sont renseignés. Elle est conçue pour le thème par défaut d'OpenCart et son paiement ; d'autres thèmes peuvent nécessiter des modifications.

Sous OpenCart 4, le champ de recherche et la liste apparaissent dans la fenêtre Shipping method options, sous l'option de point CTT. Le bouton Continue de la fenêtre ne permet pas de continuer sans point valide, avec les mêmes messages. OpenCart 4 conserve une seule commande pour le paiement et la met à jour à chaque nouvelle confirmation du client ; le point CTT de la commande est mis à jour avec elle.

Le point choisi est ajouté au mode de livraison de la commande, par exemple CTT point / parcel locker: .... Le client le voit ainsi dans l'historique de ses commandes et dans les e-mails de commande ; il est imprimé sur la facture et affiché dans Sales > Orders. La page de confirmation de commande d'OpenCart n'affiche pas le mode de livraison.

Sur la page de commande de l'administration, le panneau CTT point, au-dessus de l'historique, affiche le nom et l'identifiant du point. Pour le modifier, saisissez un code postal ou une ville sous Change CTT point, cliquez sur Search, choisissez un point et cliquez sur Save. La page affiche CTT point updated., le texte du mode de livraison de la commande est mis à jour, et une entrée d'historique CTT point changed to: ... est ajoutée sans notifier le client. Modifier le point nécessite l'autorisation de modification des commandes (sale/order) et les paramètres API. Le panneau s'affiche aussi pour les commandes CTT lorsque l'extension est désactivée.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox CTT est le premier bloc de Extensions > Extensions > Shipping > VibeFox CTT > Edit, au-dessus des paramètres. 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 supprimer la clé de cette boutique. En dessous figurent la ligne Product: opencart-shipping-ctt et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de 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 issue de la configuration d'OpenCart. Supprimer 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, CTT n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de livraison dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sous 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. Une fois la page Edit ouverte une fois, 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 concerné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 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 la licence.

Dépannage

CTT n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable (ou Enable CTT point option) est activé. Vérifiez Geo Zone, ou Ignore shipping zones et Countries. Vérifiez que la destination a une ligne dans la grille tarifaire (ou une ligne * Default), que le poids du panier se situe entre Min weight et Max weight, que le Minimum order amount est atteint et que les produits ont Requires Shipping réglé sur Yes.

Le client ne peut pas choisir de point CTT : le sélecteur n'apparaît que sous l'option de point CTT, et uniquement lorsque la clé publique, la clé privée, l'App ID et le Carrier ID sont renseignés. Vérifiez les avertissements en haut de la page de configuration, activez le Debug log et consultez le champ Log sur la page de l'extension.

Les tarifs en temps réel n'apparaissent pas : la grille tarifaire est utilisée tant que le client n'a pas saisi la rue, le code postal et la ville. Vérifiez les avertissements et le journal. Une réponse « 405 » signifie que la fonction n'est pas activée pour votre App ID : demandez-le à CTT. Dans une boutique qui n'utilise pas l'euro, renseignez Exchange rate.

La connexion à l'API CTT a échoué : l'avertissement en haut de la page de configuration affiche l'erreur. Vérifiez les clés et l'App ID. L'extension réessaie automatiquement après quelques minutes.

Tarifs avec ou sans TVA : avec une Tax class sélectionnée, OpenCart ajoute cette taxe au tarif. Avec --- None ---, le tarif est définitif.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela efface les réponses CTT mises en cache.

La page affiche « Warning: You do not have permission to modify VibeFox CTT! » : votre groupe d'utilisateurs administrateurs ne peut peut-être que consulter les paramètres. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_ctt (OpenCart 3) ou extension/vfd_ctt/shipping/vfd_ctt (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API CTT peut être remplacée par le paramètre vfd_ctt_api_url (pour les tests) ; il n'a pas de champ sur la page de configuration.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox CTT. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours le statut de l'extension, Sort Order, Tax class et Geo Zone. Les réponses CTT mises en cache et le jeton API sont toujours supprimés. Si Remove data on uninstall est activé, les paramètres, le journal et les points CTT des paiements n'ayant jamais abouti à une commande sont également supprimés. S'il est désactivé, les autres paramètres sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les points CTT enregistrés dans les commandes sont toujours conservés, et les commandes existantes gardent leur mode de livraison et leur coût.

Sous OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox CTT dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet téléversé.

CTT est une marque déposée de son titulaire. Cette extension n'est pas affiliée à CTT et n'est pas approuvée par CTT.