VibeFox Sameday Easybox 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.

Nom d'utilisateur et mot de passe de l'API Sameday : l'accès à l'API fait partie d'un compte professionnel Sameday en Roumanie, en Hongrie ou en Bulgarie. Adressez-vous à votre gestionnaire de compte Sameday ou à l'équipe d'intégration de Sameday. Les identifiants sont souvent les mêmes que ceux du portail eAWB (eawb.sameday.ro, .hu ou .bg). Pour l'API de démonstration, Sameday fournit des identifiants de test distincts. Sans nom d'utilisateur et mot de passe de l'API, le transporteur n'est pas proposé, car le client ne pourrait pas choisir de casier.

Comtés dans le formulaire d'adresse : l'estimation Sameday a besoin du comté de l'adresse de livraison. PrestaShop ne dispose pas de comtés pour la Roumanie, la Hongrie et la Bulgarie par défaut. Le module peut les ajouter pour vous (voir la section Lockers easybox ci-dessous). Sans eux, les tarifs proviennent de votre grille ou des frais de repli.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour un 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 retrouvez plus tard VibeFox Sameday Easybox 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 de configuration, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez votre API username et votre API password Sameday, choisissez le Sameday country et cliquez sur Save. La page doit afficher « Connecté à Sameday ... lockers easybox ». Le Pickup point et l'Easybox service sont renseignés à partir de votre compte.

5. Définissez vos tarifs : Exchange rate of the estimate si la devise de votre boutique diffère de celle de Sameday, et une ligne Country prices (par exemple * Default) ou un Fallback cost.

6. Si la page indique que la boutique ne dispose pas de comtés pour votre pays Sameday, cliquez sur Add counties dans la section Lockers easybox.

À l'installation, le module crée le transporteur Sameday easybox avec le texte de délai de livraison Delivery to a Sameday easybox locker. Il est affecté à tous les groupes de clients et à la zone Roumanie. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison et le logo 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 Configure du module, en six sections. Le bouton Save de chaque section enregistre la page entière.

Au-dessus des réglages, la page affiche l'état de la connexion : l'hôte Sameday, le nombre de casiers easybox et la date de la dernière actualisation de la liste, ou le rejet du nom d'utilisateur ou du mot de passe par Sameday. Elle signale aussi les problèmes de configuration, par exemple l'absence d'identifiants, de tarif, de taux de change pour l'estimation, de comtés, une unité de poids de la boutique que le module ne connaît pas, ou un transporteur introuvable.

Tous les tarifs et limites acceptent la virgule ou le point comme séparateur décimal (4,99 ou 4.99). Un nombre invalide ou négatif n'est pas enregistré : un avertissement indique le champ, et la valeur précédente est conservée.

Général

Enable/Disable : active ou désactive le transporteur. Cela revient au statut du transporteur dans Shipping > Carriers.

Name : le nom du mode de livraison affiché au client (le nom du transporteur). Par défaut : Sameday easybox.

Tax status : None signifie que le prix est définitif. Taxable avec une règle de taxe fait ajouter par PrestaShop cette taxe de livraison au prix.

Compte Sameday (API)

À l'enregistrement, le module se connecte à Sameday et charge vos services, vos points de collecte et la liste des casiers easybox. La liste est actualisée chaque jour.

API username : votre nom d'utilisateur de l'API Sameday.

API password : votre mot de passe de l'API Sameday. Il n'est plus jamais affiché : laissez le champ vide pour conserver celui qui est enregistré. Vider le nom d'utilisateur supprime aussi le mot de passe. Si Sameday le rejette, il n'est pas réessayé pendant 10 minutes.

Sameday country : le pays de votre compte Sameday : Romania (api.sameday.ro) (par défaut), Hungary (api.sameday.hu) ou Bulgaria (api.sameday.bg). Ses casiers sont proposés, et le transporteur n'est affiché que pour ce pays de destination. Lorsque vous le modifiez, le transporteur est aussi lié à la zone du nouveau pays.

Test mode : utilise l'API de démonstration Sameday (sameday-api.demo.zitec.com) avec des identifiants de démonstration.

Tarifs

L'ordre d'application est le suivant : l'estimation Sameday (lorsque le Pickup point et l'Easybox service sont renseignés), puis la grille de tarifs par pays, puis les frais de repli. Les tarifs de la grille se saisissent dans la devise par défaut de la boutique. Les clients qui paient dans une autre devise voient le prix converti.

