VibeFox Jadlog 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.
Contrato con Jadlog (para precios en tiempo real y puntos Pickup): los precios en tiempo real y la lista de puntos Pickup proceden de 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 contrato con Jadlog.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
La descarga es un archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_jadlog-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_jadlog.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_jadlog-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, 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 Jadlog 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. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia, en la parte superior de la página Edit, y haz clic en Activate (consulta Clave de licencia).
5. 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 BRL. Añade precios fijos o un coste de reserva si los quieres (consulta Configuración).
6. Activa Enable Jadlog home delivery, Enable Jadlog Pickup o ambos, y haz clic en Save.
OpenCart 4
1. En el administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_jadlog.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 Jadlog, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).
4. Introduce la clave de licencia y los ajustes como en los pasos 4 a 6 para OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.
Tras la instalación, ambas opciones están desactivadas hasta que las actives y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Jadlog que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Jadlog > Edit. Se aplican a ambas opciones de Jadlog. Las secciones aparecen a la izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra los precios de Jadlog y las listas de puntos Pickup en caché. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
En la parte superior de la página, la extensión muestra avisos de una configuración incompleta: sin token de API (solo se usan precios fijos y no se pueden enumerar 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 BRL para una tienda que no vende en BRL, y sin clase de peso "kg" ni clase de longitud "cm" en la tienda (en ese caso, los pesos y las dimensiones se convierten según el nombre de la unidad de su clase; revisa System > Localisation > Weight Classes y Length Classes).
Al guardar, un título no válido de cualquiera de las dos opciones (vacío, de más de 64 caracteres o con < > ; = # { }), un Sort order que no sea un número entero, o una clase de impuesto o zona geográfica que no exista, detienen el guardado con un error. Otros valores incorrectos se guardan con una observación sobre los ajustes: un número no válido o menor que 0 no se guarda, un peso mínimo mayor que el peso máximo mantiene ambos pesos guardados, un tipo de cambio BRL que no sea un número positivo se borra, un CEP sin 8 dígitos o un CNPJ sin 14 dígitos (o 11 para un CPF) se guarda tal como se escribió con un aviso, y en la tabla de precios una fila con un país desconocido se elimina y un precio no válido se deja vacío.
General
Jadlog tiene dos opciones de entrega: Jadlog home delivery (esta sección) y Jadlog Pickup (su propia sección). Los ajustes de esta página se aplican a ambas.
Enable Jadlog home delivery: ofrece la entrega de Jadlog a la dirección del cliente con el servicio elegido más abajo. Predeterminado: off.
Method title: el nombre de la opción de entrega a domicilio que se muestra al cliente en la finalización de compra. Predeterminado: Jadlog. Obligatorio, hasta 64 caracteres.
Sort order: la posición de Jadlog entre los métodos de envío de la finalización de compra. Un número entero.
Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Los precios de Jadlog son precios finales del transportista. Elige No tax si OpenCart no debe añadirles impuestos. Se aplica a ambas opciones.
Precios en tiempo real de Jadlog
Los precios en tiempo real solo se solicitan 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 para cambiarlo. Cuando no hay ningún token guardado, la página muestra No token saved.
Remove the saved API token: márcalo y haz clic en Save para borrar el token guardado.
CNPJ: el CNPJ (14 dígitos) o CPF (11 dígitos) del remitente registrado en el contrato de Jadlog, por ejemplo 00.000.000/0000-00.
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 lo ha dado.
Origin CEP: el código postal desde el que se envían los paquetes, 8 dígitos (00000-000). Obligatorio para precios en tiempo real: OpenCart no tiene código postal de tienda, así que sin este campo solo se usan precios fijos.
Jadlog service: el servicio (modalidade) de tu contrato para entrega a domicilio: .Package (3, predeterminado), .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 la segunda opción.
Insurance type: Normal (N) (predeterminado) o Own insurance policy (A - apolice), según lo acordado 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. En caso contrario, 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.
Delivery time: muestra el plazo de entrega que devuelve Jadlog en la finalización de compra, junto al título de la entrega a domicilio (por ejemplo "Jadlog (3 business days)") y junto a cada punto Pickup. Activado de forma predeterminada. El plazo de entrega siempre se guarda con el pedido.
Jadlog Pickup
Una segunda opción de entrega con el servicio Pickup (40) de Jadlog. Necesita el token de la API. Sin puntos, la opción queda oculta.
Enable Jadlog Pickup: ofrece la entrega en un punto Jadlog Pickup elegido en la finalización de compra. Predeterminado: off.
Jadlog Pickup title: el nombre de esta opción en la finalización de compra. Predeterminado: Jadlog Pickup. Obligatorio, hasta 64 caracteres.
Points to show: cuántos puntos Pickup ofrecer, de 1 a 10. Predeterminado: 5.
Precios fijos (se usan cuando no hay token de API, para países que Jadlog no atiende y siempre que Jadlog no devuelva 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 botón × 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. Se usa Price cuando la columna de tamaño está vacía. Un precio de 0 significa envío gratuito para ese país. Usa * Default (other countries) para todos los demás países.
Fallback cost: se usa cuando ni Jadlog ni la tabla dan un precio. Déjalo vacío para ocultar el método en ese caso.
Fixed price applies: Per order (predeterminado) 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 reserva. Los precios de Jadlog ya cubren todo el carrito.
Condiciones
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (predeterminado).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Predeterminado: 150. 0 significa sin límite.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal (después del cupón, antes de impuestos) a partir del cual la entrega es gratuita. Déjalo vacío para no tener envío gratuito.
Disponibilidad
Geo zone: ofrece Jadlog solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. La zona geográfica no se comprueba cuando Ignore shipping zones está activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore shipping zones: cuando está activado, no se comprueba la Geo zone y Jadlog se ofrece para los países de abajo. Cuando está desactivado (predeterminado), solo se aplica la Geo zone.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra cada solicitud y respuesta de Jadlog en storage/logs/vfd_jdlg_debug.log.php (en OpenCart 4, system/storage/logs/vfd_jdlg_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API y los pedidos de Jadlog Pickup sin punto siempre se registran, incluso cuando esta opción está 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: cuando está activado, al desinstalar la extensión se eliminan todos los ajustes de Jadlog, el registro y las elecciones de puntos de finalizaciones de compra que nunca se convirtieron en pedidos. Cuando está desactivado (predeterminado), los ajustes se conservan para una reinstalación. Los precios en caché siempre se eliminan. Los datos de Jadlog de los pedidos nunca se borran.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El token de la API 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 la API guardado se conserva.
Funcionamiento en la finalización de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de cada opción de Jadlog: la entrega a domicilio y Jadlog Pickup aparecen como dos opciones bajo un mismo método Jadlog. Con Ignore shipping zones activado, Jadlog se ofrece solo cuando el país está permitido (no se comprueba la zona geográfica). En caso contrario, si hay una Geo zone definida y la dirección está fuera de ella, Jadlog no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no añaden peso y no se incluyen en el importe del pedido. El importe del pedido es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. La extensión comprueba el peso del carrito y el importe mínimo del pedido. Si el subtotal alcanza Free shipping from, la entrega es gratuita y no se envía ninguna solicitud de precio a Jadlog.
Para una dirección de entrega en Brasil con un CEP completo de 8 dígitos, la extensión 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. Los pesos de los productos se convierten de su clase de peso de OpenCart a kg, y las dimensiones de su clase de longitud a cm. Los carritos sin peso se cotizan como 0.1 kg. El precio devuelto se convierte a tu moneda predeterminada, se redondea a sus decimales y se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada. Si no hay precio en tiempo real (sin token, dirección fuera de Brasil, CEP incompleto, sin tipo de cambio BRL, error de Jadlog), la extensión usa la tabla Price per country y después el Fallback cost. Si ninguno da un precio, la opción se oculta para ese carrito.
Cada precio se guarda en caché durante 1 hora, así que el mismo carrito no provoca una nueva solicitud. Una solicitud 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.
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 Jadlog en la ventana Shipping method options. Los precios son los mismos que en OpenCart 3.
La extensión solo calcula precios y enumera puntos Pickup. No crea envíos de Jadlog, no imprime etiquetas, no solicita recogidas, no cancela envíos ni rastrea paquetes. No muestra un mapa de puntos Pickup y no solicita cotizaciones internacionales a Jadlog. Usa precios fijos para otros países.
Puntos Pickup
La opción Jadlog Pickup se ofrece solo para direcciones en Brasil, y solo cuando Enable Jadlog Pickup está activado y el token de la API está guardado. Cuando el cliente ha introducido un CEP completo de 8 dígitos, la extensión pide a Jadlog los puntos Pickup activos más cercanos y enumera hasta Points to show puntos bajo la opción, 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 en segundo plano cuando el cliente selecciona Jadlog Pickup, de modo que el paso de método de entrega no espera a Jadlog.
El precio de cada punto se solicita a Jadlog. Si Jadlog no da ningún 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 de la opción es el precio del punto elegido. Antes de elegir un punto, es el precio del punto más cercano que tenga precio. Cuando el cliente elige un punto, se actualiza el precio que se muestra junto a Jadlog Pickup.
Se requiere un punto. Cuando el cliente hace clic en Continue en el paso de método de entrega sin un punto, ve Please select a Jadlog Pickup point. La extensión comprueba en el servidor 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 bajo la opción.
Sin token de API, cuando Jadlog no está disponible o cuando no hay puntos activos cercanos, la opción Jadlog Pickup se oculta. Un pedido sin punto no se podría enviar.
En OpenCart 4, la lista de puntos Pickup aparece en la ventana Shipping method options, bajo la opción Jadlog Pickup. Se carga en segundo plano, primero desde la caché y luego con los precios de los otros puntos de Jadlog. Cuando el cliente elige un punto, se actualiza el precio que aparece junto a Jadlog Pickup en la ventana. El botón Continue de la ventana no avanza sin un punto válido, con los mismos mensajes.
Pedidos
Cuando se realiza un pedido con una opción de Jadlog, la extensión guarda el servicio de Jadlog y, si Jadlog lo devolvió, el plazo de entrega en días hábiles. En un pedido de Jadlog Pickup, también guarda el nombre, la dirección y el ID del punto Pickup. En OpenCart 4, la tienda mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar, y los datos de Jadlog del pedido se actualizan con él. Si el cliente cambia ese pedido a otro método de envío, sus datos de Jadlog se eliminan.
El punto se añade al método de envío del pedido después del título de la opción, por ejemplo Jadlog Pickup: seguido del nombre y la dirección del punto. Este texto aparece en las páginas de pedidos del administrador y en la cuenta del cliente, en los correos de pedido y en la factura.
La página de pedidos del administrador (Sales > Orders) muestra un panel Jadlog con Jadlog service, Delivery time y, para Jadlog Pickup, Pickup point, Pickup point address y Pickup point ID. En OpenCart 4, el panel se muestra encima de History.
Reserva el envío tú mismo en el sistema de Jadlog. El pedido muestra el servicio y el ID del punto Pickup que necesitas para ello.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Jadlog es el primer bloque de Extensions > Extensions > Shipping > VibeFox Jadlog > Edit, por 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: opencart-shipping-jadlog 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 (incluidos 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 con 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, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un solo 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. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, las opciones de envío de Jadlog no se muestran a los clientes en la finalización de compra y no se calcula ningún precio. Un usuario administrador que haya iniciado sesión en el administrador en el mismo navegador las sigue viendo en la tienda, marcadas 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 las opciones de Jadlog quedan ocultas para todos. Una vez que hayas abierto 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 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 ningún cron job. Al desinstalar la extensión, la clave de licencia y el estado de la licencia siempre se eliminan.
Solución de problemas
Jadlog no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Jadlog home delivery (o Enable Jadlog Pickup) esté activado. Revisa Geo zone, o activa Ignore shipping zones y revisa Countries. Revisa los avisos de la parte superior de la página de la extensión, los límites de peso, Minimum order amount y que los productos tengan Requires Shipping en Yes. Si el cliente aún no ha introducido un CEP completo de 8 dígitos, solo se pueden usar precios fijos, así que añade una fila de Price per country o un Fallback cost.
Solo se muestran precios fijos: activa Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Muestra el motivo: sin CNPJ ni cuenta corriente, sin CEP de origen, CEP de destino incompleto, sin tipo de cambio 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 borra la pausa, así que puedes volver a intentarlo de inmediato.
Los puntos Pickup no aparecen: la opción 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, la opción 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: rellena 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 class en No tax.
Los precios parecen desactualizados tras un cambio: haz clic en Save en la página de la extensión. Esto borra los precios de Jadlog y las listas de puntos Pickup en caché.
La página muestra «Warning: You do not have permission to modify VibeFox Jadlog!»: tu grupo de usuarios administradores puede tener solo permiso para ver los ajustes. Concede al grupo el permiso de modificación para extension/shipping/vfd_jadlog (OpenCart 3) o extension/vfd_jadlog/shipping/vfd_jadlog (OpenCart 4) en System > Users > User Groups.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Jadlog. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece el estado de la extensión, Sort order, Tax class y Geo zone. Los precios en caché y las listas de puntos Pickup siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes de Jadlog y el registro. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. El servicio de Jadlog, el plazo de entrega y el punto Pickup guardados con los pedidos siempre se conservan, y los pedidos existentes mantienen su método y coste de envío.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Jadlog en la lista de extensiones instaladas, y luego en Delete (el botón rojo de la papelera) para eliminar el paquete subido.
Jadlog es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por Jadlog.