VibeFox DHL Packstation for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x. Se admiten los temas Classic y Hummingbird.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

DHL API key: la lista de ubicaciones procede de la API gratuita DHL Location Finder. Regístrate en el portal para desarrolladores de DHL (developer.dhl.com), crea una aplicación, añade la API «Location Finder - Unified» y copia la clave de API de la aplicación. Para esta API no hace falta un contrato comercial con DHL. Sin la clave, el transportista no aparece en la finalización de compra. Ten en cuenta el límite de solicitudes de tu aplicación de DHL: cada nueva búsqueda por código postal o ciudad es una solicitud a la API.

VibeFox license key: se compra en vibefox.net. Una clave funciona en un 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 más tarde VibeFox DHL Packstation 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. Pega la clave de API de DHL, haz clic en Save y después en Test API key. Elige los tipos de ubicación e introduce los precios por país (véase Configuración).

Al instalar, el módulo crea el transportista DHL Packstation con el texto del plazo de entrega Delivery to a DHL Packstation or post office. El transportista está activado y asignado a todos los grupos de clientes y a las zonas de Alemania y Austria (los países de la lista de precios predeterminada). Puedes cambiar zonas, grupos de clientes, plazo de entrega, logotipo y límites de tamaño en Shipping > Carriers. No configures aquí los precios: el precio siempre procede del módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox DHL Packstation > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Si un campo tiene un error (un número no válido o negativo, Min weight (kg) mayor que Max weight (kg), o un nombre de más de 64 caracteres), no se guarda nada y el error aparece en la parte superior. Cada guardado vacía la caché de ubicaciones.

Las advertencias encima de los ajustes indican cuándo no se encontró el transportista, cuándo la unidad de peso de la tienda (International > Localization, Local units) no es conocida por el módulo (en ese caso los pesos se leen como kg; usa kg, g, lb u oz), cuándo la clave de API de DHL está vacía, cuándo no hay ningún tipo de ubicación activado y cuándo las entradas de precios por país no están en formato CC:PRICE (estas entradas se ignoran).

General

Los grupos de clientes, las zonas y los límites de tamaño del transportista se configuran en Shipping > Carriers. Los ajustes siguientes se aplican a todas las zonas.

Enable/Disable: 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. Por defecto: DHL Packstation. Obligatorio, máximo 64 caracteres.

Tax: la regla de impuesto del transportista o No tax. PrestaShop añade este impuesto sobre los precios de abajo. Con No tax, los precios son definitivos.

DHL Location Finder API

DHL API key: la «API Key» de tu aplicación en developer.dhl.com. Sin ella, el transportista no aparece en la finalización de compra. Después de guardar, el campo queda vacío y muestra Saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.

Remove the saved API key: marca esta casilla y guarda para borrar la clave almacenada.

Connection test: el botón Test API key busca las ubicaciones cercanas a 53113 Bonn con la clave guardada y vacía la caché de ubicaciones. Guarda primero los ajustes. Muestra cuántas ubicaciones se encontraron, si DHL rechazó la clave (401/403) o si la API no respondió correctamente (detalles en el registro de depuración).

Ubicaciones de recogida

En la finalización de compra, el cliente ve las ubicaciones cercanas a su código postal de entrega y puede buscar otro código postal o ciudad.

Location types: qué ubicaciones de DHL puede elegir el cliente: Packstation (parcel locker), Post Office (Postfiliale) y DHL Parcel Shop (Paketshop). Las tres están activadas por defecto. Si no se selecciona ninguna, el transportista no aparece. Para un Packstation, el cliente debe introducir su DHL Postnummer.

Search radius (meters): el radio alrededor del código postal o la ciudad buscados. Por defecto: 5000. Número entero; los valores inferiores a 100 o superiores a 25000 m (el máximo de DHL) se ajustan a ese límite.

Max results: el número máximo de ubicaciones que se muestran en cada búsqueda. Por defecto: 20. Número entero; DHL admite hasta 50, y los valores mayores se reducen a 50.

Shipping address: usa la ubicación elegida como dirección de entrega del pedido. Activado por defecto. La línea de dirección 1 pasa a ser, por ejemplo, «Packstation 105» (o «Postfiliale 502» para una Post Office o un DHL Parcel Shop), y la línea 2 «Postnummer» con el número, además del código postal, la ciudad y el país de la ubicación, para que las etiquetas impresas desde el pedido vayan al lugar correcto. El nombre, la empresa y el teléfono proceden de la dirección del cliente. La nueva dirección solo la usa el pedido y no aparece en la libreta de direcciones del cliente.

