VibeFox CTT 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 antérieures de PHP.
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. Vous avez besoin d'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 délivré par CTT pour votre intégration : demandez-le à votre contact e-commerce CTT. CTT décide aussi des fonctions de l'API (estimation du 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
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 retrouvez plus tard VibeFox CTT dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).
4. Renseignez la grille tarifaire (au moins une ligne Portugal ou * Default) et cliquez sur Save. Vous pouvez aussi renseigner les clés API de CTT et le Carrier ID, puis activer Live rates et Enable CTT point carrier (voir Configuration).
À l'installation, le module crée deux transporteurs. CTT (livraison à l'adresse du client, texte de délai de livraison CTT delivery to your address) est activé. CTT point / parcel locker (texte de délai de livraison Pickup at a CTT point or parcel locker) est désactivé jusqu'à ce que vous l'activiez. Les deux sont rattachés à la zone Portugal 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. N'y définissez pas de prix : le prix provient toujours du module.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox CTT > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Les prix et les conditions s'appliquent aux deux transporteurs CTT. Chaque enregistrement efface les réponses CTT mises en cache, y compris le jeton API et les listes de points CTT.
Des avertissements au-dessus des réglages signalent une grille tarifaire vide, un prix manquant pour le Portugal, des clés API incomplètes, un Carrier ID manquant, une devise de boutique autre que l'EUR sans taux de change, un échec de connexion à l'API CTT et un transporteur CTT supprimé. Les valeurs invalides sont signalées à l'enregistrement : un nombre invalide n'est pas enregistré, une destination inconnue ou une ligne en double dans la grille tarifaire est supprimée. Si l'unité de poids ou de dimension de votre boutique n'est pas reconnue par le module, un avertissement vous demande de définir les unités dans International > Localization (Local units).
Général
Enable/Disable : active ou désactive la livraison CTT à l'adresse du client. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.
Name : le nom du transporteur affiché au client lors du paiement, par exemple « CTT Expresso ». Par défaut : CTT. Obligatoire, 64 caractères maximum.
Tax status : None signifie que les prix sont définitifs. Taxable avec une règle de taxe signifie que PrestaShop ajoute cette taxe de livraison (par exemple la TVA) au-dessus des prix. Le choix est enregistré pour les deux transporteurs CTT.
Livraison dans un point CTT ou une consigne automatique
Le second transporteur CTT. Le client recherche des points CTT par code postal ou par ville et doit en choisir un avant de continuer. Il nécessite les clés API CTT et le Carrier ID. Sans eux, c'est un transporteur sans sélection de point.
Enable CTT point carrier : active ou désactive le transporteur de points CTT. C'est le même interrupteur que son statut dans Shipping > Carriers. Par défaut : désactivé.
CTT point carrier name : le nom de cette option lors du paiement. Par défaut : CTT point / parcel locker. Obligatoire, 64 caractères maximum.
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 figurant sur 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 affichées après l'enregistrement. La description du champ indique alors Saved - leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez les modifier. Cochez Remove the saved public and private key et enregistrez pour supprimer les deux.
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 apparaissent sous le champ, ceux qui prennent en charge les points CTT étant marqués (CTT points). Chiffres uniquement.
Live rates : le module demande à CTT le prix (estimation du 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 prix. CTT appelle ce prix une estimation. Par défaut : désactivé.
Service ID : facultatif. Lorsque CTT renvoie plusieurs services, celui qui porte ce ServiceId est utilisé. Laissez le champ vide pour utiliser le moins cher.
Exchange rate : les prix 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 avec dimensions utilisent les leurs. Les dimensions sont converties en cm et les poids en grammes à partir des unités de votre boutique.
Prix (le titre de la section affiche la devise par défaut de votre boutique)
Saisissez les prix 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, ce tableau fixe le prix. Lorsqu'ils sont activés, il sert de prix de repli.
Price table : une ligne par destination. Choisissez un pays, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) ou * Default (other destinations). Chaque ligne comporte un Price de base et des prix 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 prix de taille vide (ou 0) utilise le prix de base. Une ligne dont les deux champs sont vides masque le transporteur. La ligne Azores s'applique aux codes postaux portugais 9500-9999, la ligne Madeira (y compris Porto Santo) à 9000-9499. Sans elles, la ligne Portugal s'applique. Cliquez sur Add destination pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Les prix acceptent le point ou la virgule comme séparateur décimal. La grille est vide après l'installation.
Calculation : mode de calcul du prix de la grille.
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 transporteurs apparaissent. 0 signifie aucune limite.
Max weight (kg) : les transporteurs sont masqués au-delà de ce poids de panier. Par défaut : 30 (les colis CTT vont jusqu'à 30 kg). 0 signifie aucune limite. Min weight (kg) ne peut pas être supérieur à Max weight (kg) : les réglages ne sont pas enregistrés.
Minimum order amount : n'affiche les transporteurs que si le sous-total du panier (produits à expédier, après remises, 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 du panier (après remises, avant taxes) à partir duquel les transporteurs coûtent 0. Il ne s'applique qu'aux destinations qui ont un prix. Utilisé uniquement lorsque Free shipping est activé.
Disponibilité sans zones de livraison
En règle générale, les transporteurs sont proposés dans les zones de livraison auxquelles ils sont rattachés dans Shipping > Carriers.
Ignore shipping zones : propose les transporteurs dans les pays indiqués ci-dessous sans les rattacher à leur zone. Lorsque vous l'activez, les deux transporteurs sont rattachés à toutes les zones actives (y compris celles que vous créerez plus tard). Lorsque vous le désactivez, ils retrouvent les zones qu'ils avaient auparavant.
Countries : les pays de destination pour ce mode. Par défaut : Portugal. Laissez vide pour autoriser tous les pays. Utilisé uniquement lorsque Ignore shipping zones est activé. Les clients des zones auxquelles les transporteurs étaient rattachés auparavant sont toujours servis.
Avancé
Debug log : enregistre le calcul des prix et les appels à l'API CTT dans logs/vfd_ctt_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API CTT sont toujours enregistrées, même lorsque cette option est désactivée. Les clés, les jetons et les adresses des clients ne sont jamais enregistrés.
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 du module supprime ses réglages et ses transporteurs. Lorsqu'elle est désactivée, la désinstallation se contente de désactiver les transporteurs. Les commandes, y compris le point CTT choisi, ne sont jamais modifiées.
Fonctionnement lors du paiement
À l'étape de livraison, PrestaShop demande au module le prix de chaque transporteur CTT. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord Ignore shipping zones et ses pays, le poids du panier et le montant minimum de commande. Avec Live rates activé et une adresse complète, il 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 prix renvoyé. Sinon, ou lorsque CTT ne fournit pas de prix (erreur API, délai dépassé, pas de couverture, fonction non activée pour votre App ID), le prix provient de la grille. Si la livraison gratuite s'applique, le prix est de 0. Le prix est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.
Un prix 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 en échec est mémorisée pendant 5 minutes, pour que le paiement n'attende pas CTT à chaque actualisation. Le délai d'attente de l'API est de 12 secondes. Les erreurs de l'API n'atteignent jamais le client : le prix de la grille est utilisé, ou le transporteur est masqué si la destination n'a pas de prix.
Si vous modifiez un transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.
Une fois les clés API renseignées, le module envoie à CTT l'adresse de livraison, les poids et dimensions des produits ainsi que l'URL de votre boutique, afin d'obtenir un prix ou les points CTT les plus proches.
Le module ne crée pas d'envois, 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 réglages API pour les deux transporteurs.
Points de retrait
Lorsque le client sélectionne le transporteur de points CTT, 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 ou touche Entrée) et en choisir un dans la liste. Le choix est immédiatement enregistré dans le panier. 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'étape de livraison, le module vérifie à nouveau le point côté serveur. Sans point, le client voit Please select a CTT point. ; avec un point absent de la liste CTT, il voit The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Les listes de points CTT sont mises en cache pendant 6 heures. 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 du point fonctionne avec les thèmes Classic et Hummingbird. Elle n'est active que lorsque la clé publique, la clé privée, l'App ID et le Carrier ID sont renseignés.
Le point choisi est enregistré dans la commande. Il apparaît sur la page de commande dans l'administration, dans le bloc CTT point (nom et ID), sur la page de confirmation de commande, dans le détail de commande du compte client, et dans l'e-mail de confirmation de commande sous la forme CTT point: à côté du nom du transporteur. Le nouvel e-mail de commande du module Mail alerts affiche également l'ID du point.
Sur la page de commande dans l'administration, 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. et un message privé de commande CTT point changed to: avec le nouveau point est ajouté. Modifier le point nécessite l'autorisation de modifier les commandes.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox CTT est le premier bloc de la page Modules > Module Manager > VibeFox CTT > 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 jusqu'à laquelle la licence est active 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: presta-shipping-ctt 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. 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, aucun des deux transporteurs CTT (livraison à l'adresse ou dans un point CTT) n'est affiché aux clients lors du paiement, et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : les transporteurs sont donc masqués aussi pour vous. 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, sur l'onglet Alerts. Les commandes existantes ne sont pas concerné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 suivant la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module 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 carrier) est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou que Ignore shipping zones est activé et que le pays est autorisé. 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 et que le Minimum order amount est atteint. Des produits peuvent aussi être limités à certains transporteurs sur la page du produit.
Le client ne peut pas choisir de point CTT : le sélecteur n'apparaît que sous le transporteur de points CTT, et seulement lorsque la clé publique, la clé privée, l'App ID et le Carrier ID sont renseignés. Vérifiez les avertissements au-dessus des réglages, activez Debug log et consultez le champ Log sur la page du module.
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 au-dessus des réglages 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'est pas en euros, renseignez Exchange rate.
La connexion à l'API CTT a échoué : l'avertissement au-dessus des réglages indique l'erreur. Vérifiez les clés et l'App ID. Le module réessaie automatiquement après quelques minutes.
Prix avec ou sans TVA : avec Tax status sur une règle Taxable, PrestaShop ajoute la taxe de livraison au prix. Avec None, le prix est définitif.
Les prix semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les réponses CTT mises en cache.
La page indique qu'un transporteur CTT est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. Une réinitialisation conserve les réglages et l'état activé ou désactivé des deux transporteurs.
Pour les développeurs : l'adresse de l'API CTT peut être modifiée avec la clé de configuration vfd_ctt_API_URL.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox CTT et choisissez Uninstall. La clé de licence, le statut de la licence, les réponses CTT mises en cache et le jeton API sont toujours supprimés. Si Remove data on uninstall est activé, les deux transporteurs sont supprimés (les commandes conservent leur historique), ainsi que les réglages, le journal et les points CTT des paniers qui ne sont jamais devenus des commandes. S'il est désactivé, les transporteurs sont seulement désactivés et tous les réglages sont conservés. Réinstaller le module rend à chaque transporteur l'état activé ou désactivé qu'il avait. Les points CTT enregistrés dans les commandes sont toujours conservés.
CTT est une marque appartenant à son propriétaire respectif. Ce module n'est ni affilié à CTT ni approuvé par CTT.