VibeFox DHL Africa 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 con la extensión cURL. DHL XML Services también necesita la extensión SimpleXML de PHP.
Cuenta de DHL Express (solo para tarifas en vivo): las tarifas en vivo usan la API MyDHL. Necesitas tu número de cuenta de DHL Express y las credenciales de la API MyDHL: una clave de API y un secreto de API. Solicítalos en el portal para desarrolladores de DHL (MyDHL API, "Get access") o a tu gestor de cuenta de DHL Express. Las cuentas que todavía tienen credenciales de DHL XML Services (Site ID y contraseña) pueden usarlas en su lugar. Si solo usas precios de reserva, no necesitas credenciales de DHL.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_dhl_africa-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_dhl_africa.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 panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_dhl_africa-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 DHL Africa 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 de la parte superior de la página Edit y haz clic en Activate (ver Clave de licencia).
5. Elige la API de DHL, introduce la clave de API, el secreto de API y tu número de cuenta de DHL. Mantén Test mode activado mientras uses credenciales de prueba. Introduce la dirección de Ship from. Si tu cuenta de DHL no se factura en la moneda predeterminada de tu tienda, configura DHL quote currency y Exchange rate. Opcionalmente, configura precios por país y un coste de reserva (ver Configuración). Activa Enable DHL Express Africa y haz clic en Save.
OpenCart 4
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_dhl_africa.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 DHL Africa, 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.
Después de instalar, el método está desactivado hasta que actives Enable DHL Express Africa y guardes. Si vuelves a instalar la extensión tras desinstalarla, se vuelven a usar los ajustes de DHL que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra las cotizaciones de DHL en caché. Los precios y los pesos admiten coma decimal o punto decimal. Solo los usuarios del panel con el permiso de modificación para esta extensión pueden guardar los ajustes.
Las advertencias en la parte superior de la página te indican cuándo las tarifas en vivo están desactivadas porque falta la clave de API, el secreto de API o el número de cuenta (o, con XML Services, el Site ID o la contraseña), cuando falta el país o la ciudad de origen, cuando se seleccionan XML Services (DHL los está retirando), cuando se establece una moneda de cotización sin tipo de cambio, y cuando la extensión no reconoce la unidad de peso o de longitud de la tienda (los pesos de los productos se leen entonces como kg y las dimensiones como cm; añade una clase de peso con la unidad kg en System > Localisation > Weight Classes o una clase de longitud con la unidad cm en System > Localisation > Length Classes).
Si un valor no es válido al guardar (un título de método vacío o de más de 64 caracteres, un número no válido o negativo, un tipo de cambio de 0, un peso mínimo superior al peso máximo, una moneda de cotización, un país de origen, una clase de impuesto o una zona geográfica desconocidos, o un orden de clasificación que no es un número entero), una advertencia encima de los ajustes indica el campo, por ejemplo Select a valid origin country. It was not saved. Se conserva el valor anterior de ese campo y los demás ajustes se guardan.
General
Enable DHL Express Africa: muestra u oculta DHL Express en la finalización de compra. Predeterminado: desactivado.
Method title: el nombre del método de envío que ve el cliente en la finalización de compra. Predeterminado: DHL Express. Obligatorio, como máximo 64 caracteres.
Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Con una clase de impuesto (y con los impuestos activados en la tienda), la tarifa de DHL se toma sin el impuesto que cotiza DHL, y OpenCart añade su propio impuesto. Con No tax, la tarifa de DHL se cobra tal como se cotiza, con el impuesto incluido.
Sort order: la posición de DHL Express entre los métodos de envío en la finalización de compra. Un número entero.
Cuenta de DHL Express (necesaria solo para las tarifas en vivo)
DHL API: la interfaz de DHL que se usa.
API key: tu nombre de usuario de la API MyDHL (clave de API).
API secret: tu contraseña de la API MyDHL (secreto de API). Después de guardar, los campos de clave de API y de secreto de API quedan vacíos y muestran Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Remove the saved API key and API secret: se muestra solo para la API MyDHL cuando hay una clave o un secreto guardados. Actívalo y haz clic en Save para borrar ambos.
XML Site ID: tu Site ID de DHL XML Services (solo para la API heredada). Al borrarlo también se elimina la contraseña XML guardada.
XML password: tu contraseña de DHL XML Services (solo para la API heredada). Como el secreto de API, no se vuelve a mostrar después de guardar.
DHL account number: tu número de cuenta de DHL Express (9 dígitos). La API MyDHL lo requiere. Con XML Services devuelve las tarifas de tu cuenta en lugar de las tarifas publicadas.
Test mode: usa el entorno de pruebas de DHL. Activado de forma predeterminada. Las credenciales de prueba solo funcionan en el entorno de pruebas, y las de producción solo en producción. Desactívalo cuando pongas la tienda en marcha.
Dirección de origen
La dirección desde la que DHL recoge los paquetes. La tarifa depende de ella. OpenCart guarda la dirección de la tienda como texto libre, así que el origen siempre se introduce aquí. La nota de esta sección muestra el país de tu tienda.
Origin country: el país desde el que envías.
Origin city: la ciudad desde la que envías, por ejemplo Johannesburgo. La API MyDHL la requiere.
Origin postcode: déjalo vacío en los países sin códigos postales (por ejemplo Kenia, Nigeria, Ghana).
Tarifas
Todos los precios están en la moneda predeterminada de tu tienda, sin impuestos. La tarifa en vivo es el producto DHL Express más barato para el paquete. Si DHL no está configurado, falla o no tiene servicio para la ruta, se usa el precio del país y después el coste de reserva. Si no hay ninguno de los dos, el método se oculta.
DHL quote currency: DHL cotiza en la moneda del país de tu cuenta de DHL (por ejemplo ZAR, NGN o KES). Si DHL no devuelve un importe en la moneda predeterminada de tu tienda, la tarifa en vivo se convierte desde esta moneda con el tipo de cambio de abajo. Si no, no se usa. Predeterminado: — None —.
Exchange rate: cuánto vale 1 unidad de la moneda de cotización de DHL en la moneda predeterminada de tu tienda, por ejemplo 1 ZAR = 0.05. Debe ser mayor que 0. Déjalo vacío si no quieres conversión. El tipo de cambio es un ajuste manual.
Fallback cost: un coste fijo cuando no hay tarifa en vivo ni precio del país. Déjalo vacío para ocultar el método en ese caso.
Country prices: un precio de reserva por país de destino, uno por línea: CC:Price, por ejemplo ZA:25.00. Se usa cuando no hay tarifa en vivo. Las líneas con otro formato se ignoran, y una advertencia al guardar las enumera.
Fallback price basis: Per order (predeterminado) cobra el precio una sola vez. Per item (multiplied by the cart quantity) lo multiplica por el número de artículos. Se aplica solo al precio del país y al coste de reserva. La tarifa en vivo de DHL siempre corresponde a todo el paquete.
Free shipping from: el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual este método es gratuito. No se consulta a DHL. Déjalo vacío si nunca es gratuito.
Condiciones
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (predeterminado). No puede ser mayor que Maximum weight (kg).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Predeterminado: 70 (también se usa cuando el campo está vacío). 0 significa sin límite.
Minimum subtotal: muestra el método solo si el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Disponibilidad
Geo zone: ofrece DHL Express solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se comprueba con Ignore shipping zones.
Ignore shipping zones: ofrece el método para los países de abajo (o para todos los países, si la lista está vacía), sea cual sea la zona geográfica seleccionada.
Countries: los países de destino para ese modo. Solo se usa con Ignore shipping zones.
Avanzado
Debug log: escribe los cálculos de tarifas en storage/logs/vfd_dhla_debug.log.php (en OpenCart 4, system/storage/logs/vfd_dhla_debug.log.php). El archivo no se puede leer desde la web. Los errores de DHL siempre se registran, incluso cuando está desactivado. Las credenciales, el número de cuenta y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_dhla_debug.old.log.php y se inicia un registro nuevo.
Log: muestra el tamaño y las entradas más recientes 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, las cotizaciones de DHL en caché y el registro. Si está desactivado (predeterminado), todo se conserva para una reinstalación. Los productos de DHL de los pedidos realizados siempre se conservan.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. La clave de API, el secreto de API y la contraseña XML no se exportan.
Import: pega el 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. Las credenciales guardadas se conservan.
Cómo funciona en la finalización de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de DHL Express. Si hay una Geo zone establecida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, no se ofrece DHL Express. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no añaden peso ni se incluyen en el subtotal. Después, la extensión comprueba las condiciones: los países de Ignore shipping zones, el peso del carrito y el 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. No se tienen en cuenta los certificados de regalo, los puntos de recompensa ni el crédito de la tienda. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna petición a DHL.
En caso contrario, la extensión envía a DHL el origen y el destino (país, ciudad, código postal), el peso del carrito convertido a kg a partir de las clases de peso de los productos (como mínimo 0,5 kg) y una caja construida con las dimensiones de los productos en cm: la longitud más larga, la anchura más ancha y las alturas apiladas. Los productos sin dimensiones no añaden nada. Si ningún producto tiene dimensiones, se usa una caja de 10 x 10 x 10 cm. Los envíos a otro país se declaran para la aduana, con el subtotal del carrito como valor declarado. Los envíos nacionales no se declaran. La fecha de recogida es hoy, en la zona horaria de la tienda, o el lunes si es fin de semana. Una tarifa en vivo solo se solicita después de que el cliente haya introducido una ciudad (con XML Services, una ciudad o un código postal). Hasta entonces se aplican los precios de reserva.
El producto DHL Express más barato se muestra como un único precio con el título de tu método. El cliente no ve el producto de DHL. 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 cotización se guarda en caché durante 1 hora por paquete y ruta. Una petición fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a DHL en cada actualización. El tiempo de espera de la API es de 12 segundos. Si DHL devuelve un error, no tiene servicio o responde con una moneda que no se puede usar, el cliente no ve ningún error: se usa el precio de reserva o se oculta el método. El motivo se escribe en el registro de depuración.
La extensión solo calcula tarifas. No crea envíos de DHL, no imprime etiquetas ni facturas comerciales, no reserva recogidas, no hace el seguimiento de paquetes, no ofrece puntos de servicio de DHL, no permite al cliente elegir entre productos de DHL, no empaqueta varias cajas, no añade seguro ni calcula aranceles e impuestos. La cotización es solo para el envío. Los aranceles y los impuestos de importación los paga el destinatario.
En OpenCart 4, el cliente pulsa Choose en el bloque del método de envío de la página de finalización de compra y elige DHL Express en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Pedidos
Cuando se realiza el pedido, la extensión guarda la tarifa calculada para su carrito. Abre el pedido en Sales > Orders: el panel DHL Express Africa encima del historial del pedido muestra lo que hay que reservar con DHL:
DHL product: el producto DHL Express de la tarifa en vivo, por ejemplo "EXPRESS WORLDWIDE (P)". Solo se muestra para tarifas en vivo.
Price source: Live DHL rate, Fallback price (no live rate) o Free shipping threshold.
Calculated price (excl. tax): el precio en la moneda predeterminada de tu tienda.
El producto de DHL no se muestra al cliente en los correos electrónicos ni en su página de pedido. El pedido muestra el título del método y el coste de envío como cualquier otro método de envío de OpenCart.
En OpenCart 4, la finalización de compra guarda un único pedido y lo actualiza cada vez que el cliente vuelve a confirmar. El panel muestra entonces la tarifa más reciente de la finalización de compra. Si el cliente cambia a otro método de envío, el panel ya no se muestra para ese pedido.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox DHL Africa es el primer bloque de Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit, 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: opencart-shipping-dhl-africa y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios del panel con permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel (se incluyen inglés y ruso).
Si no se acepta la clave, 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 tras liberar un cupo 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 cupo de dominio. Libera el cupo en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío DHL Express no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador con sesión iniciada en el panel, 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 panel, así que sin una clave activa el método se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel. 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 panel o la página Edit: 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 la extensión siempre se eliminan la clave de licencia y el estado de la licencia.
Solución de problemas
DHL Express no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable DHL Express Africa esté activado. Revisa Geo zone (o activa Ignore shipping zones y revisa Countries), los límites de peso y el Minimum subtotal. Sin tarifa en vivo, el método solo aparece si hay un precio de país o un coste de reserva. Comprueba que los productos tengan Requires Shipping en Yes.
Las tarifas en vivo no aparecen: revisa las advertencias en la parte superior de la página de la extensión (credenciales u origen que faltan). Activa Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Los errores de DHL, como un error HTTP de la API MyDHL, la falta de productos para la ruta o un problema de moneda, siempre se registran. Comprueba que Test mode coincida con tus credenciales y que la dirección del cliente tenga una ciudad.
DHL devuelve la tarifa en ZAR, NGN o KES, pero mi tienda usa otra moneda: el registro dice DHL quote not usable. Pon DHL quote currency en esa moneda e introduce el Exchange rate. Sin ello no se usa la tarifa en vivo y se aplican los precios de reserva.
Tengo credenciales antiguas de DHL XML Services: elige XML Services (legacy) en DHL API. Cambia a la API MyDHL cuando recibas credenciales de MyDHL.
El envío se cobra con impuesto dos veces: pon una Tax class para que la tarifa de DHL se tome sin el impuesto de DHL, o elige No tax para cobrar el importe de DHL tal como se cotiza.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las cotizaciones de DHL en caché.
La página dice "Warning: You do not have permission to modify VibeFox DHL Africa!": tu grupo de usuarios del administrador puede tener solo permiso de visualización. Da al grupo el permiso de modificación para extension/shipping/vfd_dhl_africa (OpenCart 3) o extension/vfd_dhl_africa/shipping/vfd_dhl_africa (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la extensión activa los eventos de OpenCart catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request y xml_request (con el mismo prefijo), que pueden cambiar la dirección de la API, la declaración aduanera, la caja y las peticiones a DHL.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox DHL Africa. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable DHL Express Africa, Sort order, Tax class y Geo zone. Las cotizaciones de DHL en caché y los eventos de la extensión siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de DHL y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Los productos de DHL de los pedidos realizados nunca se borran. 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 la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox DHL Africa en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
DHL es una marca comercial de su respectivo titular. Esta extensión no está afiliada a DHL ni cuenta con su respaldo.