VibeFox Jadlog 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.
Contrato con Jadlog (para precios en tiempo real y puntos Pickup): los precios en tiempo real y la lista de puntos Pickup llegan desde la API Embarcador de Jadlog. Tu franquicia de Jadlog emite el acceso una vez firmado el contrato. Necesitas el token de la API Embarcador, el CNPJ (o CPF) del remitente registrado en el contrato, la cuenta corriente (conta corrente) y, si tienes uno, el número de contrato. Si solo usas precios fijos, no necesitas un contrato con Jadlog.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 Jadlog 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 la API, introduce el CNPJ, la cuenta corriente, el número de contrato y el CEP de origen, elige el servicio de Jadlog y, si la moneda predeterminada de tu tienda no es BRL, introduce el tipo de cambio a BRL. Añade precios fijos o un coste de respaldo si los quieres (ver Configuración). Haz clic en Save.
5. Para ofrecer también los puntos Jadlog Pickup, activa Enable Jadlog Pickup y haz clic en Save.
Al instalarlo, el módulo crea dos transportistas: Jadlog (entrega a domicilio, activado, texto del plazo de entrega Jadlog delivery to your address) y Jadlog Pickup (desactivado, texto del plazo Pickup at a Jadlog Pickup point). Ambos están vinculados a la zona de Brasil y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los 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 Jadlog > Configure. Se aplican a ambos transportistas de Jadlog. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra los precios de Jadlog y las listas de puntos Pickup en caché.
En la parte superior de la página, el módulo muestra advertencias si la configuración está incompleta: sin token de API (solo se usan precios fijos y no se pueden listar puntos Pickup), sin token de API y sin precios fijos (el método nunca se muestra), sin CNPJ ni cuenta corriente, sin CEP de origen, sin tipo de cambio a BRL en una tienda que no vende en BRL, una unidad de peso o de dimensiones de la tienda que el módulo no reconoce (entonces los pesos se toman en kg y las dimensiones en cm; configura las unidades en International > Localization, Local units), o un transportista de Jadlog que se ha eliminado. Al guardar, se notifican los valores incorrectos: un CEP sin 8 dígitos, un CNPJ sin 14 dígitos (u 11 para un CPF), un número no válido, un peso mínimo superior al peso máximo (ambos pesos conservan sus valores guardados), un país desconocido o un precio no válido en la tabla de precios.
General
Enable/Disable: activa o desactiva la entrega a domicilio de Jadlog. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista de entrega a domicilio que se muestra en el carrito y en la finalización de compra. Por defecto: Jadlog. Obligatorio.
Tax status: None o Taxable con una de tus reglas de impuesto. Se guarda en ambos transportistas de Jadlog. Los precios de Jadlog son precios finales del transportista. Elige None si PrestaShop no debe añadir impuestos a esos precios.
Jadlog live prices
Los precios en tiempo real solo se piden para direcciones en Brasil con un CEP completo de 8 dígitos.
API token: el token Embarcador de Jadlog. Puedes pegarlo con o sin la palabra "Bearer". Déjalo vacío para usar solo precios fijos. Tras guardar, el campo queda vacío y muestra Saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Remove the saved API token: marca la casilla y haz clic en Save para eliminar el token guardado.
CNPJ: el CNPJ (14 dígitos) o el CPF (11 dígitos) del remitente registrado en el contrato de Jadlog. Se admiten puntos, barras y guiones.
Current account (conta corrente): el número de tu cuenta corriente de Jadlog. Sin ella y sin el CNPJ, Jadlog no puede cotizar y solo se usan precios fijos.
Contract number: el número de tu contrato de Jadlog, si tu franquicia te dio uno.
Origin CEP: el código postal desde el que se envían los paquetes, de 8 dígitos. Se guarda en el formato 00000-000. Déjalo vacío para usar el código postal de la tienda de Shop Parameters > Contact > Stores, si la dirección de la tienda está en Brasil.
Jadlog service: el servicio (modalidade) de tu contrato para entrega a domicilio: .Package (3, por defecto), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) o Emergencial (14). Jadlog Pickup (40) es el segundo transportista.
Insurance type: Normal (N) (por defecto) o Own insurance policy (A - apolice), según se acuerde en tu contrato de Jadlog.
Volumetric weight: Jadlog cobra el mayor entre el peso real y el peso volumétrico.
BRL exchange rate: Jadlog cotiza en reales brasileños. Si la moneda predeterminada de tu tienda es BRL, este campo no es necesario. Si no lo es, introduce cuánto vale 1 BRL en tu moneda predeterminada, por ejemplo 0.16. El precio de Jadlog se multiplica por este tipo, y el valor declarado del pedido que se envía a Jadlog se convierte de nuevo a BRL. Sin el tipo de cambio no se usan precios en tiempo real y solo se aplican precios fijos. Se aceptan tanto el punto como la coma como separador decimal.
Delivery time: muestra el plazo de entrega que devuelve Jadlog en la finalización de compra, debajo del transportista de Jadlog y junto a cada punto Pickup, por ejemplo "Delivery time: 3 business days". Activado por defecto. El plazo de entrega siempre se guarda con el pedido.
Jadlog Pickup
Un segundo transportista con el servicio Pickup de Jadlog (40). Necesita el token de la API. Sin puntos, el transportista se oculta.
Enable Jadlog Pickup: activa o desactiva el transportista Jadlog Pickup. Es el mismo interruptor que su estado en Shipping > Carriers. Desactivado tras la instalación.
Jadlog Pickup carrier name: el nombre de esta opción en la finalización de compra. Por defecto: Jadlog Pickup. Obligatorio.
Points to show: cuántos puntos Pickup ofrecer, de 1 a 10. Por defecto: 5.
Fixed prices (se usan cuando no hay token de API, para los países que Jadlog no atiende y siempre que Jadlog no devuelve ningún precio)
Price per country: una tabla con las columnas Country, Price, XS, S, M, L y XL, en la moneda predeterminada de tu tienda. Haz clic en + Add country para añadir una fila y en el icono de la papelera para eliminar una. La columna de tamaño se elige según el peso del carrito: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg, XL por encima de 5 kg. Price se usa cuando la columna de tamaño está vacía. Precio 0 significa envío gratis para ese país. Usa * Default (other countries) para todos los demás países. Las filas sin ningún precio se eliminan al guardar.
Fallback cost: se usa cuando ni Jadlog ni la tabla dan un precio. Déjalo vacío para ocultar el transportista en ese caso.
Fixed price applies: Per order cobra el precio una vez. Per item (price x quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo a los precios fijos y al coste de respaldo. Los precios de Jadlog ya cubren todo el carrito.
Conditions
Minimum weight (kg): oculta los transportistas cuando el carrito pesa menos. 0 significa sin límite.
Maximum weight (kg): oculta los transportistas cuando el carrito pesa más. Por defecto: 150. 0 significa sin límite.
Minimum order amount: muestra los transportistas solo cuando el subtotal del carrito (productos que requieren envío, después de descuentos y antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlos siempre.
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual el envío es gratis. Déjalo vacío si no hay envío gratis.
Availability without shipping zones
Ignore shipping zones: ofrece Jadlog para los países indicados abajo, aunque sus transportistas no estén vinculados a su zona. Al activarlo, ambos transportistas se vinculan a todas las zonas activas, y las zonas creadas más tarde también se vinculan. Al desactivarlo de nuevo, los transportistas recuperan las zonas que tenían antes.
Countries: los países de destino para ese modo, fuera de las zonas propias de los transportistas. Déjalo vacío para permitir todos los países. Este campo solo se usa cuando Ignore shipping zones está activado.
Advanced
Debug log: registra cada petición y respuesta de Jadlog en logs/vfd_jdlg_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. El token, el CNPJ y la cuenta nunca se registran, y el CEP del cliente se acorta. Desactiva el registro cuando termines.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar el módulo se eliminan todos los ajustes de Jadlog y sus transportistas. Si está desactivado, desinstalar solo desactiva los transportistas. Los precios en caché siempre se eliminan. Los pedidos nunca se modifican.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de cada transportista de Jadlog. Solo cuentan los productos físicos: los productos virtuales no suman peso ni se incluyen en el importe del pedido. El módulo comprueba primero las condiciones: peso del carrito e importe mínimo del pedido y, con Ignore shipping zones, los países permitidos. Si el subtotal del carrito alcanza Free shipping from, el envío es gratis y no se envía ninguna petición de precio a Jadlog.
Para una dirección de entrega en Brasil con un CEP completo de 8 dígitos, el módulo envía a Jadlog el CEP de origen y de destino, el peso, tu CNPJ, la cuenta corriente, el contrato, el servicio, el tipo de seguro y el valor declarado del pedido. El precio devuelto se convierte a la moneda predeterminada de tu tienda y se muestra en la moneda del carrito del cliente. Los carritos sin peso se cotizan como 0,1 kg. Si no hay precio en tiempo real (sin token, dirección fuera de Brasil, CEP incompleto, sin tipo de cambio a BRL o error de Jadlog), el módulo usa la tabla Price per country y después el Fallback cost. Si ninguno da un precio, el transportista se oculta para ese carrito.
Cada precio se guarda en caché durante 1 hora, para que el mismo carrito no genere una nueva petición. Una petición fallida se guarda en caché durante 10 minutos. Si Jadlog no responde, devuelve un error del servidor o rechaza el token, la API no vuelve a llamarse durante 10 minutos. El tiempo de espera de la API es de 10 segundos. El cliente nunca ve un error de la API. El motivo se escribe en el registro.
Si editas un 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 y muestra puntos Pickup. No crea envíos de Jadlog, no imprime etiquetas, no solicita recogidas, no cancela envíos ni hace seguimiento de paquetes. No muestra un mapa de los puntos Pickup y no pide cotizaciones internacionales a Jadlog. Para otros países, usa precios fijos.
Puntos Pickup
El transportista Jadlog Pickup solo se ofrece para direcciones en Brasil, y solo cuando el token de la API está guardado. Cuando el cliente ha introducido un CEP completo de 8 dígitos, el módulo pide a Jadlog los puntos Pickup activos más cercanos y muestra hasta Points to show puntos debajo del transportista, cada uno con su precio, por ejemplo "nombre del punto — precio (3 business days) — dirección". Si la lista aún no está en caché, se carga cuando el cliente selecciona el transportista, para que el paso de envío no espere a Jadlog.
El precio de cada punto se pide a Jadlog. Si Jadlog no da precio para un punto, se usa el precio fijo, y un punto sin ningún precio se omite. Las listas de puntos se guardan en caché durante 12 horas. El precio del transportista es el precio del punto elegido. Antes de elegir un punto, es el precio del punto más cercano que tenga precio. Un punto sin precio no oculta el transportista mientras otros puntos tengan precio. Después de que el cliente elija un punto, el paso de envío se actualiza con el nuevo precio.
El punto es obligatorio. Sin punto, el cliente no puede continuar y ve Please select a Jadlog Pickup point. El módulo comprueba que el punto esté en la lista de Jadlog para el CEP de entrega. Si no lo está, el cliente ve The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. Cuando el CEP está incompleto, no hay puntos cercanos o Jadlog no está disponible, se muestra un mensaje debajo del transportista.
Sin token de API, sin CEP de 8 dígitos, cuando Jadlog no está disponible o cuando no hay puntos activos cerca, el transportista Jadlog Pickup se oculta. Un pedido sin punto no podría enviarse.
Pedidos
Cuando se realiza un pedido con un transportista de Jadlog, el módulo guarda el servicio de Jadlog y, si Jadlog lo devolvió, el plazo de entrega en días laborables. En un pedido de Jadlog Pickup también guarda el nombre, la dirección y el ID del punto Pickup.
La página de pedido del administrador muestra un bloque Jadlog con Jadlog service, Delivery time y, para Jadlog Pickup, Pickup point, Pickup point address y Pickup point ID. El cliente ve el punto elegido en la página de confirmación del pedido y en los detalles del pedido. El punto se añade al nombre del transportista en el correo electrónico de confirmación del pedido. El correo de nuevo pedido de la tienda (si usas el módulo de alertas por correo electrónico) también incluye el ID del punto.
Crea el envío en el sistema de Jadlog tú mismo. El pedido muestra el servicio y el ID del punto Pickup que necesitas para ello.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Jadlog es el primer bloque de Modules > Module Manager > VibeFox Jadlog > Configure, encima de los ajustes. Introduce 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 quitar la clave de esta tienda. Debajo están la línea Product: presta-shipping-jadlog 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 (incluye 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 acceder al 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, los transportistas de Jadlog no se muestran 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 los transportistas también se ocultan 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 requieren 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 por 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
Jadlog no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable (o Enable Jadlog Pickup) 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. Revisa las advertencias de la parte superior de la página del módulo, los límites de peso y el Minimum order amount. Si el cliente aún no ha introducido un CEP completo de 8 dígitos, solo pueden usarse precios fijos, así que añade una fila en Price per country o un Fallback cost. En la página del producto también se pueden limitar los productos a ciertos transportistas.
Solo se muestran precios fijos: activa Debug log, recarga la finalización de compra y mira el campo Log en la página del módulo. Muestra el motivo: sin CNPJ o cuenta corriente, sin CEP de origen, CEP de destino incompleto, sin tipo de cambio a BRL o el mensaje de error de Jadlog.
HTTP 401 o 403 en el registro: Jadlog rechazó el token de la API. Compruébalo con tu franquicia de Jadlog. La API se pausa durante 10 minutos tras este error. Guardar los ajustes elimina la pausa, así que puedes volver a intentarlo de inmediato.
Los puntos Pickup no aparecen: el transportista Jadlog Pickup necesita Enable Jadlog Pickup, el token de la API y un CEP completo de 8 dígitos en Brasil. Si Jadlog no tiene puntos activos cerca del CEP, el transportista se oculta. Revisa el registro para ver el motivo.
Los precios aparecen en reales en lugar de en mi moneda: introduce el BRL exchange rate (cuánto vale 1 BRL en la moneda predeterminada de tu tienda).
Los precios parecen demasiado bajos o demasiado altos: completa los pesos y las dimensiones de los productos. Los carritos sin peso se cotizan como 0,1 kg, y el peso volumétrico necesita dimensiones.
Se añade impuesto a los precios de Jadlog: pon Tax status en None.
Los precios parecen desactualizados tras un cambio: haz clic en Save en la página del módulo. Esto borra los precios de Jadlog y las listas de puntos Pickup en caché.
La página indica que no se encontró un transportista de Jadlog: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Jadlog y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Los precios en caché y las listas de puntos Pickup siempre se eliminan. Si Remove data on uninstall está activado, ambos transportistas se eliminan (los pedidos conservan su historial) y se borran los ajustes y el registro. Si está desactivado, los transportistas solo se desactivan y se conservan todos los ajustes. Al volver a instalar el módulo, los transportistas recuperan el estado que tenían. El servicio de Jadlog, el plazo de entrega y el punto Pickup guardados con los pedidos siempre se conservan.
Jadlog es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Jadlog ni avalado por la empresa.