VibeFox Correos CityPaq for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Livraison en Espagne : les casiers CityPaq n'existent qu'en Espagne ; le transporteur n'est donc proposé que pour les adresses de livraison en Espagne.

Identifiants API Correos (uniquement pour la liste en direct des casiers) : la liste des casiers CityPaq de Correos lit les casiers actifs depuis l'API « terminals » de Correos. Sur le portail développeurs de Correos, ouvrez l'API « terminals » et utilisez 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 vos 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 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éversement terminé, cliquez sur Configure, ou recherchez plus tard VibeFox Correos CityPaq dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Remplissez la grille tarifaire, choisissez la manière dont le client sélectionne le casier (voir Configuration) et cliquez sur Save.

À l'installation, le module crée le transporteur Correos CityPaq avec le texte de délai de livraison Delivery to a Correos CityPaq parcel locker. Le transporteur est associé à tous les groupes de clients et à la zone Espagne. 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 Correos CityPaq > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Les prix et montants acceptent une virgule ou un point décimal.

Les avertissements affichés au-dessus des réglages vous indiquent lorsque le transporteur est introuvable, lorsque la grille tarifaire n'a ni ligne pour l'Espagne ni ligne par défaut, lorsque le choix de sélection du casier ne peut pas fonctionner (aucun casier dans votre liste, pas d'identifiants API), quelle a été la dernière erreur de l'API Correos, et lorsque l'unité de poids de votre boutique n'est pas reconnue par le module (les poids des produits sont alors lus en kg ; définissez kg, g, lb ou oz dans International > Localization). Si le nom est vide, invalide ou dépasse 64 caractères, si un poids ou un montant n'est pas un nombre valide égal ou supérieur à 0, ou si Min weight (kg) est supérieur à Max weight (kg), la page affiche une erreur et rien n'est enregistré. Les prix invalides dans la grille tarifaire et les lignes invalides ou en double dans My lockers sont signalés comme avertissements, et le reste est enregistré.

Général

Les casiers CityPaq n'existent qu'en Espagne ; le transporteur n'est donc jamais proposé pour d'autres pays.

Enable/Disable: active ou désactive la livraison Correos CityPaq. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Name: le nom du mode de livraison affiché au client lors du paiement. C'est aussi le nom du transporteur. Par défaut : Correos CityPaq. Obligatoire, 64 caractères maximum.

Tax: la règle de taxe du transporteur. PrestaShop ajoute cette taxe aux prix de la grille. No tax signifie que les prix sont définitifs.

Prix (le titre de la section indique la devise par défaut de votre boutique)

Correos ne publie pas d'API de tarifs pour CityPaq ; le prix provient donc de cette grille. Saisissez les tarifs de votre contrat Correos dans la devise par défaut de la boutique, hors taxes.

Price table: une ligne pour Spain (ES) et/ou une ligne par défaut * Default. Chaque ligne a 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 égal à 0 ou vide utilise le prix de base. Cliquez sur + Add row pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Sans ligne correspondante, le transporteur est masqué. Si un pays apparaît deux fois, seule la première ligne est utilisée.

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

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

Conditions

Min weight (kg): masque le transporteur lorsque le panier est plus léger. 0 signifie pas de limite.

Max weight (kg): masque le transporteur lorsque le panier est plus lourd. Par défaut : 30, car CityPaq accepte les colis jusqu'à 30 kg. 0 signifie pas de limite.

Minimum order amount: n'affiche le transporteur que lorsque le sous-total du panier (produits soumis à expédition, après remises, hors taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Livraison gratuite

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

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

Sélection du casier CityPaq

La section contient un lien vers le localisateur officiel des casiers CityPaq de Correos.

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

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

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. Si un code figure deux fois, seule la première ligne est utilisée.

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

La section contient un lien vers la page de l'API « terminals » du 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.

Après l'enregistrement, les deux champs restent vides et affichent Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Cochez Remove the saved client ID and client secret et cliquez sur Save pour les supprimer. Lorsque rien n'est enregistré, la section affiche No credentials saved. Lorsque vous modifiez les identifiants ou la sélection du casier, les listes de casiers en cache sont effacées.

Disponibilité sans zones de livraison

Ignore shipping zones: propose CityPaq pour toute adresse espagnole, même si la zone de l'adresse n'est pas associée au transporteur. Lorsque l'option est activée, le transporteur est associé à toutes les zones actives, y compris celles créées ultérieurement. Lorsque vous la désactivez à nouveau, le transporteur retrouve les zones qu'il avait auparavant. Désactivé (recommandé) signifie que les zones définies dans Shipping > Carriers sont utilisées.

Avancé

Debug log: écrit des lignes de débogage dans logs/vfd_cpq_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API Correos sont toujours écrites, même lorsque cette option est désactivée. Les identifiants et les données personnelles 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 les réglages, le transporteur, les listes en cache et les journaux. Les casiers enregistrés dans les commandes sont conservés. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix CityPaq. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. Le module vérifie que l'adresse de livraison est en Espagne, le poids du panier et le montant minimum de commande, trouve la ligne de prix pour l'Espagne (ou la ligne *) et la taille du colis, puis renvoie le prix. 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. La taxe est ajoutée par la règle de taxe du transporteur.

Lorsque le client sélectionne CityPaq, le cadre CityPaq locker apparaît sous le transporteur. Le choix est enregistré dans le panier dès que le client le fait. Un casier non acceptable est refusé avec un message, et le choix précédent est conservé. Avec la liste Correos, un code de casier n'est accepté que si Correos l'a proposé pour le code postal recherché, et son nom et son adresse sont repris de Correos. Un client peut rechercher jusqu'à 30 codes postaux différents par panier. Au-delà, il voit Trop de recherches. Veuillez saisir le casier CityPaq trouvé sur la carte Correos.

Le bouton Continue de l'étape de livraison ne permet pas de continuer sans casier valide. Cela est aussi vérifié sur le serveur. Le client voit par exemple Veuillez choisir le casier CityPaq où vous souhaitez récupérer votre colis. Lorsque la commande est passée, le casier du panier est enregistré dans la commande.

La liste Correos n'est demandée que lorsque le client sélectionne CityPaq, et non pour chaque visiteur de l'étape de livraison. Une liste 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'attente de l'API est de 12 secondes. Le client ne voit jamais l'erreur technique, seulement un message bref et le champ manuel. Le cadre du casier fonctionne avec les thèmes Classic et Hummingbird.

Le module n'obtient pas de tarifs en direct 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. Le client le voit sous la forme CityPaq locker: sur la page de confirmation de commande et sur la page de détail de commande de son compte client. Dans l'e-mail de confirmation de commande et dans l'e-mail de nouvelle commande du module Mail alerts, le casier est ajouté à la ligne du transporteur, par exemple Correos CityPaq - CityPaq locker: ....

Sur la page de commande de l'administration, le bloc CityPaq locker affiche le casier et son Locker code: lorsqu'il a été choisi dans une liste. Pour le modifier, utilisez le champ Change CityPaq locker puis cliquez sur Save : avec votre liste, choisissez un autre casier dans la liste déroulante ; avec la liste Correos, saisissez un code de casier (il est recherché auprès de Correos) ou une adresse ; dans les autres cas, saisissez un nouveau code ou une nouvelle adresse. Laissez le champ vide pour conserver le casier actuel. Chaque modification ajoute un message privé à la commande : Casier CityPaq modifié en : .... Modifier le casier nécessite l'autorisation de modifier les commandes. L'accès aux pages Modules n'est pas nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Correos CityPaq est le premier bloc de Modules > Module Manager > VibeFox Correos CityPaq > Configure, au-dessus des réglages. Saisissez la clé dans License key puis 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-correos-citypaq et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, le transporteur Correos CityPaq n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office, donc le transporteur est masqué aussi pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affecté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é automatiquement pendant que vous travaillez dans le back-office : 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 ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Correos CityPaq n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que l'adresse de livraison est en Espagne. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone Espagne et le groupe du client (ou activez Ignore shipping zones). Vérifiez que la grille tarifaire contient une ligne pour l'Espagne ou une ligne *, et que le panier respecte les limites de poids et Minimum order amount. Les produits peuvent aussi être limités à certains transporteurs sur leur page produit.

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 enregistré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 prochaine tentative a lieu 10 minutes plus tard.

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 comporter au minimum CODE | Name.

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

La page indique que le transporteur est introuvable ou n'a pas pu être mis à jour : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. La réinitialisation conserve les réglages et le statut du transporteur.

Notes pour les développeurs : le casier d'un panier et d'une commande est stocké dans la table vfd_cpq_locker (avec le préfixe de votre base de données). Le module utilise l'API « terminals » de production de Correos.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Correos CityPaq et choisissez Uninstall. La clé de licence, le statut de la licence, les listes de casiers Correos en cache et la dernière erreur de l'API sont toujours supprimées. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), et les réglages, le journal et les casiers des paniers sans commande sont supprimés. Si elle est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module restaure le statut précédent du transporteur. Les casiers enregistrés dans les commandes ne sont jamais supprimés.

Correos et CityPaq sont des marques de leurs propriétaires respectifs. Ce module n'est ni affilié à Correos ni approuvé par Correos.