VibeFox Melhor Envio for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Cuenta de Melhor Envio (solo para cotizaciones en vivo): las cotizaciones en vivo requieren un token de acceso. En tu cuenta de Melhor Envio abre la página de tokens (melhorenvio.com.br/painel/gerenciar/tokens) y genera un token con el permiso «shipping-calculate». Para 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. No hay botón de «conectar»: pegas el token en la configuración del módulo. Sin token, el transportista 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 el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure, o busca VibeFox Melhor Envio más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Pega el token de acceso, tu correo de contacto y el CEP de origen. Si la moneda predeterminada de tu tienda no es BRL, establece BRL exchange rate. Opcionalmente, rellena la tabla de precios de reserva (por ejemplo, para Brasil) o un coste de reserva. Haz clic en Save.
Al instalar, el módulo crea el transportista Melhor Envio con el texto de plazo de entrega Delivery by the carriers of your Melhor Envio account. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar zonas, grupos de clientes, plazo de entrega, logotipo y límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre viene del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Melhor Envio > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las cotizaciones de Melhor Envio en caché y el último error de la API.
Las advertencias de la parte superior de la página muestran una configuración incompleta: un CEP de origen vacío o que no tiene 8 dígitos, falta el correo de contacto, falta el tipo de cambio BRL, el último error de la API de Melhor Envio con su fecha, no hay token y no hay precio de reserva (entonces el transportista nunca se muestra), o una unidad de peso o de dimensiones de la tienda que el módulo no reconoce (se lee entonces como kg o cm). Si un campo numérico contiene algo que no es un número igual o superior a 0, Min weight es mayor que Max weight, o Default product size no tiene el formato longitud x anchura x altura, la página muestra un error y no se guarda nada.
General
Enable Melhor Envio shipping: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del transportista que ven los clientes en la finalización de compra. Predeterminado: Melhor Envio. Obligatorio, 64 caracteres como máximo.
Tax: la regla de impuesto del transportista, o No tax. Los precios de Melhor Envio son precios finales del transportista. Elige No tax si PrestaShop no debe añadir impuestos a esos precios.
Melhor Envio API
Access token: el token del entorno seleccionado abajo. Se envía a Melhor Envio como token Bearer. Después de guardar, el campo queda vacío y muestra A token is saved — leave empty to keep it. Escribe un token nuevo solo si quieres cambiarlo. Para borrar el token guardado, marca Remove the saved token y guarda. El token nunca se escribe en el registro.
Sandbox: usa el sandbox de Melhor Envio (sandbox.melhorenvio.com.br) para pruebas. Úsalo con un token de sandbox. Predeterminado: desactivado.
Contact e-mail: un correo electrónico de contacto técnico, que se envía a Melhor Envio en la cabecera User-Agent de cada solicitud. Melhor Envio lo exige a todas las integraciones. Una dirección no válida no se guarda y aparece un aviso.
Origin CEP: el CEP (8 dígitos) desde el que se envían los paquetes, por ejemplo 01310-100. Se guarda en formato 00000-000. Sin un CEP de origen válido no se piden cotizaciones.
Services: ID de servicios de Melhor Envio separados por comas, para cotizar (opcional), 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 la estimación de entrega de Melhor Envio en la finalización de compra, por ejemplo "3-5 business days". Predeterminado: 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. Predeterminado: activado.
BRL exchange rate: Melhor Envio cotiza en reales brasileños. Solo hace falta si la moneda predeterminada de tu tienda no es BRL: introduce el precio de 1 BRL en tu moneda predeterminada, por ejemplo 0.17. Sin él, las cotizaciones en vivo no se usan. El valor debe ser mayor que 0. El valor declarado se convierte a BRL con el mismo tipo de cambio. Si tu moneda predeterminada es BRL, el campo muestra Store currency is BRL.
Default product weight: en kg, para productos sin peso, tanto en las cotizaciones como en los límites de peso. Debe ser mayor que 0. Predeterminado: 0.3.
Default product size: longitud x anchura x altura en cm, para productos sin dimensiones. Predeterminado: 16x11x5.
Precios de reserva (en la moneda predeterminada de tu tienda)
Los precios de reserva se usan cuando no hay token, falta el CEP de destino o la API no da cotización (error, tiempo de espera, 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 el icono de papelera para eliminar una. Elige * Default como país 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 después de guardar y se ignoran.
Fallback cost: se usa cuando la tabla tampoco tiene precio. Déjalo vacío para ocultar el transportista en ese caso.
Fallback calculation: Per order cobra el precio de reserva una 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. Si un artículo no tiene precio, el transportista se oculta. Esto se aplica solo a los precios de reserva. Las cotizaciones de Melhor Envio ya incluyen todos los artículos.
Disponibilidad
Min weight: oculta el transportista cuando el carrito pesa menos, en kg. 0 significa sin límite.
Max weight: oculta el transportista cuando el carrito pesa más, en kg. Predeterminado: 30. 0 significa sin límite. Un campo vacío significa 30 kg en las zonas del transportista, y sin límite solo para los países de Ignore shipping zones que queden fuera de ellas.
Minimum subtotal: muestra el transportista solo si el subtotal del carrito (productos que necesitan envío, 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 desde el que 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.
Ignore shipping zones: ofrece el transportista en los países indicados abajo aunque no esté asignado a sus zonas. Mientras está activado, el transportista se vincula a todas las zonas, incluidas las zonas inactivas y las creadas más adelante. Al desactivarlo, el transportista recupera sus propias zonas.
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.
Avanzado
Debug log: escribe las solicitudes a la API y el cálculo de tarifas en logs/vfd_menv_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso con esta opción desactivada. El token nunca se registra y el CEP del cliente se acorta a sus primeros 5 dígitos.
Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar el módulo se borran todos sus ajustes, el transportista y el registro. Si está desactivado, todo se conserva para una reinstalación. La caché de cotizaciones siempre se elimina. Los servicios guardados con los pedidos forman parte del historial de pedidos y se conservan.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de Melhor Envio. Solo cuentan los productos que necesitan envío: los productos virtuales no suman peso y no se incluyen en el subtotal. El módulo comprueba primero las condiciones: los países de Ignore shipping zones, el peso del carrito y el subtotal mínimo.
Para una dirección de entrega en Brasil con un CEP de 8 dígitos, el módulo 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 configurado una. Las cotizaciones se convierten a tu moneda predeterminada, se ordenan por precio y después se muestran en la moneda del carrito del cliente. Si se aplica envío gratuito, el servicio más barato cuesta 0.
Con One option - the cheapest service, el transportista muestra el precio del servicio más barato y la línea Delivery estimate: debajo del transportista si Delivery time está activado. Con One option per service, el cliente ve Choose a delivery service: debajo del transportista, con un botón de opción por servicio, su precio y la estimación de entrega. La elección se guarda de inmediato, y se actualizan el precio del transportista y el resumen del carrito. Si el servicio ya no se ofrece para la dirección, el cliente ve This service is not available for your address any more. Please choose another one. y vuelve la elección anterior.
Cada cotización se guarda en caché durante 1 hora por paquete, CEP, token y entorno, así que el mismo carrito no genera 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 aún 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 *); si no existe, el coste de reserva. Si se aplica envío gratuito, el transportista se muestra sin coste aunque no haya precio. Si no hay ningún precio, el transportista se oculta. El cliente nunca ve un error de la API.
Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.
El módulo 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 factura (NF-e). No ofrece la selección de agencias (puntos de entrega) de Jadlog, Azul o LATAM, ni los servicios extra de entrega en mano propia y acuse de recibo. Gestiona los envíos en tu panel de Melhor Envio. Melhor Envio envía solo dentro de Brasil. Otros países reciben solo los precios de reserva.
Pedidos
Cuando se realiza un pedido con cotización en vivo, el módulo guarda con el pedido el servicio de Melhor Envio y su estimación de entrega. La página de pedido del back office muestra un bloque Melhor Envio con Melhor Envio service (con el ID del servicio) y Delivery estimate, para que sepas qué servicio comprar en Melhor Envio. El cliente ve la misma información en la página de su pedido en su cuenta. En el correo de confirmación del pedido se añaden después del nombre del transportista. Los pedidos con precio de reserva no tienen servicio. Los pedidos existentes no se ven afectados.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Melhor Envio es el primer bloque de Modules > Module Manager > VibeFox Melhor Envio > Configure, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-melhor-envio y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).
Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, el transportista de Melhor Envio no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo siempre elimina la clave de licencia y el estado de la licencia.
Solución de problemas
Melhor Envio no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Melhor Envio shipping esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente, o activa Ignore shipping zones y revisa Countries. Revisa las advertencias de la parte superior de la página del módulo, los límites de peso y Minimum subtotal. Sin token ni cotización, el transportista necesita un precio de reserva: una fila en Fallback price table o un Fallback cost. Los productos también pueden limitarse a ciertos transportistas en la página del producto.
Solo se muestran precios de reserva: activa Debug log, recarga la finalización de compra y mira el campo Log de la página del módulo. Motivos habituales: no hay token, el CEP de origen no tiene 8 dígitos, falta el BRL exchange rate para una moneda predeterminada 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 rechazó 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 coincida con él.
El cliente ve "The service could not be saved. Please try again.": la elección no llegó a la tienda, por ejemplo por un error de red. El cliente puede volver a elegir el servicio. El servicio seleccionado cuando el cliente hace clic en Continue también se guarda.
El impuesto se añade al precio de Melhor Envio: configura Tax en No tax.
Las cotizaciones parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las cotizaciones en caché.
La página indica que no se encontró el transportista de Melhor Envio: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para crearlo de nuevo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Melhor Envio y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. La caché de cotizaciones siempre se elimina. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial), se restauran sus propias zonas y se borran los ajustes, las elecciones de servicio de los carritos abiertos y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, el transportista recupera el estado que tenía antes. Los servicios guardados con los pedidos siempre se conservan.
Melhor Envio es una marca registrada de su respectivo titular. Este módulo no está afiliado ni respaldado por Melhor Envio.