VibeFox DHL Africa for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior con la extensión cURL. El módulo no se instala en versiones anteriores de PHP ni sin cURL. Las DHL XML Services también necesitan la extensión SimpleXML de PHP.
Cuenta de DHL Express (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API MyDHL. Necesitas tu número de cuenta de DHL Express y las credenciales de la API MyDHL: una clave API y un secreto API. Pídelas en el DHL Developer Portal (MyDHL API, "Get access") o a tu gestor de cuenta de DHL Express. Las cuentas que todavía tengan credenciales de DHL XML Services (Site ID y contraseña) pueden usarlas en su lugar. Si solo usas precios alternativos, no necesitas credenciales de DHL.
Licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 DHL Africa más adelante en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Elige la DHL API, introduce la API key, la API secret y tu número de cuenta de DHL. Mantén activado Test mode 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 alternativo (ver Configuración). Haz clic en Save.
Al instalar, el módulo crea el transportista DHL Express con el texto de tiempo de entrega DHL Express courier. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el tiempo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures 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 DHL Africa > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda la página completa. Cada guardado también borra las cotizaciones de DHL en caché. Los precios y los pesos aceptan coma o punto decimal.
Las advertencias de la parte superior de la página te indican cuándo las tarifas en tiempo real están desactivadas porque falta la API key, la API secret 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 hay una moneda de cotización sin tipo de cambio, y cuando la unidad de peso o de dimensiones de la tienda en International > Localization (Local units) no es conocida por el módulo (entonces se lee como kg o cm). Si un valor no es válido al guardar (un nombre 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, la moneda de cotización, el país de origen o la regla de impuesto), un error indica el campo, se mantiene el valor anterior de ese campo y los demás ajustes se guardan.
General
Enable DHL Express Africa: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del transportista que ve el cliente en la compra. Por defecto: DHL Express. Obligatorio, hasta 64 caracteres.
Tax: la regla de impuesto del transportista, o No tax. Con una regla de impuesto (y con los impuestos activados en la tienda), la tarifa de DHL se toma sin el impuesto que cotiza DHL, y PrestaShop añade su propio impuesto. Con No tax, la tarifa de DHL se cobra tal como se cotiza, con el impuesto incluido.
DHL Express account (necesario solo para tarifas en tiempo real)
DHL API: la interfaz de DHL que se usa. Solo se muestran los campos de la API elegida.
API key: tu nombre de usuario de la API MyDHL (clave API).
API secret: tu contraseña de la API MyDHL (secreto API). Después de guardar, los campos API key y API secret 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: solo se muestra 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 API secret, 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 por defecto. Las credenciales de prueba solo funcionan en el entorno de pruebas, y las de producción solo en producción. Desactívalo cuando pases a producción.
Ship from
La dirección desde la que DHL recoge los paquetes. La tarifa depende de ella.
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).
Rates
Todos los precios están en la moneda predeterminada de tu tienda, sin impuestos. La tarifa en tiempo real es el producto DHL Express más económico 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 alternativo. Si no hay ninguno de los dos, el transportista 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 tiempo real se convierte desde esta moneda con el tipo de cambio de abajo. Si no, no se usa. Por defecto: — 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 tiempo real ni precio por país. Déjalo vacío para ocultar el transportista en ese caso.
Country prices: un precio alternativo por país de destino, uno por línea: CC:Price, por ejemplo ZA:25.00. Se usa cuando no hay tarifa en tiempo real. Las líneas con otro formato se ignoran, y una advertencia al guardar indica cuáles son.
Fallback price basis: Per order 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 por país y al coste alternativo. La tarifa en tiempo real de DHL siempre es para el paquete completo.
Free shipping from: el subtotal del carrito (productos que necesitan envío, después de descuentos, antes de impuestos) a partir del cual este transportista es gratuito. No se consulta a DHL. Déjalo vacío para que nunca sea gratuito.
Conditions
Minimum weight: oculta el transportista por debajo de este peso del carrito, en kg. 0 significa sin límite. No puede ser mayor que Maximum weight.
Maximum weight: oculta el transportista por encima de este peso del carrito, en kg. Por defecto: 70 (también se usa cuando el campo está vacío). 0 significa sin límite.
Minimum subtotal: muestra el transportista solo si el subtotal del carrito (después de descuentos, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Availability without shipping zones
Ignore shipping zones: ofrece el transportista sin que tú le asignes zonas. El transportista recibe todas las zonas, incluidas las que crees más adelante, y deciden los países de abajo. Al desactivarlo, el transportista vuelve a tener sus propias zonas.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países a los que envías. Se usa solo con Ignore shipping zones.
Advanced
Debug log: escribe los cálculos de tarifas en logs/vfd_dhla_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de DHL siempre se registran, incluso con esta opción desactivada. Las credenciales y las direcciones de los clientes nunca se registran.
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 el módulo se borran los ajustes, el transportista, los productos de DHL guardados de los pedidos y el registro. Si está desactivado, todo se conserva para una reinstalación.
Cómo funciona en la compra
En el paso de envío, PrestaShop pide al módulo el precio de DHL Express. Solo cuentan los productos físicos: los productos virtuales no suman peso ni se incluyen en el subtotal. El módulo primero comprueba las condiciones: los países de Ignore shipping zones, el peso del carrito y el subtotal mínimo. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna petición a DHL.
Si no, el módulo envía a DHL el origen y el destino (país, ciudad, código postal), el peso del carrito convertido a kg (al menos 0,5 kg) y una caja creada a partir de las dimensiones de los productos en cm: la longitud más larga, la anchura más grande y las alturas apiladas. Los productos sin dimensiones no suman 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, o el lunes si es fin de semana. Una tarifa en tiempo real solo se solicita después de que el cliente haya introducido una ciudad (con XML Services, una ciudad o un código postal). Antes de eso, se aplican los precios alternativos.
El producto DHL Express más económico se muestra como un solo precio con el nombre de tu transportista. El cliente no ve el producto de DHL. El precio se calcula en tu moneda predeterminada, se redondea y después se muestra en la moneda del carrito del cliente.
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 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 en una moneda que no se puede usar, el cliente no ve ningún error: se usa el precio alternativo o el transportista se oculta. El motivo se escribe en el registro de depuración.
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 tarifas. No crea envíos de DHL, no imprime etiquetas ni facturas comerciales, no reserva recogidas, no rastrea paquetes, no ofrece puntos de servicio de DHL, no deja elegir al cliente 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.
Pedidos
Cuando se realiza el pedido, el módulo guarda la tarifa calculada para su carrito. La página del pedido en el back office muestra entonces un bloque DHL Express Africa, para que sepas qué reservar con DHL:
DHL product: el producto DHL Express de la tarifa en tiempo real, por ejemplo "EXPRESS WORLDWIDE (P)". Se muestra solo para tarifas en tiempo real.
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.
Los recálculos posteriores del carrito, por ejemplo cuando el pedido se edita en el back office, no cambian estos valores. Las tarifas de carritos que nunca se convirtieron en pedido se eliminan después de 30 días.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox DHL Africa es el primer bloque de Modules > Module Manager > VibeFox DHL Africa > Configure, 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 eliminar la clave de esta tienda. Debajo de ellos están la línea Product: presta-shipping-dhl-africa 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. Tras cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo 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. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, el transportista DHL Express no se muestra a los clientes en la compra y no se calcula ninguna tarifa. El front office de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la compra. Aparece un aviso 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. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
DHL Express no aparece en la compra: comprueba que la licencia esté activa y que Enable DHL Express Africa esté activado. En Shipping > Carriers comprueba que el transportista cubre la zona del país del cliente y el grupo del cliente (o activa Ignore shipping zones y revisa Countries). Revisa los límites de peso y Minimum subtotal. Sin tarifa en tiempo real, el transportista solo aparece si hay un precio por país o un coste alternativo configurado. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.
Las tarifas en tiempo real no aparecen: revisa las advertencias de la parte superior de la página del módulo (credenciales u origen que faltan). Activa Debug log, recarga la compra y mira el campo Log de la página del módulo. 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. Configura DHL quote currency con esa moneda e introduce el Exchange rate. Sin ello, la tarifa en tiempo real no se usa y se aplican los precios alternativos.
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 tiene doble impuesto: configura una regla de impuesto en Tax para que la tarifa de DHL se tome sin el IVA 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 del módulo. Esto borra las cotizaciones de DHL en caché.
La página indica que no se encontró el transportista DHL Express: el transportista se borró en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Para desarrolladores, el módulo ofrece los hooks actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest y actionVfdDhlaXmlRequest para cambiar la URL de la API, la declaración aduanera, la caja y las peticiones de DHL.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox DHL Africa y elige Uninstall. La clave de licencia, el estado de la licencia y las cotizaciones de DHL en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se borra (los pedidos conservan su historial) y se eliminan los ajustes, los productos de DHL guardados de los pedidos y el registro. Si está desactivado, el transportista solo se desactiva, y los ajustes y los productos de DHL de los pedidos realizados se conservan. Al reinstalar el módulo se restaura el estado que tenía el transportista antes.
DHL es una marca comercial de su respectivo titular. Este módulo no está afiliado a DHL ni cuenta con su respaldo.