VibeFox J&T Express 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.

Acceso a la API de J&T Express Malasia (solo para cotizaciones en tiempo real): las cotizaciones en tiempo real existen solo para J&T Express Malasia, para direcciones de entrega en Malasia. Necesitas cuatro valores. Solicita una cuenta VIP de J&T en el sitio web de J&T Express Malasia (la página del módulo tiene un enlace): J&T te entrega el código de cliente VIP y la clave de API VIP. La cuenta de API y la clave privada para firmar las solicitudes las emite J&T para la integración por API. Pídeselas a tu gestor de cuenta de J&T. J&T Filipinas, Indonesia y otros países no tienen una API pública de cotizaciones, así que para ellos usa la tabla de precios. Si solo usas la tabla de precios y el coste de reserva, no necesitas acceso a la API de J&T.

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 J&T Express 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 (véase Clave de licencia).

4. Rellena la tabla de precios y/o el coste de reserva. Para cotizaciones en tiempo real en Malasia, introduce también las credenciales de la API de J&T, el código postal del remitente y, si la moneda predeterminada de tu tienda no es MYR, el tipo de cambio de moneda (véase Configuración). Haz clic en Save.

Al instalar, el módulo crea el transportista J&T Express con el texto del plazo de entrega Courier delivery. El transportista se asigna a todas las zonas 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 definas 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 J&T Express > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las cotizaciones de J&T en caché. Si las cotizaciones en tiempo real están configuradas solo en parte, un aviso en la parte superior de la página indica los ajustes que faltan o te dice que falta el tipo de cambio de moneda. Los importes que no sean un número mayor o igual que 0 se rechazan con un error, y lo mismo ocurre con un Currency conversion rate de 0 y con un Min weight mayor que Max weight. Si la unidad de peso de tu tienda no se reconoce, un aviso te pide que definas una unidad estándar en International > Localization.

General

Los ajustes de esta página se aplican a todas las zonas. Las zonas, los grupos de clientes y los límites de tamaño del transportista se definen en Shipping > Carriers (o usa Ignore shipping zones más abajo).

Enable J&T Express: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Method title: el nombre del transportista que se muestra en el carrito y en la finalización de compra. Predeterminado: J&T Express. Obligatorio.

Tax: la regla fiscal del transportista, o No tax. Una regla fiscal añade el impuesto de envío de tu tienda sobre el coste. Elige No tax si el precio de J&T ya incluye todo lo que quieres cobrar.

API de J&T Express Malasia (cotizaciones en tiempo real) (opcional, para direcciones de entrega en Malasia; se necesitan las cuatro credenciales)

VIP customer code: tu código de cliente VIP de J&T Express. Al borrarlo también se borra la clave de API VIP guardada.

VIP API key: la clave de API (contraseña) que J&T Express te dio junto con el código VIP. Nunca se registra. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.

API account: el nombre de tu cuenta de API de J&T Express. Al borrarlo también se borra la clave privada guardada.

API private key: la clave privada de la cuenta de API. Solo se usa para firmar las solicitudes (SHA-256). Nunca se envía a J&T ni se registra. Como la clave de API VIP, no se muestra de nuevo después de guardar.

Sender postcode: el código postal malasio desde el que se envían los paquetes. Déjalo vacío para usar el código postal de la tienda de Shop Parameters > Contact > Stores, cuando la tienda está en Malasia. Los espacios se eliminan al guardar.

Currency conversion rate: las cotizaciones de J&T Express Malasia están en MYR. Si la moneda predeterminada de tu tienda no es MYR, introduce cuántas unidades de tu moneda vale un MYR (1 MYR = X). Sin este valor no se usan cotizaciones en tiempo real y se usan en su lugar la tabla de precios o el coste de reserva. Si tu moneda predeterminada es MYR, el campo lo indica y no hace falta: las cotizaciones se usan tal cual. Se aceptan tanto el punto como la coma como separador decimal. El tipo de cambio debe ser mayor que 0.

Price table and fallback (se usan para países distintos de Malasia, cuando las cotizaciones en tiempo real no están configuradas o cuando J&T no da ninguna cotización; precios en la moneda predeterminada de tu tienda, sin impuestos)

Country prices: una tabla con una fila por país. Haz clic en Add country para añadir una fila y en el icono de la papelera para eliminar una. Elige * Any other country para todos los países sin fila propia. Cada fila tiene un Base price y cinco tramos de peso: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg y XL por encima de 5 kg. Un precio de tramo mayor que 0 sustituye al precio base para los carritos de ese tramo. Un tramo de 0 usa el precio base. Un precio base de 0 significa envío gratuito, y un precio base vacío se guarda como 0. Si un país aparece en dos filas, se conserva la última. Los países sin fila (cuando no hay fila *) no reciben precio de tabla.

Fallback cost: el precio que se usa cuando ni J&T ni la tabla dan un precio. Déjalo vacío para ocultar el transportista en ese caso. 0 significa envío gratuito.

Table / fallback price is: Per order cobra el precio una sola vez. Per item (multiplied by the number of items) lo multiplica por el número de artículos del carrito. Las cotizaciones en tiempo real de J&T son siempre para el pedido completo.

Condiciones

Free shipping from: el subtotal del carrito (productos que necesitan envío, después de descuentos y antes de impuestos) a partir del cual el envío es gratuito. Déjalo vacío si no quieres envío gratuito.

Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito alcance este importe. Déjalo vacío para mostrarlo siempre.

