VibeFox Correos CityPaq for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

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

Identifiants de l'API Correos (uniquement pour la liste des casiers en temps réel) : 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 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 les clients saisissent eux-mêmes le casier ou choisissent dans votre propre liste, vous n'avez pas besoin d'identifiants de l'API.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un seul 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_correos_citypaq-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_correos_citypaq.ocmod.zip. Installez uniquement 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_correos_citypaq-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 aussi copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions, choisissez le type d'extension Shipping. Repérez VibeFox Correos CityPaq et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page de réglages.

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

5. Renseignez la grille tarifaire, choisissez la façon dont le client sélectionne le casier (voir Configuration), activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_correos_citypaq.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, choisissez le type d'extension Shipping. Repérez VibeFox Correos CityPaq, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

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

Après l'installation, le mode reste désactivé tant que vous n'activez pas Enable/Disable et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages que vous aviez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Les tarifs et montants acceptent une virgule ou un point décimal. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

En haut de la page, des avertissements signalent : l'absence de ligne pour l'Espagne et de ligne par défaut dans la grille tarifaire, un mode de sélection du casier qui ne peut pas fonctionner (aucun casier dans votre liste, identifiants de l'API absents), la dernière erreur de l'API Correos, et l'absence de classe de poids avec l'unité kg dans la boutique (les poids des produits sont alors convertis selon le nom de l'unité : kg, g, lb ou oz ; les unités inconnues sont lues comme kg). Vérifiez System > Localisation > Weight Classes. Si le nom est vide, non valide ou dépasse 64 caractères, si un poids ou un montant n'est pas un nombre valide égal ou supérieur à 0, si Min weight (kg) est supérieur à Max weight (kg), ou si Sort order n'est pas un nombre entier, la page affiche une erreur et rien n'est enregistré. Les tarifs non valides de la grille, les lignes en double et les lignes non valides 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 mode n'est donc jamais proposé pour les autres pays.

Enable/Disable : active ou désactive la livraison Correos CityPaq. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client au moment du paiement. Par défaut : Correos CityPaq. Obligatoire, 64 caractères maximum, sans < > ; = # { }.

Tax class : OpenCart ajoute la taxe de cette classe aux tarifs de la grille. No tax signifie que les tarifs sont définitifs.

Sort order : la position du mode dans la liste des modes de livraison. Un nombre entier.

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

Correos ne publie pas d'API de tarifs pour CityPaq : le tarif 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 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 égal à 0 ou vide utilise le tarif de base. Cliquez sur Add row pour ajouter une ligne et sur le bouton × pour en supprimer une. Sans ligne correspondante, le mode 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.

Per order (size by the total cart weight): un seul tarif 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 tarif de sa propre taille, multiplié par sa quantité, et les tarifs sont additionnés.

Les poids des produits sont convertis en kg à partir de la classe de poids de chaque produit.

Conditions

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

Max weight (kg) : masque le mode 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 le mode que si le sous-total des produits nécessitant une livraison (après coupon, avant taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.

Livraison gratuite

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

Free shipping from : le sous-total des produits nécessitant une livraison (après coupon, avant taxes) à partir duquel ce mode coûte 0. Utilisé uniquement lorsque Free shipping est activé.

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

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 listés, les codes postaux les plus proches en premier (jusqu'à 50). 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, de 3 à 120 caractères, avec un lien vers la carte 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 listés en premier.

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

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

Liste des casiers CityPaq de Correos (API) (utilisée uniquement avec la liste des casiers 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 tarifs 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. Ne saisissez une nouvelle valeur que pour la modifier. Cochez Remove the saved client ID and client secret et cliquez sur Save pour les supprimer. Si rien n'est enregistré, la section affiche No credentials saved. Lorsque vous modifiez les identifiants ou le choix du casier, les listes de casiers en cache et la dernière erreur de l'API sont effacées.

Disponibilité

Geo zone : propose le mode uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie toutes les adresses espagnoles. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore geo zone : propose CityPaq pour toutes les adresses espagnoles, même si elles ne figurent pas dans la zone géographique ci-dessus.

Avancé

Debug log : écrit des lignes de débogage dans storage/logs/vfd_cpq_debug.log.php (sur OpenCart 4, system/storage/logs/vfd_cpq_debug.log.php). Le fichier ne peut pas être lu 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 consigné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 de l'extension supprime les réglages, les listes en cache et les journaux. Les casiers enregistrés dans les commandes sont conservés. Lorsqu'elle est désactivée (par défaut), tout est conservé pour une réinstallation.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. L'identifiant client et le secret de l'API ne sont pas inclus.

Import : collez un JSON de réglages exporté depuis cette extension et cliquez sur Import. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Les identifiants enregistrés sont conservés.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif CityPaq. Si une Geo zone est définie (et que Ignore geo zone est désactivé) et que l'adresse se trouve hors de cette zone, CityPaq n'est pas proposé. Seuls les produits dont Requires Shipping est sur Yes sont pris en compte : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite que l'adresse de livraison est en Espagne, le poids du panier et le montant minimum de commande, recherche la ligne de tarif pour l'Espagne (ou la ligne *) et la taille du colis, puis renvoie le tarif. Si la livraison gratuite s'applique, le tarif est de 0. Le tarif est calculé dans la devise par défaut de la boutique, arrondi selon ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée. Aucune requête n'est envoyée à Correos pour le tarif.

La zone CityPaq locker apparaît sous le mode CityPaq à l'étape du mode de livraison. Le choix est enregistré dès que le client le fait. Un casier non acceptable est refusé avec un message, et le choix précédent reste en place. Avec la liste de Correos, un code de casier n'est accepté que si Correos l'a proposé pour le code postal recherché ; son nom et son adresse sont alors repris de Correos. Un client peut rechercher jusqu'à 30 codes postaux différents par session de paiement. Ensuite, le client voit Too many searches. Please enter the CityPaq locker you found on the Correos map.

Le bouton Continue de l'étape du mode de livraison ne poursuit pas avec CityPaq sans casier valide. Cela est vérifié côté serveur. Le client voit par exemple Please choose the CityPaq locker where you want to collect your parcel. Lorsque la commande est passée, le casier est enregistré dans la commande.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit CityPaq dans la fenêtre Shipping method options. Le cadre CityPaq locker apparaît dans cette fenêtre, sous l'option CityPaq, et fonctionne comme décrit ci-dessus. Le bouton Continue de la fenêtre ne poursuit pas avec CityPaq sans casier valide. OpenCart 4 conserve une seule commande pour le paiement et la met à jour à chaque nouvelle confirmation du client ; le casier de la commande est mis à jour avec elle.

La liste de Correos n'est demandée que lorsque CityPaq est le mode sélectionné, et non pendant l'affichage de l'étape. Une liste est mise en cache pendant 12 heures par code postal. Une requête en échec est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Correos à chaque mise à jour. Le client ne voit jamais l'erreur technique, seulement le message The Correos CityPaq list cannot be loaded right now. et le champ manuel.

L'extension n'obtient pas de tarifs en temps réel 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 en utilisant le casier enregistré dans la commande.

Points relais

Le casier choisi est ajouté au mode de livraison de la commande, par exemple Correos CityPaq - CityPaq locker: .... Le client le voit donc dans l'historique de commandes de son compte et dans les e-mails de commande, et 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 CityPaq locker au-dessus de l'historique affiche le casier et son Locker code : lorsqu'il a été choisi dans une liste. Pour le modifier, utilisez le champ Change CityPaq locker et cliquez sur Save : avec votre liste, choisissez un autre casier dans la liste déroulante ; avec la liste de Correos, saisissez un code de casier (il est recherché chez Correos) ou une adresse ; sinon, saisissez un nouveau code ou une nouvelle adresse. Laissez le champ vide, ou gardez -- Keep the current locker --, pour conserver le casier actuel. Chaque modification met aussi à jour le texte du mode de livraison de la commande et ajoute une entrée d'historique CityPaq locker changed to: ... sans notifier le client. La modification du casier nécessite l'autorisation de modification des commandes (sale/order). L'accès aux réglages de l'extension n'est pas nécessaire. Le panneau est affiché pour les commandes CityPaq même 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 Correos CityPaq est le premier bloc de Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit, au-dessus des réglages. Collez 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) et 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 se trouvent la ligne Product: opencart-shipping-correos-citypaq et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les 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. 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, Correos CityPaq n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, si bien que sans clé active le mode est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, 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 affectées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié 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 son statut.

Dépannage

Correos CityPaq n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que l'adresse de livraison est en Espagne. Vérifiez la Geo zone (ou activez Ignore geo zone). Vérifiez que la grille tarifaire comporte une ligne pour l'Espagne ou une ligne *, que le panier respecte les limites de poids et le Minimum order amount, et que les produits ont Requires Shipping sur Yes.

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 en haut de la page de 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 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 la carte CityPaq de Correos.

La liste déroulante de my lockers n'apparaît pas : My lockers est vide ou ses lignes ne sont pas valides. Chaque ligne a besoin d'au moins CODE | Name.

Où les clients trouvent le code du casier : sur la carte CityPaq de Correos reliée sous le champ du casier.

La page indique "Warning: You do not have permission to modify VibeFox Correos CityPaq!" : votre groupe d'utilisateurs administrateurs ne peut peut-être que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_correos_citypaq (OpenCart 3) ou extension/vfd_correos_citypaq/shipping/vfd_correos_citypaq (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : le casier d'une session de paiement et celui d'une commande sont stockés dans la table vfd_cpq_locker (avec le préfixe de votre base de données). L'adresse de l'API Correos peut être remplacée par le réglage vfd_cpq_api_url (pour les tests) ; il n'a pas de champ sur la page de réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Correos CityPaq. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort order, Tax class et Geo zone. 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é, les réglages, le journal et les casiers des sessions de paiement sans commande sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les casiers enregistrés dans les commandes ne sont jamais supprimés, et les commandes existantes gardent leur mode et leur coût de livraison.

Sur 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 Correos CityPaq dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet envoyé.

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