VibeFox PostNL for PrestaShop — Ayuda

Requisitos

PrestaShop: de 8.0 a 9.x, tema Classic o Hummingbird (o un tema basado en ellos).

PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.

Clave de API de PostNL (solo para puntos de recogida): los puntos de recogida se cargan desde la PostNL Checkout API. Los clientes empresariales de PostNL encuentran la clave de API en Mijn PostNL, en My account > API beheren. El sandbox de PostNL necesita una clave de sandbox aparte. El transportista de entrega a domicilio no necesita clave.

Clave de licencia de VibeFox: 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 PostNL 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 (consulta Clave de licencia).

4. Rellena los precios. Para los puntos de recogida, introduce también la API key de PostNL y el Ship from (postcode) (consulta Configuración). Haz clic en Save.

Al instalar, el módulo crea dos transportistas: PostNL pickup point con el texto de tiempo de entrega Delivery to a PostNL pickup point, y PostNL con PostNL delivery to the home address. Ambos están vinculados a las zonas de los Países Bajos y Bélgica y a todos los grupos de clientes. Puedes añadir zonas y cambiar los grupos de clientes, el tiempo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No definas precios allí: 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 PostNL > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. En WooCommerce, un método se añade a una zona dos veces, una por tipo de entrega. En PrestaShop, cada tipo de entrega es un transportista propio, con su propio nombre, estado y zonas.

Encima de los ajustes, la página muestra advertencias: falta la clave de API o el código postal de envío para los puntos de recogida, el sandbox está activado, no hay ningún precio definido, la última solicitud fallida a PostNL con su fecha y error, una unidad de peso de la tienda que el módulo no reconoce y un transportista eliminado.

General

PostNL pickup point: activa o desactiva el transportista de punto de recogida. El cliente debe elegir un punto de PostNL en la finalización de compra. Solo se ofrece para direcciones de los Países Bajos y Bélgica, y solo con clave de API. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Pickup point carrier name: el nombre que ven los clientes en la finalización de compra. Predeterminado: PostNL pickup point. Obligatorio.

PostNL home address: activa o desactiva el transportista de entrega a domicilio. No se elige ningún punto. Funciona en todos los países con precio. Es el mismo interruptor que el estado del transportista.

Home delivery carrier name: el nombre que ven los clientes en la finalización de compra. Predeterminado: PostNL. Obligatorio.

Tax status: la regla de impuesto de ambos transportistas. Una regla Taxable añade el impuesto de envío de esa regla sobre los precios. None significa que los precios son definitivos.

API de PostNL (puntos de recogida) (no es necesaria para la entrega a domicilio)

API key: tu clave de API de PostNL, de Mijn PostNL (My account > API beheren). Se envía a PostNL en la cabecera "apikey" y nunca se muestra a los clientes ni se escribe en el registro. 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 la casilla y haz clic en Save para borrar la clave guardada. Entonces el transportista de punto de recogida deja de ofrecerse.

Sandbox: usa el sandbox de PostNL (api-sandbox.postnl.nl) con una clave de API de sandbox. Entonces los clientes ven puntos de recogida de prueba. Mantenlo desactivado en una tienda en producción.

Ship from (country): el país desde el que entregas tus paquetes a PostNL (Netherlands o Belgium). Predeterminado: Netherlands. PostNL usa la dirección del remitente para la fecha de recogida.

Ship from (postcode): el código postal del remitente, por ejemplo 1234AB en los Países Bajos o 1000 en Bélgica. Déjalo vacío para usar el código postal de la tienda de Shop Parameters > Contact > Stores cuando la tienda esté en el mismo país. Un código postal no válido se guarda vacío con una advertencia. Cuando cambies la clave de API, el ajuste del sandbox o la dirección de envío, se borran las listas de puntos de recogida en caché y el último error de la API.

Precios (en la moneda predeterminada de la tienda, sin impuestos)

Los precios se aplican a ambos transportistas. PostNL no tiene una API pública de tarifas, así que el módulo no solicita tarifas en tiempo real. Para un cliente que paga en otra moneda, PrestaShop convierte el precio con el tipo de cambio de tu tienda.

