VibeFox Correos CityPaq for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

Identifiants API Correos (uniquement pour la liste en direct des casiers) : la liste CityPaq de Correos lit les casiers actifs via l'API « terminals » de Correos. Sur le portail développeurs de Correos, ouvrez l'API « terminals » et cliquez sur Request access pour votre application. Correos approuve les demandes de ses clients professionnels et envoie un client ID et un client secret. Ils sont aussi affichés sous My applications sur le portail. Si les clients saisissent eux-mêmes le casier ou choisissent dans votre propre liste, vous n'avez pas besoin d'identifiants 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_correos_citypaq dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Correos CityPaq, ou cliquez sur Settings sous le nom de l'extension sur 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 et choisissez comment le client sélectionne le casier (voir Configuration).

6. Ajoutez VibeFox Correos CityPaq à la zone de livraison de l'Espagne dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne contient qu'un seul champ :

Title (zone) : le nom de cette option au paiement pour cette zone. Laissez vide pour utiliser le Name général.

Les avertissements affichés au-dessus des réglages indiquent quand la grille tarifaire ne contient aucune ligne utilisable, quand le choix du casier ne peut pas fonctionner (aucun casier dans votre liste, pas d'identifiants API) et quelle a été la dernière erreur de l'API Correos. Les prix et montants acceptent la virgule ou le point décimal.

Général

Les casiers CityPaq n'existent qu'en Espagne ; la méthode n'est donc jamais proposée pour d'autres pays.

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 client au paiement. Par défaut : Correos CityPaq.

Tax status : Taxable ajoute la taxe WooCommerce aux prix de la grille, None ne l'ajoute pas.

Prix (le titre de la section affiche la devise de votre boutique)

Price table : une ligne pour Spain (ES) et/ou une ligne par défaut *. Chaque ligne contient un Price de base et des prix facultatifs pour les tailles de colis 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 à 0 ou vide utilise le prix de base. Cliquez sur + Add row pour ajouter une ligne et sur la croix pour en supprimer une. Saisissez vos tarifs de contrat Correos dans la devise de la boutique. Sans ligne correspondante, la méthode est masquée. Les prix invalides et les lignes en double sont signalés à l'enregistrement.

Calculation type : la manière dont la taille du colis est déterminée.

Per order (size by the total cart weight): un seul prix pour tout le panier, choisi selon le poids total. C'est la valeur par défaut.

Per item (size by each item weight, multiplied by quantity): chaque produit reçoit le prix de sa propre taille, multiplié par sa quantité, et les prix sont additionnés.

Les poids des produits sont convertis en kg à partir de l'unité de poids de votre boutique (kg, g, lbs ou oz).

Conditions

Min weight (kg) : masque la méthode lorsque le panier est plus léger. 0 signifie sans limite.

Max weight (kg) : masque la méthode lorsque le panier est plus lourd. Par défaut : 30, car CityPaq accepte les colis 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 lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce, par exemple des articles encombrants qui ne rentrent pas dans un casier. L'extension ne vérifie pas les dimensions des colis.

Livraison gratuite

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

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

Choix du casier CityPaq

Locker selection : la manière dont le client choisit le casier avant de passer commande. Par défaut : le client saisit le casier.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): le client voit les casiers CityPaq actifs du code postal de l'adresse de livraison et peut rechercher un autre code postal à 5 chiffres. Lorsqu'un code postal n'a pas de casier, les casiers de la même zone, puis de la même province sont affichés, les codes postaux les plus proches en premier. Chaque casier affiche son nom, son adresse, son code postal, sa ville et ses horaires d'ouverture. Si la liste ne peut pas être chargée ou ne trouve rien, le client saisit le casier manuellement.

Customer enters the locker (code or address from the Correos finder): un champ obligatoire pour le code du casier (par exemple S0000213D) ou l'adresse, avec un lien vers le localisateur officiel CityPaq de Correos.

Customer chooses from my list of lockers (below): une liste déroulante obligatoire des casiers de My lockers. Les casiers proches du code postal du client sont affichés en premier.

Do not ask for a locker: aucune question sur le casier au paiement.

Si vous choisissez la liste Correos sans identifiants API, ou votre propre liste alors que My lockers est vide, le client est invité à saisir le casier manuellement.

My lockers : utilisé lorsque Locker selection est réglé sur votre liste. Un casier par ligne : CODE | Name | Address | Postal code | City. Le code et le nom sont obligatoires. Les lignes invalides et en double sont signalées à l'enregistrement.

Liste CityPaq de Correos (API) (utilisée uniquement avec la liste CityPaq de Correos)

La section contient un lien vers la page de l'API « terminals » sur le portail développeurs de Correos. Seule la liste des casiers est lue. Les prix proviennent toujours de la grille tarifaire.

API client ID : le client_id de votre application sur le portail développeurs de Correos.

API client secret : le client_secret de votre application sur le portail développeurs de Correos.

Lorsque vous modifiez les identifiants ou le choix du casier, les listes de casiers mises en cache sont effacées.

