VibeFox J&T Express for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 o posterior (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Acceso a la API de J&T Express Malasia (solo para tarifas en tiempo real): las tarifas 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 de la extensión tiene un enlace): J&T te facilita 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 tarifas, 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

El archivo descargable es un único ZIP con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_jt_express-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_jt_express.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_jt_express-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 J&T Express 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. Rellena la tabla de precios y/o el coste de reserva. Para las tarifas en tiempo real de 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 (véase Configuración). Activa Enable J&T Express y haz clic en Save.

OpenCart 4

1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_jt_express.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 J&T Express, 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 los mismos en ambas versiones.

Tras la instalación, el método está desactivado hasta que actives Enable J&T Express y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de J&T Express que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox J&T Express > Edit. Las secciones aparecen a la izquierda. Un botón Save en la parte inferior guarda toda la página sin recargarla. Cada guardado también borra las tarifas de J&T en caché. Si un valor es incorrecto, no se guarda nada y la página muestra el motivo: un título de método no válido, un importe que no es un número igual o mayor que 0, una Currency conversion rate de 0, un Min weight (kg) mayor que Max weight (kg) o un orden de clasificación que no es un número entero. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

Las advertencias sobre los ajustes (que se muestran de nuevo tras cada guardado) indican cuándo las tarifas en tiempo real están configuradas solo en parte: enumeran los ajustes de API que faltan o indican que la moneda de tu tienda no es MYR y falta el tipo de cambio. Otra advertencia aparece si tu tienda no tiene una clase de peso con la unidad kg en System > Localisation > Weight Classes. Los pesos de los productos se convierten entonces según el nombre de su unidad (kg, g, lb, oz), y las demás unidades se leen como kg.

General

El método se ofrece para la zona geográfica seleccionada o para los países de Ignore shipping zones. Los ajustes de esta página se aplican a todas las zonas.

Enable J&T Express: muestra u oculta el método en la compra (es el estado de esta extensión). Por defecto: desactivado.

Method title: el nombre del método de envío que el cliente ve en el carrito y en la compra. Por defecto: J&T Express. Obligatorio, hasta 64 caracteres, sin los caracteres < > ; = # { }.

Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Una clase de impuesto añade el impuesto de envío sobre el coste. Elige No tax si el precio de J&T ya incluye todo lo que quieres cobrar.

Sort order: la posición del método entre los métodos de envío de la compra. Un número entero.

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

La tarifa se solicita a J&T Express Malasia para cada código postal malasio y se guarda en caché durante una hora. Sin las credenciales, y para otros países, se usan la tabla de precios y el coste de reserva.

VIP customer code: tu código VIP de J&T Express. Borrarlo también 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. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. Para eliminarla, borra VIP customer code y guarda.

API account: el nombre de tu cuenta de API de J&T Express. Borrarlo también 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. Igual que la clave de API VIP, no se vuelve a mostrar tras guardar. Para eliminarla, borra API account y guarda.

Sender postcode: el código postal malasio desde el que se envían los paquetes, por ejemplo 50000. Obligatorio para las tarifas en tiempo real: la dirección de la tienda en OpenCart es texto libre, así que el código postal nunca se toma de ella.

Currency conversion rate: las tarifas de J&T Express Malasia están en MYR. Si la moneda predeterminada de tu tienda no es MYR, indica cuántas unidades de tu moneda vale un MYR (1 MYR = X), por ejemplo 0.20. Sin este valor no se usan las tarifas en tiempo real, y se usan la tabla de precios o el coste de reserva. Si tu moneda predeterminada es MYR, el campo lo indica y no hace falta: las tarifas se usan tal cual. El tipo debe ser mayor que 0.

