VibeFox DHL Packstation 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). El selector de ubicaciones funciona con la finalización de compra estándar de OpenCart.

PHP: 8.0 o posterior.

Clave de API de DHL: 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 método se oculta en la finalización de compra. Ten en cuenta el límite de peticiones de tu aplicación de DHL: cada nueva búsqueda de código postal o ciudad es una petición a la API.

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_packstation-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_dhl_packstation.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_packstation-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 Packstation 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 License key, en el bloque de licencia de la parte superior de la página Edit, y haz clic en Activate (ver Clave de licencia).

5. 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 (ver Configuración). Activa Enable/Disable 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_packstation.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 Packstation, 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 para 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/Disable y guardes. La lista de precios predeterminada incluye precios para Alemania y Austria, y un precio para otros países. Si vuelves a instalar la extensión tras desinstalarla, se vuelven a usar los ajustes que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado borra la caché de ubicaciones. Si un campo tiene un error (un nombre no válido o de más de 64 caracteres, un radio o un número de resultados que no es un número entero, un número no válido o negativo, Min weight (kg) mayor que Max weight (kg), un orden de clasificación que no es un número entero, una clase de impuesto o una zona geográfica desconocidas), no se guarda nada y se muestra el error. 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 la clave de API de DHL está vacía, cuando no hay ningún tipo de ubicación activado (en ambos casos el método no se muestra en la finalización de compra), cuando las entradas de precios por país no están en el formato CC:PRICE (estas entradas se ignoran), y cuando no hay una clase de peso con la unidad kg en System > Localisation > Weight Classes (los pesos de los productos se leen entonces según el nombre de la unidad de su clase: kg, g, lb u oz; las unidades desconocidas se tratan como kg).

General

Los ajustes se aplican a todas las zonas geográficas.

Enable/Disable: activa DHL Packstation en la finalización de compra. Predeterminado: desactivado.

Name: el nombre del método de envío que ve el cliente. Predeterminado: DHL Packstation. Obligatorio, como máximo 64 caracteres, sin los caracteres < > ; = # { }.

Tax Class: la clase de impuesto del coste de envío, o --- None --- (predeterminado). OpenCart añade este impuesto sobre los precios de abajo. Con --- None --- los precios son definitivos.

Sort Order: la posición de DHL Packstation entre los métodos de envío. Un número entero.

API DHL Location Finder

DHL API key: la "API Key" de tu aplicación en developer.dhl.com. Sin ella, el método se oculta 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: se muestra cuando hay una clave guardada. 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 borra la caché de ubicaciones. Guarda primero los ajustes. Muestra cuántas ubicaciones se han encontrado (Connected: … DHL locations found near 53113 Bonn.), que DHL ha rechazado la clave (401/403), o que la API no ha respondido 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 envío 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 de forma predeterminada. Si no se selecciona ninguna, el método se oculta. Para un Packstation, el cliente debe introducir su DHL Postnummer.

Search radius (meters): el radio alrededor del código postal o la ciudad buscados. Predeterminado: 5000. Un 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 por búsqueda. Predeterminado: 20. Un número entero; DHL permite hasta 50, y los valores mayores se reducen a 50.

Shipping address: usa la ubicación elegida como dirección de envío del pedido. Activado por defecto. La línea 1 de la dirección pasa a ser, por ejemplo, "Packstation 105" (o "Postfiliale 502" para una oficina de correos o un DHL Parcel Shop), 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 región se vacía. La libreta de direcciones del cliente no se modifica.

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 tu tienda, sin impuestos, en formato CC:PRICE, separados por comas o saltos de línea. Predeterminado: DE:4.99, AT:5.99. La coma decimal también funciona (DE:4,99).

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

Calculation: Per order (predeterminado) 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 de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual este envío es gratuito. Déjalo vacío si nunca es gratuito.

Disponibilidad

Min weight (kg): el peso mínimo del carrito. Los pesos de los productos se convierten desde su clase de peso. 0 significa sin límite (predeterminado).

Max weight (kg): el método se oculta por encima de este peso del carrito. Predeterminado: 31.5, porque un Packstation admite paquetes de hasta 31,5 kg. 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 valor. Déjalo vacío para mostrarlo siempre.

Geo Zone: ofrece el método solo en esta zona geográfica. All Zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se usa con Ignore shipping zones.

Ignore shipping zones: si está activado, el método se ofrece para los países de abajo (todos los países si la lista está vacía), sea cual sea la zona geográfica de la dirección.

Countries (ignore zones): los países de destino para ese modo. Solo se usa con Ignore shipping zones.

Avanzado

