VibeFox Correios for WooCommerce — Aide
Prérequis
WordPress : 5.8 ou ultérieur.
WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.
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 posting card. Il vous faut trois valeurs : votre identifiant Meu Correios (en général 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 d'où vous expédiez. Sans identifiants, l'extension fonctionne uniquement avec des tarifs fixes.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.
Installation
1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_correios dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Correios, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. 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 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).
6. Ajoutez VibeFox Correios à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez des pays.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Correios. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :
Title (zone) : le nom affiché au client pour cette zone. Laissez-le vide pour utiliser le Method title général.
La page des réglages affiche des avertissements lorsque les tarifs en temps réel ou la méthode 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 enregistrement des réglages, les tarifs en cache et le jeton d'API sont effacés. Les nombres peuvent être saisis avec un point ou une virgule.
Général
Enable/Disable : active ou désactive la méthode dans toutes les zones à la fois.
Method title : le nom de la méthode de livraison affiché dans le panier et au paiement. Par défaut : Correios. Une zone peut le remplacer par son propre titre.
Tax status : Taxable ajoute la taxe WooCommerce au coût de la livraison, None ne l'ajoute pas.
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 la méthode est masquée s'il n'y en a pas.
API user : votre identifiant de connexion au portail Meu Correios, en général 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.
Posting card : le numéro de posting card (cartão de postagem) de votre contrat : 10 chiffres, commençant en général 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 de test (homologation) de Correios 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 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 incluant 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. S'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. Default: 0.3. Les poids et dimensions des produits sont convertis depuis les unités de votre boutique, et le panier est tarifé comme un seul colis.
BRL → store currency rate : le nom du champ affiche la devise de votre boutique. Les tarifs Correios sont en BRL. Si la devise de votre boutique n'est pas le BRL, saisissez combien d'unités de votre devise vaut 1 BRL, par exemple 0.17. Sans ce taux, les tarifs en temps réel ne sont pas utilisés. Si la devise de votre boutique est le BRL, laissez-le vide.
Tarifs fixes (pour les pays hors du Brésil, sans identifiants API, et en 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 de votre boutique : 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 la croix pour en supprimer une. La ligne * Default (all other countries) fixe les tarifs de tous les pays qui n'ont pas leur propre ligne. Un pays sans ligne (et sans *) n'a pas de tarif fixe. Un tarif de base de 0 signifie livraison gratuite pour ce pays.
Fixed price per : Order 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 l'ensemble du colis.
Conditions
Min cart weight (kg) : masque la méthode en dessous de ce poids de panier. 0 signifie aucune limite.
Max cart weight (kg) : masque la méthode au-dessus de ce poids de panier. Par défaut : 30. 0 signifie aucune limite. Les colis PAC et SEDEX de Correios peuvent peser jusqu'à 30 kg.
Minimum order amount : n'affiche la méthode que lorsque le sous-total du panier atteint ce montant. Laissez vide pour toujours l'afficher.
Excluded shipping classes : masque la méthode si un article du panier appartient à l'une de ces classes d'expédition WooCommerce.
Free shipping : active la livraison gratuite à partir du montant ci-dessous.
Free shipping from : le sous-total du panier à partir duquel la livraison est gratuite. Dans ce cas, aucune requête n'est envoyée à l'API.
Disponibilité sans zones de livraison
Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, quelle que soit la zone correspondante.
Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels la boutique livre. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.
Avancé
Debug log : journalise les calculs de tarifs dans WooCommerce > Status > Logs, source vfd-correios. Les erreurs de l'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.
Remove data on uninstall : si activé, la suppression de l'extension efface ses réglages, ses méthodes de zone et ses tarifs en cache. La désactivation de l'extension ne supprime jamais rien.
Fonctionnement au paiement
Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, montant minimum de commande et classes d'expédition exclues. Si la livraison gratuite s'applique, le client obtient un tarif gratuit 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 posting card. Ce jeton fournit aussi les numéros de contrat et de bureau régional, de sorte que le prix est celui de votre contrat. Elle demande ensuite le tarif du service choisi selon les CEP d'origine et de destination, le poids du colis en grammes et ses dimensions en cm. Un tarif n'est demandé que si le CEP de destination comporte 8 chiffres. Si 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 tarif en BRL est converti avec votre taux. Le service est enregistré avec la ligne de livraison de la commande sous le nom Correios service et apparaît dans l'administration de la commande.
Chaque tarif 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 avant son expiration et renouvelé automatiquement ; si Correios le rejette, 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 la méthode est masquée s'il n'existe pas de tarif fixe. Le client ne voit jamais les détails des erreurs de l'API ; ceux-ci sont consignés dans le journal WooCommerce.
La méthode fonctionne sur le paiement classique ainsi que sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L'extension ne calcule que des tarifs. Elle n'obtient pas les tarifs Correios internationaux (Exporta Fácil, Packet), ni d'estimations de délais de livraison, ni d'étiquettes, de pré-envois, de déclarations ou de suivi. Les clients ne peuvent pas choisir d'agence ou de consigne 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.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Correios. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, Correios n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. 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. L'état est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Correios n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, Minimum order amount et Excluded shipping classes. Sans tarif en temps réel, un tarif fixe doit exister pour le pays ou pour *.
La méthode affiche un tarif fixe au lieu du tarif Correios : ouvrez WooCommerce > Status > Logs, source vfd-correios. L'erreur Correios y est consignée : 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é et, si la devise de la boutique 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 qu'avec Homologation activé, et un code de production uniquement avec cette option désactivée.
Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs en cache et le jeton d'API.
Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier état connu.
Désinstallation
La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de licence de cette extension sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs en cache ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils restent en place pour une réinstallation ultérieure. Les commandes ne sont jamais touchées.
Correios est une marque commerciale de son titulaire. Cette extension n'est ni affiliée à Correios ni approuvée par Correios.