VibeFox Correios 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.

Contrat Correios (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API tarifaire de Correios Web Services (CWS) et nécessitent les identifiants d'un contrat Correios avec une carte de dépôt. Vous avez besoin de trois valeurs : votre utilisateur Meu Correios (généralement le CNPJ ou le CPF du contrat), le code d'accès à l'API et le numéro de la carte de dépôt. 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). Il vous faut aussi le CEP à partir duquel vous expédiez. Sans identifiants, l'extension ne fonctionne qu'avec les tarifs fixes.

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

Installation

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_correios-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_correios.ocmod.zip. N'installez que 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_correios-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 Correios 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 le champ License key du bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Saisissez l'utilisateur de l'API Correios, le code d'accès, le numéro de la carte de dépôt, 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 la solution de repli (voir Configuration), activez Enable Correios et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_correios.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le 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 lui.

3. Allez dans Extensions > Extensions, choisissez le type d'extension Shipping. Repérez VibeFox Correios, 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 de livraison reste désactivé tant que vous n'activez pas Enable Correios et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Correios 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 Correios > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. 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. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

La page affiche des avertissements lorsque les tarifs en temps réel ou le mode ne peuvent pas fonctionner : seuls certains des trois identifiants sont renseignés, le CEP d'origine manque, 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 mode est masqué. Un avertissement apparaît aussi si la boutique n'a pas de classe de poids avec l'unité kg ou pas de classe de longueur avec l'unité cm ; les unités des produits sont alors converties selon le nom d'unité de leur classe (les unités inconnues sont lues comme kg ou cm). Vérifiez System > Localisation > Weight Classes et Length Classes.

L'enregistrement est refusé avec un message si le titre du mode est vide ou non valide (64 caractères maximum, sans < > ; = # { }), si un champ numérique ou un tarif de Country prices n'est pas un nombre égal ou supérieur à 0, si le taux en BRL vaut 0, si Min cart weight est supérieur à Max cart weight, si le CEP d'origine ne comporte pas 8 chiffres, si le code de l'autre service comporte plus de 5 chiffres, ou si Sort order n'est pas un nombre entier. Rien n'est enregistré tant que vous n'avez pas corrigé la valeur.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode à une zone géographique dans Conditions, ou à une liste de pays avec Ignore shipping zones.

Enable Correios: affiche ou masque Correios au moment du paiement. Par défaut : désactivé.

Method title: le nom du mode de livraison affiché au client dans le panier et au paiement. Par défaut : Correios. Obligatoire.

Sort order: la position de Correios parmi les modes de livraison au paiement. Un nombre entier.

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

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

API user: votre identifiant de connexion au portail Meu Correios, généralement le CNPJ ou le CPF du contrat. Le vider efface aussi le code d'accès enregistré.

Access code: le code d'accès à l'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). Ne saisissez une nouvelle valeur que pour la modifier. Pour supprimer le code enregistré, videz API user et enregistrez.

Posting card: le numéro de la carte de dépôt (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 tête. Vous pouvez vérifier le numéro sur la page Correios Fácil du site de Correios.

Homologation: utilise l'environnement d'homologation (test) de Correios : les requêtes sont envoyées à 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) d'où 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 de contrat : PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Les codes de contrat exigent une carte de dépôt 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 tête. Lorsqu'il est renseigné, il est utilisé à la place de Service.

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

Default product weight (kg): envoyé à Correios pour chaque produit sans poids. Par défaut : 0.3. Les poids et dimensions des produits sont convertis à partir de leurs classes de poids et de longueur, et le panier est tarifé comme un seul colis.

BRL → store currency rate: le nom du champ affiche la devise par défaut de votre boutique, par exemple BRL → EUR rate. Les tarifs Correios sont en BRL. Si la 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 cette valeur, 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 d'API et comme solution de repli lorsque l'API ne renvoie aucun tarif)

Country prices: un tableau de pays avec un tarif Base et des tarifs 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 tarif de taille vide ou égal à zéro utilise le tarif Base. Cliquez sur Add country pour ajouter une ligne et sur le bouton × pour en supprimer une. La ligne * All other countries définit les tarifs de tous les pays sans ligne propre. Un pays sans ligne (et sans *) n'a pas de tarif fixe. Une ligne doit comporter au moins un tarif. Un tarif de base de 0 signifie livraison gratuite pour ce pays.

Fixed price per: Order (par défaut) facture le tarif 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 le colis entier.

Conditions

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

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

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.

Free shipping: active la livraison 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 la livraison est gratuite. Aucune requête d'API n'est alors envoyée.

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

Geo zone: proposer Correios uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie sans limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Non utilisé avec Ignore shipping zones.

Disponibilité sans zones de livraison

