VibeFox Melhor Envio for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Cuenta de Melhor Envio (solo para cotizaciones en vivo): las cotizaciones en vivo necesitan un token de acceso. En tu cuenta de Melhor Envio abre la página de permisos de acceso para tokens (Integrações > Permissões de acesso, melhorenvio.com.br/painel/gerenciar/tokens) y genera un token con el permiso «shipping-calculate». Para hacer pruebas, genera un token en el sandbox de Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Los tokens de producción y de sandbox son distintos. Los tokens caducan. No hay botón de «conectar»: pegas el token en los ajustes. Sin token, el método usa los precios de reserva.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_melhor_envio a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox Melhor Envio, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Pega el token de acceso, tu correo electrónico de contacto y el CEP de origen. Si la moneda de tu tienda no es BRL, configura BRL exchange rate. Opcionalmente, rellena la tabla de precios de reserva (por ejemplo, para Brasil) o un coste de reserva.
6. Añade una zona para Brasil en WooCommerce > Settings > Shipping > Shipping zones y añade VibeFox Melhor Envio a ella, o activa Ignore shipping zones y elige los países.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Se aplican a todas las zonas de envío. Cuando añades el método a una zona, la ventana de la zona tiene un solo campo:
Title (zone): el nombre de esta opción en la finalización de compra. Déjalo vacío para usar el Name global.
Las advertencias de la parte superior de la página indican una configuración incompleta: un CEP de origen que no tiene 8 dígitos, un correo electrónico de contacto que falta, un tipo de cambio BRL que falta, el último error de la API de Melhor Envio con su fecha, o ningún token y ningún precio de reserva. Cada vez que guardas los ajustes, se borran las cotizaciones en caché.
General
Enable/Disable: activa o desactiva el envío de Melhor Envio en todas las zonas a la vez.
Name: el nombre del método de envío que ven los clientes en la finalización de compra. Por defecto: Melhor Envio.
Tax status: Taxable añade el impuesto de WooCommerce al coste del envío; None no lo añade.
Melhor Envio API
Access token: el token del entorno seleccionado abajo. Nunca se escribe en el registro.
Sandbox: usa el sandbox de Melhor Envio (sandbox.melhorenvio.com.br) para hacer pruebas. Úsalo con un token de sandbox. Por defecto: desactivado.
Contact e-mail: un correo electrónico de contacto técnico, que se envía a Melhor Envio con cada solicitud. Melhor Envio lo exige a todas las integraciones.
Origin CEP: el CEP (8 dígitos) desde el que se envían los paquetes, por ejemplo 01310-100. Sin un CEP de origen válido no se solicita ninguna cotización.
Services: ID de servicio de Melhor Envio opcionales, separados por comas, para cotizar, por ejemplo 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Déjalo vacío para cotizar todos los servicios de tu cuenta.
Quotes at checkout: cómo se muestran las cotizaciones.
Delivery time: muestra junto al nombre la estimación de entrega de Melhor Envio, por ejemplo «(3-5 business days)». Por defecto: activado.
Declared value: declara el valor del producto (seguro) en las cotizaciones. Cuando está desactivado, las cotizaciones se hacen sin valor declarado: son más baratas, pero los paquetes no están asegurados. Por defecto: activado.
BRL exchange rate: Melhor Envio cotiza en reales brasileños. Solo es necesario si la moneda de tu tienda no es BRL: introduce el precio de 1 BRL en la moneda de tu tienda, por ejemplo 0.17. Sin él, no se usan las cotizaciones en vivo. El valor declarado se convierte a BRL con el mismo tipo de cambio.
Default product weight (kg): se usa para los productos sin peso, tanto en las cotizaciones como en los límites de peso. Por defecto: 0.3.
Default product size (cm): largo x ancho x alto, que se usa para los productos sin dimensiones. Por defecto: 16x11x5.
Fallback prices (en la moneda de tu tienda)
Los precios de reserva se usan cuando no hay token, falta el CEP de destino o la API no devuelve ninguna cotización (error, tiempo de espera o sin cobertura).
Fallback price table: precio por país y peso del carrito. Haz clic en + Add country para añadir una fila y en la × para eliminar una. Elige * Any country para todos los países que no tengan fila propia. Cada fila tiene una columna Price y columnas de peso: XS hasta 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg y XL más de 5 kg. Una columna vacía o con 0 usa Price. Se aceptan tanto «9.99» como «9,99». Los valores que no son números se notifican tras guardar y se ignoran.
Fallback cost: se usa cuando la tabla tampoco tiene precio. Déjalo vacío para ocultar el método en ese caso.
Fallback calculation: Per order cobra el precio de reserva una sola vez. Per item (each item priced by its own weight x quantity) busca el precio de reserva para el peso de cada artículo (el peso predeterminado si no tiene) y lo multiplica por su cantidad. Esto se aplica solo a los precios de reserva. Las cotizaciones de Melhor Envio ya incluyen todos los artículos.
Availability
Min weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite.
Max weight (kg): oculta el método cuando el carrito pesa más. Por defecto: 30. 0 significa sin límite.
Minimum subtotal: muestra el método solo si el subtotal del carrito (después de descuentos, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal del carrito a partir del cual el envío es gratuito. Con una opción por servicio, solo el servicio más barato pasa a ser gratuito. Los servicios más rápidos mantienen su precio. Déjalo vacío para desactivarlo.
Excluded shipping classes: oculta el método cuando el carrito contiene artículos de cualquiera de estas clases de envío de WooCommerce.
Ignore shipping zones: ofrece el método para los países indicados abajo, aunque no se haya añadido a una zona de envío.
Countries: los países de destino para ese modo. Déjalo vacío para todos los países. Este campo solo se usa cuando Ignore shipping zones está activado.
Advanced
Debug log: registra las solicitudes a la API y el cálculo de tarifas en WooCommerce > Status > Logs (origen vfd-melhor-envio). Los errores siempre se registran, incluso con esta opción desactivada. El token y las direcciones de los clientes nunca se registran.
Remove data on uninstall: si está activado, al eliminar el plugin se borran todos sus ajustes y métodos de zona. Desactivar el plugin nunca borra los ajustes.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, WooCommerce pide al plugin una tarifa. El plugin comprueba primero las condiciones: peso del carrito, subtotal mínimo y clases de envío excluidas.
Para una dirección de entrega en Brasil con un CEP de 8 dígitos, el plugin envía a Melhor Envio el CEP de origen y de destino, y cada artículo enviable con su peso, tamaño, cantidad y valor declarado, además de la lista de servicios si has definido una. Las cotizaciones se convierten a la moneda de tu tienda y se ordenan por precio. El cliente ve el servicio más barato o una opción por servicio, con la estimación de entrega si está activada. Si se aplica el envío gratuito, el servicio más barato cuesta 0.
Cada cotización se guarda en caché durante 1 hora por paquete, CEP y entorno, para que el mismo carrito no genere una nueva solicitud. Una llamada fallida se recuerda durante 5 minutos, para que una caída de la API no ralentice cada actualización de la finalización de compra. El tiempo de espera de la API es de 12 segundos.
Si no hay token, la dirección está fuera de Brasil o todavía no tiene un CEP válido, falta el tipo de cambio BRL, o Melhor Envio devuelve un error o ningún servicio para la ruta, se usan los precios de reserva: la fila del país (o la fila *) y, si no existe, el coste de reserva. Si se aplica el envío gratuito, el método se muestra sin coste aunque no tenga precio. Si no hay ningún precio, el método se oculta. El cliente nunca ve un error de la API.
El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin solo calcula precios. No compra ni genera etiquetas, no añade envíos al carrito de Melhor Envio, no rastrea paquetes, no programa recogidas ni envía datos de la factura (NF-e). No ofrece la selección de agencias (puntos de entrega) de Jadlog, Azul o LATAM, ni los servicios extra «entrega en mano propia» y «aviso de recepción». Gestiona los envíos en tu panel de Melhor Envio. Melhor Envio solo envía dentro de Brasil. Los demás países reciben únicamente los precios de reserva.
Pedidos
Cuando el pedido se realiza con una cotización en vivo, el servicio y la estimación de entrega se guardan en la línea de envío del pedido. Se muestran en la pantalla del pedido y en los correos electrónicos del pedido como Melhor Envio service y Delivery estimate, para que sepas qué servicio contratar en Melhor Envio. Los pedidos existentes conservan sus líneas de envío.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Melhor Envio no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión sí lo ven, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Melhor Envio no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el método esté añadido a la zona del país del cliente (o que Ignore shipping zones esté activado y el país permitido). Revisa las advertencias de la parte superior de la página de ajustes, los límites de peso, Minimum subtotal y Excluded shipping classes. Sin token o sin cotización, el método necesita un precio de reserva: una fila en Fallback price table o un Fallback cost.
Solo se muestran precios de reserva: activa Debug log, recarga la finalización de compra y abre WooCommerce > Status > Logs, origen vfd-melhor-envio. Motivos habituales: no hay token, el CEP de origen no tiene 8 dígitos, no hay BRL exchange rate para una moneda de tienda distinta de BRL, todavía no hay CEP de destino o ningún servicio cubre la ruta.
HTTP 401 o 403 en el registro o en las advertencias: Melhor Envio ha rechazado el token de acceso. Es incorrecto, ha caducado o ha sido revocado, o pertenece al otro entorno. Genera un token nuevo y comprueba que Sandbox coincide con él.
Qué precio ven los clientes: con una opción, el servicio más barato que devuelve Melhor Envio. Con una opción por servicio, cada servicio que cubre la ruta. Per item se aplica solo a los precios de reserva.
Las cotizaciones parecen desactualizadas tras un cambio: guarda la página de ajustes. Así se borran las cotizaciones en caché.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los ajustes. Solo se borra la caché de cotizaciones. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin, así como las cotizaciones en caché, siempre se eliminan. Los ajustes y los métodos de zona solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus líneas de envío.
Melhor Envio es una marca comercial de su respectivo titular. Este plugin no está afiliado a Melhor Envio ni cuenta con su respaldo.