VibeFox Correios for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Contrat Correios (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API tarifaire Correios Web Services (CWS) et nécessitent les identifiants d'un contrat Correios avec une posting card. Il vous faut trois valeurs : votre identifiant Meu Correios (généralement le CNPJ ou le CPF du contrat), le code d'accès API et le numéro de posting card. Générez le code d'accès dans le portail Correios Web Services (cws.correios.com.br ; pour l'homologation, cwshom.correios.com.br). Vous avez aussi besoin du CEP depuis lequel vous expédiez. Sans identifiants, le module ne fonctionne qu'avec les tarifs fixes.

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 retrouvez plus tard VibeFox Correios 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. Saisissez l'utilisateur de l'API Correios, le code d'accès, le numéro de posting card, le CEP d'origine et le service. Si la devise par défaut de votre boutique n'est pas le BRL, saisissez le taux en BRL. Renseignez les tarifs fixes pour les autres pays et en solution de repli (voir Configuration) puis cliquez sur Save.

À l'installation, le module crée le transporteur Correios avec le texte de délai de livraison Correios (Brazilian Post). Le transporteur est associé à toutes les zones et à tous les groupes de clients. 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 Correios > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs Correios et des jetons d'API. Les nombres peuvent être saisis avec un point ou une virgule.

La page affiche des avertissements lorsque les tarifs en temps réel ou le transporteur ne peuvent pas fonctionner : seuls certains des trois identifiants sont renseignés, le CEP d'origine est absent, le taux en BRL manque pour une boutique dans une autre devise, ou il n'y a ni identifiants ni tarifs fixes. Chaque avertissement indique si les tarifs fixes sont utilisés entre-temps ou si le transporteur est masqué. Un avertissement apparaît aussi si l'unité de poids ou de dimension de la boutique n'est pas connue du module (elle est alors lue comme kg ou cm) ; définissez kg, g, lb ou oz et cm, mm, m ou in dans International > Localization (Local units).

L'enregistrement est refusé avec un message si le titre de la méthode est vide ou invalide (64 caractères maximum), si un champ numérique ou un prix dans Country prices n'est pas un nombre supérieur ou égal à 0, si le taux en BRL est 0, si Min cart weight est supérieur à Max cart weight, si le CEP d'origine ne comporte pas 8 chiffres ou si l'autre code de service comporte plus de 5 chiffres. Rien n'est enregistré tant que vous n'avez pas corrigé la valeur.

Général

Enable Correios : active ou désactive le transporteur dans toutes les zones à la fois. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et au paiement. Par défaut : Correios. Obligatoire.

Tax : la règle de taxe ajoutée au coût de livraison, ou No tax (par défaut).

API Correios (tarifs en temps réel au Brésil)

Pour les adresses au Brésil, le prix provient de l'API tarifaire de Correios. Si l'API ne renvoie aucun prix (API indisponible, CEP non desservi, colis trop grand), le tarif fixe de Country prices est utilisé, ou le transporteur est masqué s'il n'y en a pas. Les détails des erreurs vont dans le journal, jamais au client.

API user : votre identifiant de connexion au portail Meu Correios, généralement le CNPJ ou le CPF du contrat.

Access code : le code d'accès API (código de acesso) généré dans le portail Correios Web Services. Ce n'est pas le mot de passe du portail. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it (empty the API user as well to remove it). Saisissez une nouvelle valeur uniquement pour la modifier. Pour supprimer le code enregistré, videz API user et Access code puis enregistrez.

Posting card : le numéro de posting card (cartão de postagem) de votre contrat : 10 chiffres, commençant généralement par deux zéros, par exemple 0012345678. Les numéros plus courts sont complétés par des zéros en début. Vous pouvez vérifier le numéro sur la page Correios Fácil du site de Correios.

Homologation : utilise l'environnement de test (homologation) de Correios : les requêtes vont vers apihom.correios.com.br avec un code d'accès d'homologation. Désactivez-le sur une boutique en production.

Origin CEP : le CEP (8 chiffres) depuis lequel les colis sont expédiés, par exemple 01001-000.

Service : le service Correios tarifé au paiement. Codes grand public : PAC (04510, par défaut), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Codes contrat : PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Les codes contrat nécessitent une posting card d'un contrat qui inclut le service.

Other service code : facultatif, un code de service à 5 chiffres de votre contrat qui ne figure pas dans la liste, par exemple 03085. Un code plus court est complété par des zéros en début. Lorsqu'il est renseigné, il est utilisé à la place de Service.

Package format : le type d'objet envoyé à Correios.

Default product weight : en kg, envoyé à Correios pour chaque produit sans poids. Par défaut : 0.3. Les poids et dimensions des produits sont convertis depuis les unités de votre boutique (la description du champ les indique), et le panier est tarifé comme un seul colis.

BRL → store currency rate : le nom du champ indique la devise par défaut de votre boutique, par exemple BRL → EUR rate. Les tarifs Correios sont en BRL. Si votre devise par défaut n'est pas le BRL, saisissez combien d'unités de votre devise vaut un BRL, par exemple 0.17. Sans ce taux, les tarifs en temps réel ne sont pas utilisés. Le taux doit être supérieur à 0. Si votre devise par défaut est le BRL, laissez le champ vide.