Debug log: escribe las peticiones a la API y los pasos de la finalización de compra en storage/logs/vfd_dhlp_debug.log.php (en OpenCart 4, system/storage/logs/vfd_dhlp_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, incluso cuando está desactivado. La clave de API, el Postnummer y las direcciones de los clientes nunca se escriben. Cuando el archivo llega a 5 MB, se mueve a vfd_dhlp_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 búsquedas en caché, el registro y las ubicaciones de las finalizaciones de compra sin terminar. Las ubicaciones elegidas se conservan en los pedidos. Si está desactivado (predeterminado), todo se conserva para una reinstalación.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. La clave de API no se exporta.

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. La clave de API guardada se conserva.

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 Packstation. Si hay una Geo Zone establecida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, el método no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no añaden peso ni se incluyen en el subtotal. La extensión comprueba que haya 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 lo bastante alto. El subtotal es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. El precio no depende de la ubicación, y no se envía ninguna petición a DHL para calcularlo. Se calcula en tu moneda predeterminada y se muestra al cliente en su moneda con el impuesto de la Tax Class seleccionada.

La extensión no crea envíos de DHL, no imprime etiquetas ni hace el seguimiento de paquetes. Usa el portal de clientes comerciales de DHL o una herramienta de etiquetas: con Shipping address activado, el pedido ya contiene la dirección del Packstation y el Postnummer. La extensión no calcula tarifas en vivo de DHL y no muestra mapa. No existe una entrada manual de número de Packstation.

Puntos de recogida

Cuando el cliente selecciona DHL Packstation en el paso del método de envío, aparece un selector debajo del método. Se cargan las ubicaciones de DHL cercanas al código postal y a la ciudad de entrega. 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 a 12 dígitos, de la aplicación de DHL o de su cuenta de DHL. Para otras ubicaciones es opcional. La elección se guarda 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. Si falta el Postnummer de un Packstation, se muestra Please enter your DHL Postnummer - it is required for delivery to a Packstation., y si no es válido, The DHL Postnummer must consist of 6 to 12 digits.

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. Con la caché de archivos predeterminada de OpenCart, las entradas duran como máximo lo que dure la caché de la tienda (1 hora por defecto), así que la lista se actualiza una vez por hora. El tiempo de espera de la API es de 12 segundos. Si no se puede contactar con 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.

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 DHL Packstation en la ventana Shipping method options. El selector aparece en esa ventana, debajo del método, y funciona como se ha descrito antes. El botón Continue de la ventana no avanza sin una ubicación válida o, para un Packstation, sin el Postnummer, con los mismos mensajes.

Cuando se realiza el pedido, la ubicación (ID, tipo, número, nombre, dirección) y el Postnummer se guardan con el pedido. La ubicación se añade al método de envío del pedido como DHL pickup location: y DHL Postnummer:, para que aparezca donde OpenCart muestra el método de envío: la página de pedido del cliente, los correos electrónicos del pedido y la factura. Si Shipping address está activado, la dirección de envío del pedido se sustituye por la dirección de la ubicación.

OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar. La ubicación, el texto del método de envío y la dirección del pedido se actualizan con él.

Pedidos

Abre el pedido en Sales > Orders. El panel DHL pickup location encima del historial del pedido muestra la ubicación, su tipo e ID, y el Postnummer, también después de desactivar la extensión. Un pedido sin ubicación muestra No DHL location was selected for this order.

Haz clic en Change, busca por código postal o ciudad, elige otra ubicación de la lista de DHL, cambia el Postnummer si hace falta y haz clic en Save location. También puedes cambiar solo el Postnummer. El texto del método de envío del pedido se actualiza. Si Shipping address está activado, la dirección de envío del pedido también se actualiza, partiendo de nuevo de la dirección original del cliente. Cada cambio añade al historial del pedido una entrada DHL pickup location changed to: …, con el estado actual del pedido y sin notificar al cliente. Cambiar la ubicación requiere el permiso de modificación de pedidos; no hace falta acceso a los ajustes de la extensión.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox DHL Packstation es el primer bloque de Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit, por encima de los ajustes. Pega 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-packstation 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 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. Después de cambiar la dirección de la tienda, o tras liberar una plaza 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 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. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, el método de envío DHL Packstation no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un administrador que haya iniciado sesión 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 requieren 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 hace falta ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

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. Revisa Geo Zone (o activa Ignore shipping zones y revisa Countries (ignore zones)). Comprueba que la DHL API key esté introducida, que al menos un tipo de ubicación esté seleccionado, que el país de destino tenga un precio (o que Other countries esté configurado), y que las reglas de peso y de subtotal no lo oculten. Comprueba que los productos tengan Requires Shipping en Yes.

No se muestra ninguna ubicación: 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 de la página de la extensión. Comprueba que no se haya alcanzado el límite de peticiones de tu aplicación de DHL.

No hay ubicaciones cerca de una dirección: aumenta el Search radius (meters) o el 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.

Change en la página de pedido del administrador dice "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 todavía no tiene ubicación, hay que elegir una antes de poder guardar el Postnummer.

Falta el panel de ubicación de recogida de DHL en la página de pedido: el panel solo se muestra en los pedidos enviados con DHL Packstation (se mantiene aunque la extensión esté desactivada).

La página dice "Warning: You do not have permission to modify VibeFox DHL Packstation!": 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_packstation (OpenCart 3) o extension/vfd_dhl_packstation/shipping/vfd_dhl_packstation (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 DHL Packstation. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable/Disable, Sort Order, Tax Class y Geo Zone. La caché de ubicaciones y los eventos de la extensión siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes, el registro y las ubicaciones de las finalizaciones de compra sin terminar. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Las ubicaciones elegidas siempre se conservan en los pedidos, y los pedidos existentes mantienen su método de envío, su coste y su dirección.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox DHL Packstation en la lista de extensiones instaladas, y después en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.

DHL y Packstation son marcas comerciales de sus respectivos titulares. Esta extensión no está afiliada a DHL ni cuenta con su respaldo.