Precios (el título de la sección muestra la moneda predeterminada de tu tienda)

Country prices: el precio por país de destino en la moneda predeterminada de la tienda, sin impuestos, formato CC:PRICE, separado por comas o saltos de línea. Por defecto: DE:4.99, AT:5.99. También funciona la coma decimal (DE:4,99).

Other countries: el precio para un país de destino que no está en Country prices. Por defecto: 5.99. Déjalo vacío para ocultar el transportista en esos países.

Calculation: Per order cobra el precio una sola vez. Per item (price x quantity) lo multiplica por el número de artículos del carrito.

Free shipping from: el subtotal del carrito (productos que requieren envío, después de descuentos y antes de impuestos) a partir del cual este envío es gratuito. Déjalo vacío si nunca debe ser gratuito.

Disponibilidad

Min weight (kg): el peso mínimo del carrito. Los pesos de los productos se convierten desde la unidad de peso de tu tienda. 0 significa sin límite.

Max weight (kg): el transportista se oculta por encima de este peso del carrito. Por defecto: 31.5, porque un Packstation admite paquetes de hasta 31,5 kg. 0 significa sin límite.

Minimum subtotal: muestra el transportista solo si el subtotal del carrito (productos que requieren envío, después de descuentos y antes de impuestos) es al menos este valor. Déjalo vacío para mostrarlo siempre.

Ignore shipping zones: cuando está activado, el transportista se vincula a todas las zonas activas (también a las creadas más adelante) y se ofrece para los países de abajo o, si la lista está vacía, para todos los países. Al desactivarlo de nuevo, el transportista recupera las zonas que tenía antes.

Countries (ignore zones): los países de destino para ese modo. Ctrl/Cmd + clic para seleccionar varios países. Se usa solo con Ignore shipping zones.

Avanzado

Debug log: escribe las solicitudes a la API y los pasos de la finalización de compra en logs/vfd_dhlp_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. Nunca se escriben la clave de API, el Postnummer ni las direcciones de los clientes.

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: cuando está activado, al desinstalar el módulo se borran los ajustes, el transportista, las búsquedas en caché y los registros. Las ubicaciones elegidas se mantienen en los pedidos. Cuando está desactivado, se conserva todo para una reinstalación.

Cómo funciona en la finalización de compra

En el paso de entrega, PrestaShop pide al módulo el precio de DHL Packstation. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el subtotal. El módulo comprueba que estén configurados una clave de API y al menos un tipo de ubicación, los países permitidos (con Ignore shipping zones), el peso del carrito y el subtotal mínimo. Después toma el precio del país de destino (o el precio de otros países) y aplica el envío gratuito si el subtotal es suficientemente alto. El precio se calcula en la moneda predeterminada de tu tienda y se muestra en la moneda del carrito del cliente.

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 automáticamente la nueva versión.

El módulo no crea envíos de DHL, no imprime etiquetas ni hace seguimiento de paquetes. Usa el portal de clientes empresariales de DHL o una herramienta de etiquetas: con Shipping address activado, el pedido ya contiene la dirección del Packstation y el Postnummer. El módulo no calcula tarifas de DHL en tiempo real y no muestra mapa. No existe la introducción manual de un número de Packstation.

Puntos de recogida

Cuando el cliente selecciona DHL Packstation, aparece un selector debajo del transportista. Se cargan las ubicaciones de DHL cercanas al código postal y a la ciudad de entrega. DHL solo se consulta para el transportista seleccionado. El cliente puede escribir otro código postal o ciudad y hacer clic en Search. Las ubicaciones se agrupan por tipo (Packstation, Post Office, Parcel Shop) y se ordenan por distancia. Si no se encuentra nada, el cliente ve No DHL locations found near "…". Try another postcode or city.