Tarifs fixes (utilisés pour les pays hors du Brésil, sans identifiants API, et en solution de repli lorsque l'API ne renvoie aucun prix)

Country prices : un tableau de pays avec un prix Base et des prix selon le poids du panier dans la devise par défaut de votre boutique, hors taxes : XS jusqu'à 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL au-delà de 5 kg. Un prix de taille vide ou égal à zéro utilise le prix Base. Cliquez sur Add country pour ajouter une ligne et sur la croix pour en supprimer une. La ligne * Default (all other countries) définit les prix de tous les pays sans ligne propre. Un pays sans ligne (et sans *) n'a pas de tarif fixe. Une ligne sans aucun prix n'est pas enregistrée. Un prix qui n'est pas un nombre, ou qui est négatif, interrompt l'enregistrement avec une erreur. Un prix de base de 0 signifie livraison gratuite pour ce pays.

Fixed price per : Order facture le prix une seule fois. Item (price × quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'aux tarifs fixes. Les tarifs en temps réel sont toujours calculés pour l'ensemble du colis.

Conditions

Min cart weight : en kg, masque le transporteur en dessous de ce poids de panier. 0 signifie aucune limite. Il ne peut pas être supérieur à Max cart weight.

Max cart weight : en kg, masque le transporteur au-dessus de ce poids de panier. Par défaut : 30. 0 signifie aucune limite, un champ vide signifie 30 kg. Les colis PAC et SEDEX de Correios peuvent peser jusqu'à 30 kg.

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

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

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Aucune requête API n'est envoyée dans ce cas.

Disponibilité sans zones de livraison

Normalement, le transporteur est affiché dans les zones qui lui sont associées dans Shipping > Carriers.

Ignore shipping zones : propose le transporteur pour les pays ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones. Désactiver l'option supprime les zones qu'elle a ajoutées. Une zone créée plus tard, alors que l'option est active, est ajoutée automatiquement.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays actifs de la boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de prix dans logs/vfd_crr_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. L'utilisateur API, le code d'accès, la posting card, le jeton et les CEP des clients ne sont pas journalisés.

Log : affiche la taille et les dernières entrées du journal de débogage. 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 services de commande, les prix en cache et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le tarif Correios. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Correios.

Pour une adresse au Brésil avec des identifiants renseignés, le module obtient d'abord un jeton API pour votre posting card. Le jeton fournit aussi les numéros du contrat et de la direction régionale, de sorte que le prix est celui de votre contrat. Il demande ensuite le prix du service choisi selon le CEP d'origine et le CEP de destination, le poids du colis en grammes et la taille du colis en cm. Un prix n'est demandé que lorsque le CEP de destination comporte 8 chiffres. Lorsque tous les produits ont des dimensions, la taille du colis est estimée à partir de celles-ci ; sinon, la taille minimale Correios est envoyée. Les colis de plus de 30 kg ne sont pas envoyés à l'API. Le prix en BRL est converti avec votre taux. Le prix est calculé dans votre devise par défaut, puis affiché dans la devise du panier du client.

Chaque prix est mis en cache pendant 1 heure par colis. Une requête en échec est mise en cache pendant 10 minutes, afin qu'une panne de l'API ne ralentisse pas chaque mise à jour du paiement. Le jeton est mis en cache jusqu'à peu de temps avant son expiration et renouvelé automatiquement ; si Correios le rejette, un nouveau jeton est demandé et la requête de prix est répétée une fois. Le délai d'attente de l'API est de 12 secondes.

Si l'API ne renvoie aucun prix, le tarif fixe est utilisé, ou le transporteur est masqué s'il n'existe pas de tarif fixe. Le client ne voit jamais les détails des erreurs d'API ; ils vont dans le journal de débogage.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne calcule que les tarifs. Il n'obtient pas les tarifs internationaux de Correios (Exporta Fácil, Packet), les estimations de délai de livraison, les étiquettes, les pré-envois, les déclarations ni le suivi. Les clients ne peuvent pas choisir une agence ou un casier Correios. Les services supplémentaires (valeur déclarée, remise en main propre, avis de réception) ne sont pas ajoutés. Le module n'affiche qu'un seul service Correios par boutique, et les taux de change ne sont pas mis à jour automatiquement.

Commandes

Lorsqu'une commande est passée avec le transporteur Correios, le module enregistre la manière dont son prix de livraison a été calculé. La page de la commande dans le back-office affiche alors un bloc Correios avec Correios service (pour un tarif en temps réel, par exemple PAC — contrat (03298)) et Price source : Live price (Correios API), Fixed price ou Free shipping.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Correios est le premier bloc de Modules > Module Manager > VibeFox Correios > 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-correios 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 Correios n'est pas affiché aux clients au 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

Correios n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Correios est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids et Minimum order amount. Sans tarif en temps réel, un tarif fixe pour le pays ou pour * doit exister. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le transporteur affiche un tarif fixe au lieu du tarif Correios : consultez le champ Log sur la page du module. Les erreurs de Correios y sont journalisées : code d'accès erroné, service absent de votre contrat, CEP non desservi, colis de plus de 30 kg ou dépassant les limites de taille. Vérifiez aussi que le CEP d'origine est renseigné, que le CEP du client comporte 8 chiffres et, si la devise par défaut n'est pas le BRL, le taux en BRL. Activez Debug log pour voir chaque calcul.

La demande de jeton échoue : vérifiez l'utilisateur API, le code d'accès, la posting card et l'environnement. Un code d'accès d'homologation ne fonctionne que si Homologation est activé, et un code de production uniquement si cette option est désactivée.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide le cache des tarifs et le jeton API.

La page indique que le transporteur Correios est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

L'enregistrement indique que vous n'avez pas la permission : votre profil employé peut voir le module mais pas le configurer. L'enregistrement des réglages et le vidage du journal nécessitent la permission de configuration du module.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Correios et choisissez Uninstall. La clé de licence, le statut de la licence ainsi que les prix et jetons en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) et les réglages, les services de commande enregistrés et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rétablit le transporteur avec le statut qu'il avait auparavant.

Correios est une marque déposée de son propriétaire respectif. Ce module n'est pas affilié à Correios et n'est pas approuvé par Correios.