Pickup point : votre point de collecte Sameday, où Sameday récupère les colis. Après une connexion réussie, il s'agit d'une liste des points de collecte de votre compte, et celui par défaut est choisi automatiquement. Nécessaire pour l'estimation Sameday. Choisissez - not set (price table only) - pour n'utiliser que la grille de tarifs.

Easybox service : le service Sameday pour la livraison en easybox, généralement « Locker NextDay » (code LN), qui est choisi automatiquement. Nécessaire pour l'estimation Sameday.

Exchange rate of the estimate : Sameday établit l'estimation dans la devise de votre pays Sameday : RON, HUF ou BGN (EUR pour les boutiques bulgares qui vendent en euros). Si votre boutique vend dans une autre devise, saisissez la valeur de 1 unité de la devise Sameday dans la devise de votre boutique, par exemple 0.20. Le taux doit être supérieur à 0. Sans lui, l'estimation n'est pas utilisée et la grille de tarifs s'applique. Le lev et l'euro sont convertis automatiquement au taux fixe.

Table price : Per order facture le prix une seule fois. Per item (price x quantity) le multiplie par le nombre d'articles. Cela s'applique au tarif de la grille et aux frais de repli. L'estimation Sameday porte toujours sur le colis entier.

Country prices : un prix par pays de destination et par poids de colis. Cliquez sur + Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Chaque ligne comporte une colonne Price et des colonnes de poids : XS jusqu'à 1 kg, S de 1 à 2 kg, M de 2 à 3 kg, L de 3 à 5 kg et XL au-delà de 5 kg. Une colonne de poids laissée à 0 utilise la colonne Price. La ligne * Default sert aux pays qui n'ont pas de ligne propre. Une nouvelle ligne démarre en * Default avec tous les prix à 0, ce qui signifie livraison gratuite. Choisissez le pays et saisissez les prix avant d'enregistrer, ou supprimez la ligne. Si un même pays figure dans deux lignes, seule la première est conservée à l'enregistrement, et un avertissement le signale. Si une cellule n'est pas un nombre valide, la grille n'est pas enregistrée.

Fallback cost : utilisé lorsqu'il n'y a pas d'estimation Sameday et que la grille du pays ne contient pas de ligne pour la destination. Laissez-le vide pour ne pas proposer le transporteur dans ce cas.

Free shipping from : le sous-total du panier (produits nécessitant une livraison, après remises, hors taxes) à partir duquel la livraison en easybox est gratuite. Lorsque le sous-total l'atteint, le transporteur est proposé sans frais et aucun prix n'est demandé. Laissez vide pour ne jamais proposer la livraison gratuite.

Disponibilité

Minimum weight (kg) : masque le transporteur lorsque le panier pèse moins. Le poids est converti depuis l'unité de poids de votre boutique (kg, g, lb ou oz). Vide ou 0 signifie aucune limite.

Maximum weight (kg) : les colis plus lourds ne se voient pas proposer la livraison en easybox. Par défaut : 30. Vérifiez la limite de votre contrat Sameday et les dimensions des casiers easybox. Vide ou 0 signifie aucune limite. Un poids minimum supérieur au poids maximum n'est pas enregistré : un avertissement le signale, et les valeurs précédentes sont conservées.

Minimum cart subtotal : ne propose le transporteur que lorsque le sous-total du panier (produits nécessitant une livraison, après remises, hors taxes) atteint ce montant.

Ignore shipping zones : lorsqu'elle est activée, le transporteur est proposé pour les pays sélectionnés ci-dessous (le pays Sameday si la liste est vide), même si leur zone n'est pas configurée pour le transporteur. Le transporteur est alors lié à toutes les zones actives, y compris celles créées plus tard. Lorsque vous la désactivez, le transporteur retrouve les zones qu'il avait auparavant. Lorsqu'elle est désactivée, le transporteur n'est proposé que dans ses zones de Shipping > Carriers.

Countries (ignore zones mode) : les pays de destination pour ce mode. Les pays autres que le pays Sameday sont ignorés, et la page vous en avertit. Ce champ n'est utilisé que lorsque Ignore shipping zones est activée.

Lockers easybox