Price per country: una fila por país de destino. Haz clic en + Add country para añadir una fila y en el icono de papelera para eliminar una. Elige * All other countries para una fila que cubra todos los países sin fila propia. Cada fila tiene un Price y clases de peso opcionales según el peso del carrito: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg y XL por encima de 5 kg. Un precio de clase de peso sustituye a Price; déjalo vacío para usar Price. Un Price de 0 significa envío gratuito. Se aceptan "6.95", "6,95" y cantidades con separador de miles, como "1.234,50" o "1,234.50". Las filas vacías y los códigos de país no válidos se eliminan al guardar. Si un país aparece dos veces, se conserva la primera fila. Los precios no válidos se ignoran con una advertencia.

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

Price for other countries: se usa cuando la tabla no tiene ni el país ni una fila *. Déjalo vacío para ocultar los transportistas en esos países.

Condiciones

Free shipping from: el subtotal del carrito (productos que necesitan envío, sin impuestos, después de descuentos) a partir del cual la entrega es gratuita. Solo se aplica donde se encuentra un precio. Déjalo vacío para no ofrecer nunca envío gratuito.

Minimum subtotal: muestra los transportistas solo cuando el subtotal del carrito sea al menos esta cantidad. Déjalo vacío para mostrarlos siempre.

Minimum weight (kg): oculta los transportistas cuando el carrito pese menos. Los pesos de los productos se convierten desde la unidad de peso de tu tienda. Déjalo vacío para no tener límite.

Maximum weight (kg): oculta los transportistas para carritos más pesados. Predeterminado: 30 (los paquetes de PostNL llegan hasta 30 kg en el Benelux). 0 significa sin límite. Si lo dejas vacío, se aplican 30 kg en las zonas de los transportistas, y no se aplica ningún límite solo en los países a los que se llega mediante Ignore zones. Un peso mínimo superior al máximo se rechaza con un error, porque los transportistas nunca se mostrarían.

Todos los importes y pesos aceptan la coma decimal, también con separador de miles. Un número no válido o negativo se ignora con una advertencia, y el campo se guarda vacío.

Disponibilidad sin zonas de envío

Normalmente, los transportistas se ofrecen en las zonas de envío a las que están vinculados en Shipping > Carriers.

Ignore zones: ofrece también PostNL en los países de abajo cuando sus zonas no los incluyen. Entonces los transportistas se vinculan a todas las zonas activas, también a las que crees más adelante. Cuando lo desactives de nuevo, los transportistas recuperan las zonas que tenían antes.

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 zones está activado. En esos países se pueden ofrecer ambos transportistas; el de punto de recogida, sin embargo, solo para los Países Bajos y Bélgica.

Avanzado

Debug log: escribe mensajes de depuración en logs/vfd_ptnl_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. No se escribe ninguna clave de API ni datos de clientes. 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: si está activado, al desinstalar el módulo se borran los ajustes y los transportistas de PostNL. Si está desactivado, al desinstalar solo se desactivan los transportistas. Los puntos de recogida guardados en los pedidos siempre se conservan.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de cada transportista de PostNL. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el subtotal. El módulo comprueba las condiciones: peso del carrito y subtotal mínimo. Después toma el precio de la tabla para el país y la clase de peso, o el precio para otros países. Si no hay precio, el transportista se oculta. Si el subtotal del carrito alcanza Free shipping from, el precio es 0.

El transportista de punto de recogida solo se ofrece para direcciones de los Países Bajos y Bélgica, y solo con clave de API. Cuando la dirección de entrega tiene un código postal válido, el módulo pide a la PostNL Checkout API los tres puntos de recogida más cercanos. Envía el código postal, la calle, el número de casa, la ciudad y el país del cliente, y tu dirección de envío. Para el transportista de entrega a domicilio no se envía nada. Si no se puede contactar con PostNL o no hay puntos para la dirección, el transportista de punto de recogida se oculta y el de entrega a domicilio sigue disponible. El tiempo de espera de la API es de 12 segundos.

Las listas de puntos se guardan en caché durante 6 horas por código postal, y las respuestas "sin puntos", durante 1 hora. Las solicitudes fallidas se guardan en caché durante 10 minutos, para que una caída no ralentice cada actualización de la finalización de compra. El último error se muestra en la página del módulo.

Si editas un 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 no solicita tarifas de PostNL en tiempo real y no crea etiquetas de envío, códigos de barras, track and trace, devoluciones ni prealertas. No tiene opciones de entrega en un día concreto, por la tarde o por la mañana. Crea el envío en Mijn PostNL u otra herramienta de PostNL usando el punto de recogida guardado.