Min weight: oculta el transportista cuando el carrito pese menos, en kg. Los pesos de los productos se convierten desde la unidad de peso de tu tienda. 0 significa sin límite. No puede ser mayor que Max weight.

Max weight: oculta el transportista cuando el carrito pese más, en kg. Predeterminado: 50. 0 significa sin límite.

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece el transportista para los países indicados abajo, aunque no esté vinculado a su zona. Al activarlo, el transportista se vincula a todas las zonas activas, y también a las zonas que crees más adelante. Si está desactivado, el transportista se ofrece solo en sus propias zonas de Shipping > Carriers. Al desactivarlo, el transportista recupera sus zonas anteriores.

Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías. Este campo solo se usa cuando Ignore shipping zones está activado.

Avanzado

Debug log: escribe los cálculos de precios en logs/vfd_jtex_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API de J&T siempre se registran, incluso con esta opción desactivada. No se escriben claves, contraseñas ni códigos postales de clientes. Desactiva el registro cuando termines.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes del módulo, el transportista, las cotizaciones en caché y el registro. Si está desactivado, todo se conserva para una reinstalación.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de J&T Express. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el subtotal. El módulo comprueba primero las condiciones: país de entrega (con Ignore shipping zones), peso del carrito y subtotal mínimo. Si el subtotal del carrito alcanza Free shipping from, el precio es 0 y no se envía ninguna solicitud a J&T.

En otro caso, el coste se toma de la primera fuente que dé un precio:

1. Cotización en tiempo real de J&T: solo cuando las cuatro credenciales de la API y un código postal del remitente están configurados, el país de entrega es Malasia, el cliente ha introducido un código postal de 5 dígitos y, en tiendas cuya moneda predeterminada no es MYR, hay un tipo de cambio configurado. El módulo envía a J&T los códigos postales del remitente y del destinatario y el peso del carrito (mínimo 0,1 kg) para el servicio estándar EZ, un paquete, y convierte el precio en MYR que devuelve a la moneda predeterminada de tu tienda.

2. Tabla de precios por país: la fila del país de entrega, o la fila *, con el precio del tramo de peso del carrito.

3. Coste de reserva.

Si ninguna de ellas da un precio, el transportista se oculta para ese carrito. Per item se aplica solo a los precios de tabla y de reserva. El precio se calcula en la moneda predeterminada de tu tienda y luego se muestra en la moneda del carrito del cliente.

Cada respuesta de J&T se guarda en caché durante 1 hora, para que el mismo carrito no provoque una nueva solicitud. Una solicitud fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a J&T en cada actualización. El tiempo de espera de la solicitud es de 10 segundos. Si J&T devuelve un error, un precio de cero o ninguna respuesta, el cliente no ve ningún error. Se usa el precio de tabla o de reserva, y el motivo se escribe en el registro.

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 los costes de envío. No crea guías de envío, cartas de porte ni etiquetas, no reserva recogidas, no cancela ni hace seguimiento de envíos, y no permite que los clientes elijan un punto de recogida. Crea y haz seguimiento de los envíos en tu cuenta de J&T como de costumbre. El módulo se diseñó según el formato de solicitud del plugin oficial de J&T Express Malasia. Confirma los precios con tu cuenta de J&T antes de poner la tienda en producción.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox J&T Express es el primer bloque de Modules > Module Manager > VibeFox J&T Express > Configure, por encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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 aparecen la línea Product: presta-shipping-jt-express 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 el inglés y el 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 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, el transportista J&T Express no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La parte pública 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 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 a la semana. No se necesita ninguna tarea cron. Al desinstalar o restablecer el módulo se eliminan siempre la clave de licencia y el estado de la licencia.

Solución de problemas

J&T Express no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable J&T Express esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o que Ignore shipping zones esté activado y el país esté permitido). Revisa los límites de peso y Minimum subtotal. Comprueba que Country prices tenga una fila para el país o una fila *, o que Fallback cost esté definido. Los productos también pueden limitarse a ciertos transportistas en la página del producto. Activa Debug log y mira el campo Log en la página del módulo.

El precio viene de la tabla, no de J&T: las cotizaciones en tiempo real necesitan las cuatro credenciales de la API, un código postal del remitente, una dirección de entrega en Malasia con un código postal de 5 dígitos y, para tiendas que no usan MYR, el Currency conversion rate. Revisa los avisos en la parte superior de la página del módulo. Si J&T rechaza la solicitud o no responde, el error se registra y se usa el precio de tabla o de reserva. La solicitud fallida se reintenta después de 10 minutos.

No hay cotizaciones en tiempo real para Filipinas o Indonesia: J&T no ofrece una API pública de cotizaciones para estos países. Usa allí la tabla de precios y el coste de reserva.

Un país obtiene envío gratuito por error: su fila tiene un precio base de 0 (un precio base vacío se guarda como 0). Introduce un precio base o elimina la fila. Comprueba también Free shipping from.

Las tarifas parecen desactualizadas después de un cambio: haz clic en Save en la página del módulo. Esto borra las cotizaciones de J&T en caché.

La página indica que no se encontró el transportista J&T Express: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.

Hooks para desarrolladores: el hook actionVfdJtexQuoteRequest cambia el cuerpo de la solicitud de cotización (por ejemplo, el tipo de servicio), y actionVfdJtexApiUrl cambia el endpoint de cotización.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox J&T Express y elige Uninstall. La clave de licencia y el estado de la licencia se eliminan siempre. Las cotizaciones en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y todos los ajustes se conservan. Al volver a instalar el módulo, el transportista guardado recupera su estado anterior.

J&T Express es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por J&T Express.