Tabla de precios y coste de reserva (se usa para países distintos de Malasia, cuando las tarifas en tiempo real no están configuradas o cuando J&T no da ninguna tarifa; 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 botón de eliminar para borrar 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. Los países sin fila (cuando no hay fila *) no obtienen precio de la 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 método en ese caso. 0 significa envío gratuito.

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

Condiciones

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

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

Min weight (kg): oculta el método cuando el carrito pesa menos. Los pesos de los productos se convierten con su clase de peso. 0 significa sin límite (por defecto). No puede ser mayor que Max weight (kg).

Max weight (kg): oculta el método cuando el carrito pesa más. Por defecto: 50. 0 significa sin límite.

Geo zone: ofrece el método solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se usa cuando Ignore shipping zones está activado.

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona geográfica. Por defecto: desactivado.

Countries: los países de destino para ese modo, elegidos entre los países habilitados en tu tienda. Déjalo vacío para permitir todos los países. Este campo solo se usa cuando Ignore shipping zones está activado.

Avanzado

Debug log: escribe los cálculos de precios en storage/logs/vfd_jtex_debug.log.php (en OpenCart 4, system/storage/logs/vfd_jtex_debug.log.php). El archivo no se puede leer 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, el código de cliente ni los códigos postales de los clientes. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_jtex_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: si está activado, al desinstalar la extensión se borran los ajustes de J&T Express y el registro. Si está desactivado (por defecto), se conservan para una reinstalación. Las tarifas en caché siempre se eliminan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de API VIP y la clave privada no se exportan.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. Las claves guardadas se conservan.

Funcionamiento en la compra

Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de J&T Express. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, el método no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni se incluyen en el subtotal. La extensión comprueba entonces las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. El subtotal es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. Los certificados regalo, los puntos de recompensa y el saldo de la tienda no se tienen en cuenta. Si el subtotal alcanza Free shipping from, el precio es 0 y no se envía ninguna solicitud a J&T.

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

1. Tarifa en tiempo real de J&T: solo cuando las cuatro credenciales de API y un código postal del remitente están definidos, el país de entrega es Malasia, el cliente ha introducido un código postal de 5 dígitos y, en las tiendas cuya moneda predeterminada no es MYR, hay un tipo de cambio. La extensión envía a J&T los códigos postales del remitente y de entrega y el peso del carrito (al menos 0,1 kg) para el servicio estándar EZ, un paquete, y convierte el precio en MYR devuelto a tu moneda predeterminada.

2. 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 método se oculta para ese carrito. Per item se aplica solo a los precios de tabla y de reserva. El precio se calcula en tu moneda predeterminada, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.

Cada respuesta de J&T se guarda en caché durante 1 hora, de modo que el mismo carrito no genera una nueva solicitud. Una solicitud fallida se guarda en caché durante 10 minutos, para que la 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 cero o ninguna respuesta, el cliente no ve ningún error. Se usa el precio de la tabla o el de reserva, y el motivo se escribe en el registro.

En OpenCart 4, el cliente hace clic en Choose en el bloque de método de envío de la página de compra y elige J&T Express en la ventana Shipping method options. El método funciona igual que en OpenCart 3.

La extensión solo calcula los costes de envío. No crea cartas de porte, guías ni etiquetas, no reserva recogidas, no cancela ni rastrea envíos, y no permite que el cliente elija un punto de recogida. No añade nada a los pedidos: el pedido muestra el nombre del método y el coste de envío como cualquier otro método de OpenCart. Crea y rastrea los envíos en tu cuenta de J&T como de costumbre. La extensión se creó según el formato de solicitud de la integración oficial de J&T Express Malasia. Confirma los precios con tu cuenta de J&T antes de pasar a producción.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox J&T Express es el primero de la página Extensions > Extensions > Shipping > VibeFox J&T Express > 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 están la línea Product: opencart-shipping-jt-express y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (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. Tras 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 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. 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 método de envío J&T Express no se muestra a los clientes en la 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 la página Edit una vez, 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 al abrir 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. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

J&T Express no aparece en la compra: comprueba que la licencia está activa y que Enable J&T Express está activado. Revisa Geo zone (o que Ignore shipping zones esté activado y el país esté en Countries), 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. Comprueba que los productos tengan Requires Shipping en Yes. Activa Debug log y revisa el campo Log en la página de la extensión.

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

No hay tarifas en tiempo real para Filipinas ni Indonesia: J&T no ofrece una API pública de tarifas 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. Revisa también Free shipping from.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas de J&T en caché.

La página dice "Warning: You do not have permission to modify VibeFox J&T Express!": tu grupo de usuarios de administración quizá solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_jt_express (OpenCart 3) o extension/vfd_jt_express/shipping/vfd_jt_express (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: otras extensiones pueden cambiar el cuerpo de la solicitud de tarifa (por ejemplo, el tipo de servicio) con el evento de OpenCart vfd_jt_express/quote_request, y la dirección del endpoint de tarifas con vfd_jt_express/api_url.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox J&T Express. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable J&T Express, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de J&T Express y el registro de depuración también se borran. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al reinstalar la extensión. Los pedidos existentes conservan 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 después de desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox J&T Express en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

J&T Express es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por J&T Express.