Puntos de recogida

Cuando el cliente selecciona el transportista de punto de recogida, debajo aparece una lista de PostNL pickup point con los tres puntos más cercanos: nombre de la empresa, dirección y distancia. La página nunca espera a PostNL: si la lista aún no está en caché, se carga en cuanto se selecciona el transportista. Antes de introducir un código postal completo, el cliente ve "Introduce tu código postal (por ejemplo 1234 AB) para ver los puntos de recogida de PostNL." (4 cifras en Bélgica). El punto elegido se guarda en el carrito y se mantiene cuando se actualiza la finalización de compra.

El punto es obligatorio. Sin él, el cliente no puede continuar y ve "Por favor, elige un punto de recogida de PostNL." Cuando el cliente hace clic en Continue, el servidor comprueba el punto con la lista de PostNL para la dirección de entrega. Si no está en la lista, el cliente ve "El punto de recogida de PostNL elegido no está disponible para esta dirección. Vuelve a elegirlo." Si no se puede contactar con PostNL, el cliente ve "Ahora mismo no se pueden cargar los puntos de recogida de PostNL. Vuelve a intentarlo en unos minutos o elige otro método de envío." Un punto elegido para otra dirección nunca se usa para el pedido. El nombre y la dirección guardados con el pedido proceden de PostNL, no del navegador.

Página de pedido del administrador: un bloque PostNL pickup point con el nombre y la dirección, el Location code y el Partner ID.

Páginas de confirmación y de detalle del pedido: PostNL pickup point con el nombre y la dirección.

Correos electrónicos de pedido: el nombre y la dirección del punto se añaden al nombre del transportista en el correo de confirmación del pedido. El correo de nuevo pedido de la tienda (módulo Mail alerts) también muestra el código de ubicación.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PostNL es el primer bloque de Modules > Module Manager > VibeFox PostNL > 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 aparecen la línea Product: presta-shipping-postnl y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y 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 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, 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, los transportistas de PostNL no se muestran a los clientes en la finalización de compra y no se calcula ningún precio de envío. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que los transportistas también se ocultan 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. El Reset de este módulo no borra datos, así que la clave y el estado se conservan.

Solución de problemas

PostNL no aparece en la finalización de compra: comprueba que la licencia esté activa y que el interruptor del transportista esté encendido. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o que Ignore zones esté activado y el país permitido). Comprueba que hay un precio definido para el país, los límites de peso y Minimum subtotal. Los productos también pueden limitarse a ciertos transportistas en la página del producto.

El transportista de punto de recogida no aparece: solo se muestra para direcciones neerlandesas y belgas, solo con clave de API, código postal de envío y precio, y solo cuando PostNL devuelve puntos para el código postal del cliente. Revisa las advertencias de la parte superior de la página del módulo y el campo Log. Los errores siempre se registran; activa Debug log para ver los detalles.

"PostNL pickup points cannot be loaded right now": no se pudo contactar con PostNL, PostNL rechazó la clave de API o falta el código postal de envío. La página del módulo muestra el último error. Una clave de sandbox funciona solo con Sandbox activado, y una clave de producción solo con él desactivado.

Los clientes ven puntos de recogida de prueba: desactiva Sandbox.

Los pesos de los productos parecen incorrectos: si la página del módulo advierte de que no se reconoce la unidad de peso de la tienda, define una unidad estándar (kg, g, lb u oz) en International > Localization, en Local units. Hasta entonces, los pesos de los productos se leen como kg.

La página indica que no se encontró un transportista de PostNL: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo. Restablecer conserva tus ajustes y el estado de los transportistas.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox PostNL y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las listas de puntos de recogida en caché y el último error de la API siempre se eliminan. Si Remove data on uninstall está activado, los transportistas se borran (los pedidos conservan su historial) y se eliminan los ajustes y el registro. Si está desactivado, los transportistas solo se desactivan y se conservan todos los ajustes. Volver a instalar el módulo devuelve a los transportistas el estado que tenían. Los pedidos existentes conservan sus líneas de envío y el punto de recogida guardado.

PostNL es una marca comercial de su respectivo propietario. Este módulo no está afiliado a PostNL ni avalado por PostNL.