VibeFox CTT for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

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). Dans 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 chez 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 des réglages affiche les transporteurs de votre compte une fois les clés enregistrées. Si vous utilisez uniquement la grille tarifaire et la livraison à domicile, 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_ctt dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox CTT, ou cliquez sur Settings sous le nom de l'extension dans la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Remplissez la grille tarifaire (au moins une ligne Portugal ou * Default). Vous pouvez aussi renseigner les clés API de CTT et le Carrier ID, puis activer Live rates (voir Configuration).

6. Dans WooCommerce > Settings > Shipping > Shipping zones, ouvrez ou créez une zone pour le Portugal et ajoutez VibeFox CTT. Dans les réglages de la méthode, choisissez le titre et le type de livraison. Ou activez Ignore shipping zones et choisissez les pays.

Configuration

Les prix, les clés API et les conditions se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox CTT. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone contient deux champs :

Title (zone): le nom de cette option au paiement dans cette zone. Laissez le champ vide pour utiliser le Name global.

Delivery: To the customer's address (par défaut) ou To a CTT point or parcel locker chosen at checkout. Un point CTT nécessite les clés API de CTT et le Carrier ID dans les réglages globaux. Ajoutez la méthode deux fois à une zone pour proposer côte à côte la livraison à domicile et la livraison dans un point CTT.

Les avertissements affichés au-dessus des réglages signalent un prix manquant pour le Portugal, des clés API incomplètes, un Carrier ID manquant, une devise de boutique sans taux de change et un échec de connexion à l'API CTT. À chaque enregistrement des réglages, les réponses CTT mises en cache sont effacées.

Général

Enable/Disable: active ou désactive la méthode dans toutes les zones à la fois.

Name: le nom de la méthode de livraison affiché au paiement, par exemple « CTT Expresso ». Par défaut : CTT. Le Title d'une zone le remplace.

Tax status: Taxable ajoute la taxe de livraison WooCommerce (par exemple l'IVA) au prix, None signifie que le prix est définitif.

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 issue 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.

App ID (X-APPID): la clé d'application attribuée par CTT pour votre intégration.

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 enregistrées, les transporteurs de votre compte sont listés sous le champ, ceux qui prennent en charge les points CTT étant marqués.

Live rates: 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 vide pour utiliser le moins cher.

Exchange rate: les prix de CTT sont en euros. Si la devise 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 ce taux, 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 indique la devise de votre boutique)

Saisissez les prix de votre contrat CTT ou de la liste de prix publique de CTT, dans la devise de votre boutique. Lorsque les tarifs en temps réel sont désactivés, cette grille fixe le prix. Lorsqu'ils sont activés, elle sert de solution 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 prix de base (Price) 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 prix sont vides masque la méthode. La ligne Açores s'applique aux codes postaux portugais 9500-9999 ; la ligne Madère (y compris Porto Santo), aux codes 9000-9499. Sans elles, la ligne Portugal s'applique. Cliquez sur + Add destination pour ajouter une ligne et sur la croix pour en supprimer une. Les prix acceptent le point ou la virgule décimale. Les lignes non valides sont signalées à l'enregistrement.

Calculation : la façon dont le prix 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 la méthode apparaisse. 0 signifie sans limite.

Max weight (kg): la méthode est masquée au-delà de ce poids de panier. Par défaut : 30 (les colis CTT vont jusqu'à 30 kg). 0 signifie sans limite.

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

Excluded shipping classes: masque la méthode lorsqu'un article du panier appartient à l'une de ces classes d'expédition WooCommerce.

Livraison gratuite

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

Free shipping from: le sous-total du panier (après remises, avant taxes) à partir duquel cette méthode coûte 0. Cela ne s'applique que lorsque la méthode a un prix. Utilisé uniquement lorsque Free shipping est activé.

Disponibilité sans zones de livraison

Ignore shipping zones: propose la méthode dans les pays indiqués ci-dessous lorsque la zone du client ne la contient pas.

Countries: les pays de destination pour ce mode. Par défaut : Portugal. Laissez vide pour utiliser tous les pays vers lesquels vous livrez. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log: consigne le calcul des prix et les appels à l'API CTT dans WooCommerce > Status > Logs, source vfd-ctt. Les erreurs de l'API CTT sont toujours consignées, même lorsque cette option est désactivée. Les clés, les jetons et les adresses des clients ne sont jamais consignés.

Remove data on uninstall: lorsqu'elle est activée, la suppression de l'extension supprime ses réglages et ses méthodes de zone. La désactivation de l'extension ne supprime jamais de données. Les commandes ne sont jamais modifiées.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un prix à l'extension. L'extension vérifie d'abord le poids du panier, le montant minimum de commande et les classes d'expédition exclues. Avec Live rates activé et une adresse 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 affiche 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 0.

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 échouée 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.

La méthode fonctionne sur le paiement classique ainsi que sur les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

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

L'extension 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 toute la boutique. Les zones diffèrent par leur titre et leur type de livraison.

Points relais

Pour une méthode de zone dont Delivery est un point CTT, un champ de recherche et une liste apparaissent sous la méthode au paiement. L'adresse de livraison est recherchée automatiquement. Le client peut rechercher d'autres points CTT par code postal ou par ville et doit en choisir un avant de passer commande. Cela est aussi vérifié côté serveur. Les listes de points CTT sont mises en cache pendant 6 heures. Si CTT est injoignable, le client voit un message et peut réessayer plus tard ou choisir un autre mode de livraison.

Le point choisi est enregistré dans la commande. Il apparaît dans l'administration de la commande sous l'adresse de livraison, sur la page de commande reçue, dans My account > Orders et dans les e-mails de commande (HTML et texte brut) sous le libellé CTT point.

Dans l'administration de la commande, cliquez sur Change à côté du point CTT, recherchez par code postal ou par ville et choisissez un autre point. La modification est enregistrée immédiatement et ajoute une note à la commande.

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 CTT. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, CTT n'est pas affiché aux clients au 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 Plugins 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. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

CTT n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et le pays autorisé). Vérifiez que la destination a une ligne dans la grille tarifaire (ou une ligne * Default), que le poids du panier est compris entre Min weight et Max weight, que le Minimum order amount est atteint et qu'aucun produit n'appartient à une classe d'expédition exclue.

Le client ne peut pas choisir de point CTT : le sélecteur n'apparaît que pour une méthode de zone dont Delivery est un point CTT, et seulement lorsque la clé publique, la clé privée, l'App ID et le Carrier ID sont renseignés. Activez le Debug log et consultez WooCommerce > Status > Logs.

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. Consultez les avertissements au-dessus des réglages et le journal. La 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 le Exchange rate.

La connexion à l'API CTT a échoué : l'avertissement au-dessus des réglages affiche l'erreur. Vérifiez les clés et l'App ID. L'extension réessaie automatiquement au bout de quelques minutes.

Prix avec ou sans TVA : avec Tax status sur Taxable, WooCommerce ajoute la taxe de livraison au prix. Avec None, le prix est définitif.

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, puis cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé sur le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier état 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 l'état de licence de cette extension sont toujours supprimés, de même que les réponses CTT mises en cache et le jeton API. Les réglages et les méthodes de zone 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, y compris le point CTT choisi, ne sont jamais modifiées, et les commandes existantes conservent leurs lignes de livraison.

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