Locker list : indique combien de casiers easybox dans combien de villes sont chargés, et depuis quand. Refresh the locker list now les recharge. La liste est actualisée à l'enregistrement des réglages et, dès qu'elle a plus d'un jour, après une demande de paiement. Pour une actualisation quotidienne fixe, appelez une fois par jour l'Cron URL affichée ici depuis une tâche cron de votre serveur. L'URL contient un jeton secret. Sans ce jeton, elle répond par une erreur et ne contacte pas Sameday.

Counties : l'estimation Sameday a besoin du comté de l'adresse. Si PrestaShop ne dispose pas de comtés (states) pour votre pays Sameday, cliquez sur Add counties. Le module ajoute les comtés de Roumanie, de Hongrie ou de Bulgarie ainsi que le champ de comté au formulaire d'adresse de ce pays. Les comtés déjà existants ne sont pas ajoutés en double. Une fois en place, la page affiche leur nombre.

Avancé

Debug log : écrit les calculs de tarifs, les appels à l'API et les choix de casiers dans le fichier logs/vfd_sdeb_debug.log.php du dossier du module, qui ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours enregistrées. Aucun mot de passe, jeton ni donnée personnelle du client n'est enregistré. Le champ Log ci-dessous affiche la fin du fichier, avec un bouton Clear log. Désactivez le journal lorsque vous avez terminé.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages et le transporteur. Sans elle, la désinstallation se contente de désactiver le transporteur. La liste des casiers et les caches sont toujours supprimés. Le casier enregistré dans les commandes est toujours conservé.

Fonctionnement au moment du paiement

Lorsque la boutique calcule la livraison d'un panier, PrestaShop demande au module le prix du transporteur Sameday easybox. Le module vérifie les conditions : pays de livraison de votre compte Sameday, identifiants de l'API et liste de casiers exploitable, pays de Ignore shipping zones, poids du panier et sous-total minimum. Les produits qui ne nécessitent pas de livraison (produits virtuels) ne sont pas comptés. Si la livraison gratuite s'applique, le client voit le transporteur sans frais.

Sinon, le module demande à Sameday une estimation, une fois que le client a saisi une ville et un comté. Il envoie votre point de collecte et votre service, le poids du colis et l'adresse du client (rue, ville, comté et code postal). Aucun nom, e-mail ni numéro de téléphone n'est envoyé. Bucarest est transmise comme « Sector 1 », comme le fait le plugin officiel de Sameday. L'estimation est convertie dans la devise de votre boutique. S'il n'y a pas d'estimation (non configurée, pas encore de ville ou de comté, erreur, pas de taux de change), le prix provient de la grille du pays, puis des frais de repli. S'il n'y a pas de prix, le transporteur est masqué.

Les problèmes liés à Sameday ne bloquent jamais le paiement. L'estimation est mise en cache pendant 1 heure. Une erreur est mise en cache pendant 10 minutes. Après un dépassement de délai ou une erreur serveur, aucune estimation n'est demandée pendant 5 minutes. Les requêtes expirent après 15 secondes. La liste des casiers est lue sur votre serveur, et non chez Sameday, pendant le paiement.

Le transporteur fonctionne à l'étape de livraison du thème Classic (PrestaShop 8) et du thème Hummingbird (PrestaShop 9).

Le module ne crée pas d'AWB (envois), n'imprime pas d'étiquettes, ne suit pas les colis et ne gère pas le paiement à la livraison. Il ne propose pas de livraison à domicile par coursier ni de widget de carte Sameday. Créez l'AWB dans le portail eAWB de Sameday ou dans votre outil habituel, avec l'identifiant du casier affiché sur la commande.

Points de collecte

Lorsque le client sélectionne le transporteur, un bloc easybox locker apparaît en dessous, avec deux listes : - Select city - et - Select easybox locker -. La ville de l'adresse de livraison est présélectionnée lorsqu'elle dispose de casiers. Chaque casier affiche son nom et son adresse. Le choix est enregistré dans le panier immédiatement, il reste donc en place lorsque l'étape de livraison se met à jour ou que la page est rechargée.

