VibeFox J&T Express for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

WooCommerce: 5.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

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 de configuración tiene un enlace): J&T te proporciona 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 con la API. Pídelas a tu gestor de cuenta de J&T. J&T Filipinas, Indonesia y otros países no tienen API pública de cotizaciones, así que usa la tabla de precios para ellos. 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 solo dominio.

Instalación

1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_jt_express a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Shipping > VibeFox J&T Express, o haz clic en Settings debajo del nombre del plugin en la página Plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

5. Rellena la tabla de precios y/o el coste de reserva. Para las cotizaciones 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 de tu tienda no es MYR, el tipo de cambio (consulta Configuración).

6. Añade VibeFox J&T Express a una zona de envío en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones y elige los países.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox J&T Express. Se aplican a todas las zonas de envío. Al añadir el método a una zona, la ventana de la zona solo tiene un campo:

Title (zone): el nombre que el cliente ve en esta zona. Déjalo vacío para usar el Method title global.

Cada vez que guardes la configuración, se borran las cotizaciones de J&T guardadas 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 qué ajustes faltan o que falta el tipo de cambio.

General

Enable/Disable: activa o desactiva el método en todas las zonas a la vez. Por defecto: on.

Method title: el nombre del método de envío que se muestra en el carrito y en la finalización de compra. Una zona puede cambiarlo. Por defecto: J&T Express.

Tax status: Taxable añade el impuesto de envío de tu tienda al coste; None no lo añade. Elige None 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.

VIP API key: la clave de API (contraseña) que J&T Express te dio junto con el código VIP. Nunca se escribe en el registro.

API account: el nombre de tu cuenta de API de J&T Express.

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 escribe en el registro.

Sender postcode: el código postal de Malasia desde el que se envían los paquetes. Déjalo vacío para usar el código postal de la tienda de WooCommerce > Settings > General, 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 de tu tienda no es MYR, indica cuántas unidades de tu moneda vale un MYR (1 MYR = X). Sin este dato no se usan las cotizaciones en tiempo real, y se usan en su lugar la tabla de precios o el coste de reserva. Si la moneda de tu tienda es MYR, déjalo vacío: las cotizaciones se usan tal cual. Se aceptan tanto el punto como la coma como separador decimal.

Tabla de precios y reserva (se usa para países distintos de Malasia, cuando no hay cotizaciones en tiempo real configuradas o cuando J&T no da ninguna cotización; precios en la moneda de tu tienda)

Country prices: una tabla con una fila por país. Haz clic en Add country para añadir una fila y en la cruz para eliminarla. 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 tienen precio de tabla.

Fallback cost: el precio que se usa cuando ni J&T ni la tabla dan precio. Déjalo vacío para ocultar el método en ese caso.

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 siempre son para el pedido completo.

Condiciones

Free shipping from: el subtotal del carrito (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 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 desde la unidad de peso de tu tienda. 0 significa sin límite.

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

Excluded shipping classes: oculta el método cuando el carrito contiene un producto de cualquiera de estas clases de envío de WooCommerce.

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece el método para los países indicados abajo, aunque no esté añadido a ninguna zona de envío. Cuando está desactivado, el método aparece solo en las zonas a las que se ha añadido.

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 WooCommerce > Status > Logs, origen vfd-jt-express. 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.

Remove data on uninstall: si está activado, al eliminar el plugin se borran sus ajustes, los métodos de zona y las cotizaciones en caché. Desactivar el plugin nunca borra nada.

Cómo funciona en la finalización de compra

Cuando el cliente introduce una dirección de entrega, WooCommerce pide al plugin una tarifa. Primero el plugin comprueba las condiciones: país de entrega, peso del carrito, subtotal mínimo y clases de envío excluidas. Si el subtotal del carrito alcanza Free shipping from, el método se muestra con un coste de 0, pero solo si el país tiene precio: una fila en Country prices, un Fallback cost o una cotización en tiempo real de J&T. J&T solo se consulta cuando la tabla y el coste de reserva no dan precio.

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

1. Cotización en tiempo real de J&T: solo cuando están configuradas las cuatro credenciales de la API y un código postal del remitente, el país de entrega es Malasia, el cliente ha introducido un código postal de 5 dígitos y, en tiendas que no usan MYR, hay un tipo de cambio configurado. El plugin 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 devuelto en MYR a la moneda de tu tienda.

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

3. Fallback cost.

Si ninguna de estas fuentes da precio, el método queda oculto. Per item se aplica solo a los precios de tabla y de reserva.

Cada respuesta de J&T se guarda en caché durante 1 hora, para que el mismo carrito no genere 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 cero o no responde, el cliente no ve ningún error. Se usa el precio de la tabla o el coste de reserva, y el motivo se escribe en el registro.

El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) de WooCommerce.

El plugin 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 el cliente elija un punto de recogida. Crea y sigue los envíos en tu cuenta de J&T como de costumbre. El plugin se desarrolló según el formato de solicitudes del plugin oficial de J&T Express Malasia. Confirma los precios con tu cuenta de J&T antes de poner la tienda en marcha.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox J&T Express. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, J&T Express no se muestra a los clientes en la finalización de compra. Los gestores de la tienda con sesión iniciada sí lo ven, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.

Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

J&T Express no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el método está añadido a la zona del país del cliente (o que Ignore shipping zones está activado y el país está permitido). Revisa los límites de peso, Minimum subtotal y Excluded shipping classes. Comprueba que Country prices tiene una fila para el país o una fila *, o que Fallback cost está configurado. Activa el Debug log y revisa WooCommerce > Status > Logs.

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 código postal de 5 dígitos y, en tiendas que no usan MYR, el Currency conversion rate. Revisa los avisos en la parte superior de la página de configuració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 vuelve a intentar 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 para ellos la tabla de precios y el coste de reserva.

Un país recibe 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.

Las tarifas parecen desactualizadas tras un cambio: guarda la página de configuración. Así se borran las cotizaciones de J&T guardadas en caché.

Hooks para desarrolladores: el filtro vfd_jtex_quote_request cambia el cuerpo de la solicitud de cotización (por ejemplo, el tipo de servicio), vfd_jtex_api_url cambia el endpoint de cotizaciones, y el filtro estándar woocommerce_shipping_vfd_jt_express_is_available controla la disponibilidad.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.

Desinstalación

Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes, los métodos de zona y las cotizaciones en caché se eliminan solo si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus líneas de envío.

J&T Express es una marca comercial de su respectivo titular. Este plugin no está afiliado a J&T Express ni cuenta con su respaldo.