Para un Packstation, el cliente debe introducir el DHL Postnummer, su número de cliente de DHL de 6-12 dígitos, que encuentra en la aplicación o en la cuenta de DHL. Para las demás ubicaciones es opcional. La elección se guarda en el carrito en cuanto se hace. Al hacer clic en Continue, el servidor la vuelve a comprobar: la ubicación debe ser uno de los resultados de búsqueda de DHL en el país de entrega. Sin ubicación, el cliente ve Please choose a DHL Packstation or post office for delivery. y no puede continuar. Un Postnummer que falte o no sea válido se notifica de la misma forma.

Los resultados de búsqueda se guardan en caché durante 12 horas. Una búsqueda vacía o 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 no se puede acceder a la API de DHL, el cliente ve DHL locations cannot be loaded right now. Please try again later or choose another shipping method. Una ubicación que el cliente ya había elegido sigue siendo aceptada.

Cuando se realiza el pedido, la ubicación (ID, tipo, número, nombre, dirección) y el Postnummer se guardan con el pedido. Si Shipping address está activado, la dirección de entrega del pedido se sustituye por la dirección de la ubicación. La ubicación aparece en la página de confirmación del pedido, en Order history and details de la cuenta del cliente, y en el correo de confirmación del pedido y en el correo de nuevo pedido del módulo Mail alerts, añadida al nombre del transportista como DHL pickup location y DHL Postnummer.

En la página del pedido del back office, el bloque DHL pickup location muestra la ubicación, su tipo e ID, y el Postnummer. Haz clic en Change, busca por código postal o ciudad, elige otra ubicación, cambia el Postnummer y haz clic en Save location. También puedes cambiar solo el Postnummer. Cada cambio añade un mensaje privado al pedido: DHL pickup location changed to: …. Si Shipping address está activado, también se actualiza la dirección de entrega del pedido. Cambiar la ubicación requiere permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Si se crearon varios pedidos a partir de un mismo carrito, la ubicación pertenece solo al primer pedido; Change en otro pedido de ese carrito muestra The DHL location of this cart belongs to another order of the same cart - nothing was changed.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox DHL Packstation es el primer bloque de Modules > Module Manager > VibeFox DHL Packstation > 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-packstation 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 Packstation no se muestra a los clientes en la finalización de 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 finalización de 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 el módulo elimina siempre la clave de licencia y el estado de la licencia. Reset de este módulo no borra los datos, así que la clave y el estado se conservan.

Solución de problemas

DHL Packstation no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o activa Ignore shipping zones y revisa Countries (ignore zones)). Comprueba que DHL API key esté rellenada, que al menos un tipo de ubicación esté seleccionado, que el país de destino tenga un precio (o que Other countries esté definido), y que las reglas de peso y subtotal no lo oculten. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.

No se muestran ubicaciones: haz clic en Test API key. Si DHL rechaza la clave (401/403), revisa la clave y que tu aplicación tenga la API «Location Finder - Unified». Activa Debug log, recarga la finalización de compra y mira el campo Log en la página del módulo. Comprueba que no se haya alcanzado el límite de solicitudes de tu aplicación de DHL.

No hay ubicaciones cerca de una dirección: aumenta Search radius (meters) o Max results, o deja que el cliente busque otro código postal o ciudad. Un Packstation sin número en los datos de DHL no aparece en la lista.

El cliente ve «Enter your postcode or city to see DHL locations near you.»: la dirección de entrega no tiene código postal ni ciudad. El cliente puede escribir uno en el campo de búsqueda.

En la página del pedido, Change muestra «Please choose a DHL location of the search - nothing was changed.»: busca por código postal o ciudad y elige una ubicación de los resultados. Si el pedido aún no tiene ubicación, hay que elegir una antes de poder guardar el Postnummer.

La página indica que no se encontró el transportista DHL Packstation: el transportista se eliminó en Shipping > Carriers. Usa Reset en Modules > Module Manager para volver a crearlo. Reset conserva el estado de activado/desactivado de un transportista existente.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox DHL Packstation y elige Uninstall. La clave de licencia, el estado de la licencia y la caché de ubicaciones siempre se eliminan. Si Remove data on uninstall está activado, el transportista se borra (los pedidos conservan su historial), y se eliminan los ajustes, el registro y las ubicaciones de los carritos sin pedido. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo se restaura el estado que tenía el transportista antes. Las ubicaciones elegidas siempre se mantienen en los pedidos.

DHL y Packstation son marcas comerciales de sus respectivos propietarios. Este módulo no está afiliado a DHL ni cuenta con su respaldo.