VibeFox Melhor Envio for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
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 tokens (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). Los tokens de producción y de sandbox son distintos. No hay botón de «conectar»: pegas el token en los ajustes de la extensión. 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 dominio.
Instalación
La descarga es un único archivo zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_melhor_envio-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_melhor_envio.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.
OpenCart 3
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_melhor_envio-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Melhor Envio y haz clic en Install (el botón verde +).
3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes.
4. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Edit y haz clic en Activate (véase «Clave de licencia»).
5. Pega el token de acceso, tu correo electrónico de contacto y el CEP de origen. Si la moneda predeterminada de tu tienda no es BRL, define BRL exchange rate. Opcionalmente, rellena la tabla de precios de reserva (por ejemplo para Brasil) o un coste de reserva. Activa Enable Melhor Envio shipping y haz clic en Save.
OpenCart 4
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_melhor_envio.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.
2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.
3. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Melhor Envio, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).
4. Introduce la clave de licencia y los ajustes como en los pasos 4 y 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable Melhor Envio shipping y guardes. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. Las secciones aparecen a la izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra las cotizaciones de Melhor Envio en caché y el último error de la API. Solo los usuarios administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
Las advertencias en la parte superior de la página (y tras cada guardado) muestran una configuración incompleta: un CEP de origen vacío o que no tenga 8 dígitos, un correo electrónico de contacto que falta, un tipo de cambio a BRL que falta, ningún token y ningún precio de reserva (en ese caso el método nunca se muestra), el último error de la API de Melhor Envio con su fecha (cuando hay un token guardado), o una tienda sin clase de peso «kg» o sin clase de longitud «cm» (las unidades se convierten entonces por su nombre, y las unidades desconocidas se leen como kg o cm). Si Name está vacío, es demasiado largo o contiene alguno de los caracteres < > ; = # { }, si un campo numérico contiene algo que no es un número de 0 o más, si Min weight es mayor que Max weight, o si Default product size no tiene la forma largo x ancho x alto, la página muestra un error y no se guarda nada.
General
Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica en Availability. El precio siempre procede de la extensión.
Enable Melhor Envio shipping: muestra u oculta Melhor Envio en la finalización de compra. Predeterminado: off.
Name: el nombre del método de envío que ven los clientes en el carrito y en la finalización de compra. Predeterminado: Melhor Envio. Obligatorio, máximo 64 caracteres.
Sort order: la posición de Melhor Envio entre los métodos de envío en la finalización de compra. Un número entero.
Melhor Envio API
Access token: el token del entorno seleccionado abajo. Se envía a Melhor Envio como token Bearer. Tras guardar, el campo queda vacío y muestra A token is saved — leave empty to keep it. Escribe un token nuevo solo para 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 hacer pruebas. Usa con él un token de sandbox. Predeterminado: off.
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, por ejemplo tech@example.com. Melhor Envio lo exige a todas las integraciones. Una dirección no válida no se guarda, y se muestra un aviso.
Origin CEP: el CEP (8 dígitos) desde el que se envían los paquetes, por ejemplo 01310-100. OpenCart no tiene código postal de tienda, así que las cotizaciones en vivo necesitan este campo. Un CEP que no tenga 8 dígitos se guarda con un aviso, pero no se piden cotizaciones.
Services: IDs de servicio de Melhor Envio separados por comas que se quieren cotizar de forma 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 junto al nombre, por ejemplo «(3-5 business days)». Predeterminado: on.
Declared value: declara el valor del producto (seguro) en las cotizaciones. Cuando está desactivado, las cotizaciones se hacen sin valor declarado: más baratas, pero los paquetes no están asegurados. Predeterminado: on.
BRL exchange rate: Melhor Envio cotiza en reales brasileños. Solo es necesario 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, no se usan las cotizaciones en vivo. 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 indica que se usan los precios de Melhor Envio tal cual.
Default product weight (kg): se usa para los 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 (cm): largo x ancho x alto, se usa para los 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 ninguna cotización (error, tiempo de espera o falta de cobertura).
Fallback price table: precio por país y peso del carrito, sin impuestos. Haz clic en Add country para añadir una fila (una fila nueva empieza con Brasil) y en el botón de eliminar para borrar una. Elige * Any country para cada país sin fila propia. Cada fila tiene un Price y columnas de peso: XS hasta 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg y XL por encima de 5 kg. Una columna vacía o 0 usa el Price, y un Price de 0 significa envío gratuito. Se aceptan tanto «9.99» como «9,99». Los valores que no son números se notifican tras guardar y se ignoran. Las filas sin ningún precio se eliminan.
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 (predeterminado) 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. Esto se aplica solo a los precios de reserva. Las cotizaciones de Melhor Envio ya incluyen todos los artículos.
Disponibilidad
Min weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite (predeterminado).
Max weight (kg): oculta el método cuando el carrito pesa más. Predeterminado: 30. 0 significa sin límite. Un campo vacío significa 30 kg, o sin límite cuando Ignore shipping zones está activado.
Minimum subtotal: muestra el método solo si el subtotal del carrito (productos que requieren envío, después del cupón, 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.
Tax class: la clase de impuesto que se añade sobre el coste de envío, o No tax (predeterminado). Los precios de Melhor Envio son precios finales de las transportistas. Elige No tax si OpenCart no debe añadirles impuestos.
Geo zone: ofrece Melhor Envio solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. La zona geográfica no se comprueba cuando Ignore shipping zones está activado.
Disponibilidad sin zonas de envío
Normalmente el método se ofrece en la zona geográfica seleccionada en Availability (todas las zonas cuando no hay ninguna seleccionada).
Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona geográfica seleccionada. En este modo no se comprueba la zona geográfica.
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 storage/logs/vfd_menv_debug.log.php (en OpenCart 4, system/storage/logs/vfd_menv_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, aunque esta opción esté desactivada. El token nunca se registra y el CEP del cliente se abrevia a sus primeros 5 dígitos. Cuando el archivo llega a 5 MB, se traslada a vfd_menv_debug.old.log.php y se inicia un registro nuevo.
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: cuando está activado, al desinstalar la extensión se borran todos los ajustes y el registro. Cuando está desactivado (predeterminado), se conservan 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.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El token de acceso no se exporta.
Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. El token de acceso guardado se conserva.
Cómo funciona en la finalización de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de Melhor Envio. Si se ha definido una Geo zone y la dirección está fuera de ella, Melhor Envio no se ofrece. Con Ignore shipping zones, la zona geográfica no se comprueba: Melhor Envio se ofrece solo cuando el país está en Countries (o Countries está vacío). Solo cuentan los productos con Requires Shipping establecido en Yes: los demás productos no añaden peso y no se incluyen en el subtotal. Después, la extensión comprueba el peso del carrito y el subtotal mínimo.
Para una dirección de entrega en Brasil con un CEP de 8 dígitos, la extensión envía a Melhor Envio el CEP de origen y el de destino, y todos los artículos enviables con su peso, tamaño, cantidad y valor declarado, además de la lista de servicios si has definido una. El Model del producto se envía como ID del artículo. Los servicios con error o sin precio se omiten. Las cotizaciones se convierten a tu moneda predeterminada, se redondean a sus decimales, se ordenan por precio y se muestran en la moneda del cliente con el impuesto de la Tax class seleccionada. Si se aplica el envío gratuito, el servicio más barato cuesta 0.
Con One option - the cheapest service, el cliente ve una opción, por ejemplo Melhor Envio (6-7 business days). Con One option per service, el cliente ve una opción por servicio, por ejemplo Melhor Envio: Correios SEDEX (1-2 business days). La estimación de entrega solo se añade cuando Delivery time está activado.
Cada cotización se guarda en caché durante 1 hora, 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 aún no tiene un CEP válido, falta el tipo de cambio a BRL, o Melhor Envio devuelve un error o ningún servicio para esa ruta, se usan los precios de reserva: la fila del país (o la fila * cuando el país no tiene fila), y si no, el coste de reserva. Esa opción se llama simplemente como indica el Name. Si se aplica el envío gratuito, el método se muestra sin coste aunque no haya precio. Si no hay ningún precio, el método se oculta. El cliente nunca ve un error de la API. El motivo se escribe en el registro.
En OpenCart 4 el cliente hace clic en Choose en el bloque del método de envío de la página de finalización de compra y elige una opción de Melhor Envio en la ventana Shipping method options. Las opciones y los precios son los mismos que en OpenCart 3.
La extensión solo calcula precios. No compra ni genera etiquetas, no añade envíos al carrito de Melhor Envio, no rastrea paquetes, no programa recogidas y no envía datos de factura (NF-e). No ofrece la selección de agencias transportistas (puntos de entrega). Gestiona los envíos en tu panel de Melhor Envio. Melhor Envio envía solo dentro de Brasil. Los demás países reciben solo los precios de reserva.
Pedidos
OpenCart guarda el nombre de la opción elegida como método de envío del pedido, de modo que el servicio y la estimación de entrega aparecen en los correos electrónicos de pedido, en la cuenta del cliente y en Sales > Orders.
Cuando se realiza un pedido con una cotización en vivo, la extensión guarda también el servicio de Melhor Envio exactamente como lo vio el cliente en el paso de envío, sin hacer una nueva solicitud. La página de pedidos del administrador en Sales > Orders muestra un bloque Melhor Envio con Melhor Envio service, Service ID y Delivery estimate, para que sepas qué servicio comprar en Melhor Envio. El cliente ve Melhor Envio service y Delivery estimate en la página de pedido de su cuenta. Los pedidos realizados con un precio de reserva no tienen servicio. Los pedidos existentes no se ven afectados.
En OpenCart 4, el bloque Melhor Envio se muestra encima de History. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar: el servicio guardado se actualiza con él, y se elimina cuando el cliente cambia a otro método de envío o cuando el pedido recibe un precio de reserva.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Melhor Envio es el primer bloque de Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit, 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: opencart-shipping-melhor-envio y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (se incluyen el inglés y el ruso).
Si no se acepta la clave, 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. Tras cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío de Melhor Envio no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el administrador en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método se oculta a todos. Tras abrir una vez la página Edit, aparece un recordatorio en el Dashboard del administrador. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del administrador o la página Edit: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. No hace falta ninguna tarea cron. Desinstalar la extensión elimina siempre 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. Revisa la Geo zone, o activa Ignore shipping zones y revisa Countries. Consulta las advertencias de la parte superior de la página de la extensión, los límites de peso y el Minimum subtotal. Sin token o sin cotización, el método necesita un precio de reserva: una fila en la Fallback price table o un Fallback cost. Comprueba que los productos tengan Requires Shipping establecido en Yes.
Solo se muestran precios de reserva: activa Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Motivos habituales: no hay token, un CEP de origen que no tiene 8 dígitos, no hay 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 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.
Se añade impuesto al precio de Melhor Envio: define Tax class como No tax.
Las cotizaciones parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las cotizaciones en caché.
La página dice "Warning: You do not have permission to modify VibeFox Melhor Envio!": tu grupo de usuarios administradores solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_melhor_envio (OpenCart 3) o extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de cotizaciones de Melhor Envio puede sustituirse con el ajuste vfd_menv_api_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Melhor Envio. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Melhor Envio shipping, Sort order, Tax class y Geo zone. La caché de cotizaciones siempre se elimina. Si Remove data on uninstall está activado, los demás ajustes y el registro de depuración también se borran. Si está desactivado, se conservan y se usan de nuevo al volver a instalar la extensión. Los servicios guardados con los pedidos siempre se conservan, y los pedidos existentes mantienen su método de envío y su coste.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Melhor Envio en la lista de extensiones instaladas y, después, en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.
Melhor Envio es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni cuenta con el respaldo de Melhor Envio.