Normalement, le mode est proposé dans la zone géographique sélectionnée dans Conditions (dans toutes les zones si aucune n'est sélectionnée).

Ignore shipping zones: proposer le mode pour les pays ci-dessous, quelle que soit la zone géographique correspondante. La Geo zone de Conditions n'est alors pas vérifiée.

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

Avancé

Debug log: consigne les calculs de tarifs dans storage/logs/vfd_crr_debug.log.php (sur OpenCart 4, system/storage/logs/vfd_crr_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours consignées, même lorsque cette option est désactivée. L'utilisateur de l'API, le code d'accès, la carte de dépôt, le jeton et les CEP des clients ne sont pas consignés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_crr_debug.old.log.php et un nouveau journal est démarré.

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 de l'extension supprime les réglages Correios et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les services Correios enregistrés avec les commandes sont toujours conservés.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le code d'accès n'est pas exporté.

Import: collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Le code d'accès enregistré est conservé.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif Correios. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve hors de cette zone, Correios 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 les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimum de commande. Le montant de la commande correspond au prix des produits nécessitant une livraison, après la remise du coupon et avant taxes. Si la livraison gratuite s'applique, le tarif est de 0 et aucune requête n'est envoyée à Correios.

Pour une adresse au Brésil avec des identifiants renseignés, l'extension obtient d'abord un jeton d'API pour votre carte de dépôt. Le jeton fournit aussi les numéros de contrat et de bureau régional, de sorte que le tarif est celui de votre contrat. Elle demande ensuite le tarif du service choisi selon le CEP d'origine et de destination, le poids du colis en grammes et la taille du colis en cm. Un tarif 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 de Correios est envoyée. Les colis de plus de 30 kg ne sont pas envoyés à l'API. Le tarif en BRL est converti avec votre taux. Le tarif est calculé dans la devise par défaut de votre boutique, arrondi selon ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Chaque tarif est mis en cache pendant 1 heure. 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 avant son expiration (au maximum pendant la durée de vie du cache d'OpenCart, 1 heure par défaut) et renouvelé automatiquement ; si Correios le refuse, un nouveau jeton est demandé et la requête de tarif 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 tarif, le tarif fixe est utilisé, ou le mode est masqué lorsqu'il n'existe pas de tarif fixe. Le client ne voit jamais les détails des erreurs de l'API ; ils sont consignés dans le journal de débogage.

L'extension calcule uniquement les tarifs. Elle n'obtient pas les tarifs internationaux de Correios (Exporta Fácil, Packet), les estimations de délais de livraison, les étiquettes, les pré-enregistrements, les déclarations ou le suivi. Les clients ne peuvent pas choisir une agence ou un point relais Correios. Les services supplémentaires (valeur déclarée, remise en main propre, avis de réception) ne sont pas ajoutés. Elle affiche un seul service Correios par boutique, et les taux de change ne sont pas mis à jour automatiquement.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Correios dans la fenêtre Shipping method options. Le mode fonctionne de la même façon que sur OpenCart 3.

Commandes

Lorsqu'une commande est passée avec Correios, l'extension enregistre la manière dont son tarif de livraison a été calculé. La page de commande dans Sales > Orders affiche alors un bloc Correios avec Correios service (par exemple PAC — contract (03298)) et Price : Live price (Correios API), Fixed price ou Free shipping. Le bloc n'est affiché que dans l'administration, pas dans les e-mails des clients, et reste visible lorsque l'extension est désactivée.

Sur OpenCart 4, le paiement conserve une seule commande et la met à jour lorsque le client confirme à nouveau. Les données Correios de la commande sont mises à jour avec elle, et si le client passe à un autre mode de livraison, le bloc Correios n'est plus affiché pour cette commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Correios est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox Correios > Edit, 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) 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 figurent la ligne Product: opencart-shipping-correios et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation Modify pour l'extension peuvent modifier 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 de l'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, Correios n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration depuis 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, donc 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é à nouveau 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 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é. Vérifiez la Geo zone (ou Ignore shipping zones et Countries), les limites de poids et le Minimum order amount. Sans tarif en temps réel, un tarif fixe doit exister pour le pays ou pour *. Vérifiez que les produits ont Requires Shipping sur Yes.

Le mode affiche un tarif fixe au lieu du tarif Correios : consultez le champ Log sur la page de l'extension. Les erreurs de Correios y sont consignées : code d'accès incorrect, 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 de l'API, le code d'accès, la carte de dépôt et l'environnement. Un code d'accès d'homologation ne fonctionne qu'avec Homologation activé, et un code de production uniquement lorsqu'il est désactivé.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs en cache et le jeton d'API.

La page indique "Warning: You do not have permission to modify VibeFox Correios!" : 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_correios (OpenCart 3) ou extension/vfd_correios/shipping/vfd_correios (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'hôte de l'API Correios peut être remplacé par le réglage vfd_crr_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 Correios. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Correios, Sort order, Tax class et Geo zone. Les tarifs et jetons en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Correios et le journal de débogage 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 services Correios enregistrés avec les commandes sont toujours conservé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 Correios dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet envoyé.

Correios est une marque commerciale de son titulaire. Cette extension n'est ni affiliée à Correios ni approuvée par Correios.