VibeFox PostNL for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Clave de API de PostNL (solo para puntos de recogida): los puntos de recogida se cargan desde la API de Checkout de PostNL. 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. Los métodos de entrega a domicilio no necesitan clave.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_postnl a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox PostNL, o haz clic en Settings debajo del nombre del plugin en la página Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Rellena los precios. Para los puntos de recogida, introduce también la API key de PostNL y el Ship from (postcode) (ver Configuración).
6. Añade VibeFox PostNL a una zona de envío en WooCommerce > Settings > Shipping > Shipping zones, por ejemplo Países Bajos y Bélgica. En la zona, define el Title y el Delivery to. Añade el método una segunda vez para el otro tipo de entrega.
Configuración
Todos los ajustes, salvo el título y el tipo de entrega, están en una sola página: WooCommerce > Settings > Shipping > VibeFox PostNL. Se aplican a todas las zonas de envío. Al añadir el método a una zona, la ventana de la zona tiene dos campos:
Title (zone): el nombre que ve el cliente para este método de zona. Déjalo vacío para usar el Name global.
Delivery to (zone): As in the global settings (por defecto), PostNL pickup point (customer chooses a point) o Home address. Añade el método dos veces a una zona para ofrecer ambos.
Encima de los ajustes, la página muestra avisos: falta la clave de API o el código postal de origen para los puntos de recogida, el sandbox está activado, no hay ningún precio definido y la última petición fallida a PostNL, con su fecha y error.
General
Enable/Disable: activa o desactiva la entrega de PostNL en todas las zonas a la vez.
Name: el nombre del método de envío que se muestra en la finalización de compra. Un Title definido en la zona lo sustituye. Por defecto: PostNL.
Delivery to: el tipo de entrega por defecto para los métodos de zona que usan As in the global settings, y para el modo Ignore zones.
Tax status: Taxable añade el impuesto de WooCommerce al coste de envío; None no lo añade.
API de PostNL (puntos de recogida) (no 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", se guarda en la base de datos de WordPress y nunca se muestra a los clientes ni se escribe en el registro.
Sandbox: usa el sandbox de PostNL (api-sandbox.postnl.nl) con una clave de API de sandbox. Los clientes verán 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, Países Bajos o Bélgica. Por defecto es el país de tu tienda. 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 WooCommerce > Settings > General cuando la tienda esté en el mismo país. Un código postal no válido se rechaza con un mensaje. Al cambiar la clave de API, el ajuste de sandbox o la dirección de origen del envío, se borran las listas de puntos de recogida guardadas en caché.
Precios (en la moneda de la tienda)
PostNL no tiene una API pública de tarifas, así que el plugin no solicita tarifas en tiempo real y nunca convierte precios.
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 cruz para quitar 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 gratis. Se aceptan tanto "6.95" como "6,95". 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 un mensaje.
Calculation: Per order cobra el precio una sola vez. Per item (price x quantity) lo multiplica por el número de artículos enviables del carrito.
Price for other countries: se usa cuando la tabla no tiene ni el país ni una fila *. Déjalo vacío para ocultar el método allí.
Condiciones
Free shipping from: el subtotal del carrito a partir del cual la entrega es gratuita. Solo se aplica donde se encuentre un precio. Déjalo vacío para no ofrecer nunca envío gratis.
Minimum subtotal: muestra el método solo cuando el subtotal del carrito sea al menos este importe. Déjalo vacío para mostrarlo siempre.
Minimum weight (kg): oculta el método cuando el carrito pese menos. Los pesos de los productos se convierten desde la unidad de tu tienda. Déjalo vacío para no tener límite.
Maximum weight (kg): oculta el método para carritos más pesados. Por defecto: 30 (los paquetes de PostNL llegan hasta 30 kg en el Benelux). Déjalo vacío para no tener límite.
Hide for shipping classes: oculta el método cuando el carrito contiene un producto de cualquiera de estas clases de envío de WooCommerce.
Todos los importes y pesos aceptan coma decimal, también con separador de miles (1.234,50 o 1,234.50). Un número no válido se ignora con un mensaje.
Disponibilidad sin zonas de envío
Ignore zones: ofrece también PostNL a los países indicados abajo cuando ninguna zona lo añade. Las zonas que contienen el método siguen funcionando como siempre. Este modo usa el Name y el Delivery to globales.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envía la tienda. Este campo solo se usa cuando Ignore zones está activado.
Avanzado
Debug log: escribe mensajes de depuración en WooCommerce > Status > Logs (origen "vfd-postnl"). Los errores de la API siempre se registran. No se escribe ninguna clave de API ni datos de clientes. Desactiva el registro cuando termines.
Remove data on uninstall: si está activado, al eliminar el plugin se borran los ajustes de PostNL y los métodos de zona. Desactivar el plugin nunca borra los ajustes. Los puntos de recogida guardados en los pedidos siempre se conservan.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, WooCommerce pide al plugin una tarifa. El plugin comprueba las condiciones: peso del carrito, subtotal mínimo y clases de envío. 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 método se oculta. Si el subtotal del carrito alcanza Free shipping from, el precio es 0.
Un método de punto de recogida solo se ofrece para direcciones de los Países Bajos y Bélgica y solo con clave de API. En cuanto el cliente introduce un código postal válido, el plugin pide a la API de Checkout de PostNL los puntos de recogida más cercanos. Envía el código postal del cliente, la calle, el número, la ciudad y el país, y tu dirección de origen del envío. No se envía nada para los métodos de entrega a domicilio. Si no se puede contactar con PostNL o no hay puntos para la dirección, el método de punto de recogida se oculta y tus demás métodos siguen disponibles. 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 peticiones 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 pantalla de ajustes.
El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin no solicita tarifas en tiempo real de PostNL y no crea etiquetas de envío, códigos de barras, track and trace, devoluciones ni avisos previos. No tiene opciones de día de entrega, de entrega 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 un método de punto de recogida, aparece debajo una lista de PostNL pickup point con los tres puntos más cercanos: nombre de la empresa, dirección y distancia. Antes de introducir un código postal, el cliente ve el mensaje "Introduce tu código postal (por ejemplo 1234 AB) para ver los puntos de recogida de PostNL." (4 cifras para Bélgica). La elección se recuerda cuando se actualiza la finalización de compra.
El punto es obligatorio. Sin un punto, la finalización de compra se detiene con el mensaje "Elige un punto de recogida de PostNL." El servidor comprueba el punto con la lista de PostNL para la dirección de envío. Si no está en la lista, la finalización de compra se detiene con el mensaje "El punto de recogida de PostNL elegido no está disponible para esta dirección. Elígelo de nuevo." El nombre y la dirección guardados con el pedido proceden de PostNL, no del navegador.
Pantalla de pedido del administrador: PostNL pickup point con el nombre y la dirección y el Location code, debajo de la dirección de envío.
Página de pedido recibido y vista del pedido en Mi cuenta: PostNL pickup point con el nombre y la dirección.
Correos electrónicos del pedido: el nombre y la dirección del punto en los correos HTML y de texto plano.
En la base de datos, el punto se guarda en los metadatos del pedido _vfd_ptnl_servicepoint_id (código de ubicación de PostNL), _vfd_ptnl_servicepoint_name (nombre y dirección) y _vfd_ptnl_servicepoint (ID del socio, empresa, calle, número, código postal, ciudad, país).
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox PostNL. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa, y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, PostNL no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión sí lo ven, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
PostNL no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el método está añadido a la zona del país del cliente (o que Ignore zones está activado y el país está permitido). Comprueba que hay un precio definido para el país, los límites de peso, Minimum subtotal y Hide for shipping classes.
El método de punto de recogida no aparece: solo se muestra para direcciones neerlandesas y belgas, solo con clave de API, código postal de origen y precio, y solo cuando PostNL devuelve puntos para el código postal del cliente. Revisa los avisos encima de la pantalla de ajustes y WooCommerce > Status > Logs, origen "vfd-postnl". Los errores siempre se registran; activa Debug log para ver los detalles.
"Los puntos de recogida de PostNL no se pueden cargar en este momento": no se pudo contactar con PostNL, PostNL rechazó la clave de API o falta el código postal de origen. La pantalla de ajustes muestra el último error. Una clave de sandbox solo funciona con Sandbox activado, y una clave de producción solo con él desactivado.
Los clientes ven puntos de recogida de prueba: desactiva Sandbox.
Filtros para desarrolladores: vfd_ptnl_number_of_locations (por defecto 3), vfd_ptnl_checkout_request (cuerpo de la petición) y vfd_ptnl_api_url.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin mantiene todos los ajustes y solo borra las listas de puntos de recogida guardadas en caché. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan, junto con las listas de puntos guardadas en caché y el último error de la API. Los ajustes y los métodos de zona solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus líneas de envío y el punto de recogida guardado.
PostNL es una marca comercial de su respectivo titular. Este plugin no está afiliado ni respaldado por PostNL.