Disponibilité sans zones de livraison

Ignore shipping zones : propose CityPaq pour toute adresse espagnole, même si aucune zone de livraison ne contient cette méthode. Désactivé (recommandé) signifie que la méthode est proposée là où vous l'avez ajoutée à une zone de livraison.

Avancé

Debug log : écrit des lignes de débogage dans WooCommerce > Status > Logs, source vfd-correos-citypaq. Les erreurs de l'API Correos sont toujours journalisées, même lorsque cette option est désactivée. Les identifiants et les données personnelles ne sont jamais journalisés.

Remove data on uninstall : si cette option est activée, la suppression de l'extension efface ses réglages et ses méthodes de zone. La désactivation de l'extension ne supprime jamais rien. Les casiers enregistrés dans les commandes sont conservés.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison en Espagne, WooCommerce demande un tarif à l'extension. L'extension vérifie le poids du panier, le montant minimum de commande et les classes d'expédition exclues, trouve la ligne de prix pour l'Espagne (ou la ligne *) et la taille du colis, puis affiche le prix. Si la livraison gratuite s'applique, le prix est de 0.

Lorsque le client sélectionne CityPaq, le champ du casier apparaît sous la méthode. La commande ne peut pas être passée sans casier valide. Cette vérification est aussi faite côté serveur, y compris pour les commandes passées avec les blocs Panier et Paiement. Avec la liste Correos, un code de casier n'est accepté que si Correos l'a proposé à ce client, et son nom et son adresse sont repris de Correos. Le nombre de recherches de code postal par session client est limité. Une fois la limite atteinte, le client saisit le casier manuellement.

Une liste Correos est mise en cache pendant 12 heures par code postal. Une requête échouée est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Correos à chaque actualisation. Le délai d'expiration de l'API est de 12 secondes. Le client ne voit jamais l'erreur technique, seulement un bref message et le champ manuel.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne récupère pas de tarifs en direct auprès de Correos, n'affiche pas de carte, n'enregistre pas les envois à l'avance, n'imprime pas d'étiquettes, ne demande pas d'enlèvements et ne suit pas les colis. Créez l'envoi dans votre compte Correos à l'aide du casier enregistré dans la commande.

Points de retrait

Le casier choisi est enregistré dans la commande. Il est affiché dans l'administration de la commande sous l'adresse de livraison, sur la page de confirmation de commande, dans My account > Orders et dans tous les e-mails de commande (HTML et texte brut) sous le libellé CityPaq locker.

Dans l'administration de la commande, vous pouvez modifier le casier dans le champ Change CityPaq locker : choisissez un autre casier dans votre liste, ou saisissez un nouveau code ou une nouvelle adresse. Avec la liste Correos, un code de casier saisi est vérifié auprès de Correos. Laissez le champ vide pour conserver le casier actuel. Chaque modification 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 Correos CityPaq. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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 son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Correos CityPaq n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique le voient toujours, avec la mention (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. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Correos CityPaq n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'adresse est en Espagne et que la méthode est ajoutée à la zone de livraison correspondante (ou que Ignore shipping zones est activé). Vérifiez que la grille tarifaire contient une ligne pour l'Espagne ou une ligne *, et que le panier respecte les limites de poids, Minimum order amount et Excluded shipping classes.

Les clients doivent saisir le casier alors que la liste Correos est sélectionnée : vérifiez que API client ID et API client secret sont renseignés, et consultez l'avertissement au-dessus des réglages. Il affiche la dernière erreur de l'API Correos. HTTP 401/403 signifie que Correos a refusé les identifiants : vérifiez-les et vérifiez que votre application a accès à l'API « terminals ». Après une erreur, la tentative suivante a lieu au bout de 10 minutes.

Aucun casier pour un code postal : Correos n'a trouvé aucun casier actif pour ce code postal, sa zone ou sa province. Le client peut rechercher un autre code postal ou saisir le casier trouvé sur le localisateur CityPaq de Correos.

La liste déroulante de mes casiers n'apparaît pas : My lockers est vide ou ses lignes sont invalides. Chaque ligne doit contenir au minimum CODE | Name.

Où les clients trouvent le code du casier : sur le localisateur CityPaq de Correos, lié sous le champ du casier.

Notes pour les développeurs : le casier est enregistré dans les métadonnées de commande _vfd_cpq_locker (texte affiché partout) et _vfd_cpq_locker_id (code du casier, lorsqu'il est choisi dans la liste Correos ou dans votre liste). L'extension utilise l'API « terminals » de production de Correos. Aucun environnement sandbox n'est documenté pour cette API.

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 et 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 statut 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 le statut de licence de cette extension sont toujours supprimés, de même que les listes de casiers Correos mises en cache et la dernière erreur d'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 future réinstallation. Les casiers enregistrés dans les commandes ne sont jamais supprimés, et les commandes existantes conservent leurs lignes de livraison.

Correos et CityPaq sont des marques de leurs titulaires respectifs. Cette extension n'est pas affiliée à Correos et n'est pas approuvée par Correos.