Le casier est obligatoire. Sans casier, le client ne peut pas continuer et voit « Veuillez choisir un casier easybox Sameday. » Lorsque le client clique sur Continue, le serveur vérifie que le casier choisi figure dans la liste. Un identifiant de casier falsifié ou supprimé est refusé avec le message « Le casier easybox sélectionné n'est plus disponible. Veuillez en choisir un autre. » Si la liste ne peut pas être chargée, le client voit « Les casiers easybox n'ont pas pu être chargés. Veuillez réessayer dans un moment ou choisir un autre mode de livraison. » Le nom et l'adresse enregistrés avec la commande proviennent de la liste, et non du navigateur. Une fois la commande passée, son casier ne change plus.

Page de commande de l'administration : un bloc Sameday easybox locker avec le nom, l'adresse et le Locker ID pour l'AWB Sameday. Si une commande easybox n'a pas de casier, le bloc indique « Aucun casier easybox n'a été sélectionné pour cette commande. »

Page de confirmation et historique des commandes : Sameday easybox locker : avec le nom et l'adresse.

E-mails de commande : le nom et l'adresse du casier sont ajoutés au transporteur dans l'e-mail de confirmation de commande. Le nouvel e-mail de commande envoyé à la boutique (module Mail alerts) comprend aussi le Locker ID.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Sameday Easybox est le premier bloc de Modules > Module Manager > VibeFox Sameday Easybox > 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-sameday-easybox 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 pour un domaine : le domaine 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 Sameday easybox n'est pas affiché aux clients au moment du paiement et aucun prix n'est demandé ni calculé. La partie boutique de PrestaShop ne sait pas que vous êtes connecté au back office : le transporteur est donc aussi masqué pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester au moment du 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 l'assistance 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 après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation du module supprime toujours la clé de licence et le statut de la licence. Reset de ce module ne supprime aucune donnée : la clé et le statut sont donc conservés.

Dépannage

Sameday easybox n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le nom d'utilisateur et le mot de passe de l'API sont saisis, que la page de configuration indique « Connecté à Sameday » et que le pays de destination est celui de votre compte Sameday. Vérifiez qu'un prix est disponible (estimation Sameday, ligne de pays, ligne * Default ou Fallback cost) ainsi que les limites de poids et de sous-total. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou activez Ignore shipping zones. Les produits peuvent aussi être limités à certains transporteurs sur la fiche produit. Activez Debug log pour voir la raison dans le champ Log.

Sameday a rejeté le nom d'utilisateur ou le mot de passe de l'API : vérifiez-les et enregistrez à nouveau. Les identifiants de démonstration ne fonctionnent qu'avec Test mode activé, les identifiants de production uniquement lorsqu'il est désactivé. En attendant, la liste de casiers enregistrée est proposée, s'il en existe une, et l'estimation Sameday n'est pas utilisée.

Le tarif vient de ma grille, et non de Sameday : l'estimation nécessite un Pickup point, l'Easybox service, des comtés dans le formulaire d'adresse et, lorsque la devise de votre boutique diffère de celle de Sameday, l'Exchange rate of the estimate. Elle n'est demandée qu'après que le client a saisi une ville et un comté. Lorsque Sameday est injoignable ou renvoie une erreur, la grille ou les frais de repli sont utilisés ; la raison figure dans le journal.

La liste des casiers est ancienne ou absente : cliquez sur Refresh the locker list now ou enregistrez les réglages. Si une actualisation échoue, la liste précédente est utilisée et le statut l'indique. Si la boutique est en mode maintenance, l'URL cron est bloquée comme le reste de la boutique, sauf si l'adresse IP du serveur cron est autorisée.

La livraison est gratuite par erreur : vérifiez Free shipping from et les lignes de Country prices dont le Price est à 0, en particulier une ligne * Default ajoutée avec + Add country et laissée incomplète.

Les limites de poids ou les colonnes de poids ne correspondent pas : si la page signale que l'unité de poids de la boutique n'est pas reconnue, réglez kg, g, lb ou oz dans International > Localization (Local units).

La page indique que le transporteur Sameday easybox est introuvable : 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 d'un transporteur existant.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Sameday Easybox et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. La liste des casiers enregistrée, le résultat de la vérification du compte et tous les caches sont toujours supprimés. Si Remove data on uninstall est activée, le transporteur est supprimé (les commandes conservent leur historique), et les réglages et le journal sont effacé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 rend au transporteur enregistré le statut qu'il avait. Les commandes existantes conservent le casier enregistré.

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