VibeFox PostNL 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).

PHP: 8.0 o posterior.

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

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

La descarga es un único archivo zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_postnl-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_postnl.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 administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_postnl-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, 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 PostNL y haz clic en Install (el botón verde +).

3. Haz clic en Edit (el botón con el lápiz) para abrir la página de configuración.

4. Pega 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 (consulta Clave de licencia).

5. Activa PostNL pickup point y/o PostNL home address y 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.

OpenCart 4

1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_postnl.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 PostNL, 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 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.

Tras la instalación, ambas opciones están desactivadas hasta que actives alguna y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de PostNL que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox PostNL > Edit. Las secciones aparecen a la izquierda. Un único botón Save al final guarda toda la página sin recargarla. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

Si un valor es incorrecto, no se guarda nada y la página muestra el motivo: un nombre de opción vacío, de más de 64 caracteres o que contiene < > ; = # { }; un orden de visualización que no es un número entero; un peso mínimo superior al máximo; o una clase de impuesto o una zona geográfica no válidas. Los problemas menores se guardan con una nota: un número no válido o negativo deja su campo vacío, un código postal de envío no válido se guarda vacío y un precio no válido de la tabla se ignora.

Encima de los ajustes, la página muestra advertencias: falta la clave 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, o una tienda sin una clase de peso "kg".

General

Cada tipo de entrega es una opción independiente en la finalización de compra. Los ajustes de esta página se aplican a ambas.

PostNL pickup point: activa o desactiva la opción 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 únicamente con una clave API. Por defecto: desactivado.

Pickup point option name: el nombre que ven los clientes en la finalización de compra. Por defecto: PostNL pickup point. Obligatorio, hasta 64 caracteres, sin < > ; = # { }.

PostNL home address: activa o desactiva la opción de entrega a domicilio. No se elige ningún punto. Funciona para todos los países con un precio. Por defecto: desactivado.

Home delivery option name: el nombre que ven los clientes en la finalización de compra. Por defecto: PostNL. Mismas reglas que el nombre del punto de recogida.

Sort order: la posición de PostNL entre los métodos de envío de la finalización de compra. Un número entero.

Tax class: la clase de impuesto de ambas opciones. Con una clase de impuesto, OpenCart añade su impuesto sobre los precios. No tax significa que los precios son definitivos.

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

API key: tu clave 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. Tras guardar, el campo queda vacío y muestra Saved - leave empty to keep it. Escribe un valor nuevo solo para cambiarla.

Remove the saved API key: marca esta casilla y haz clic en Save para eliminar la clave guardada. Entonces ya no se ofrece la opción de punto de recogida.

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

Ship from (country): el país en el que entregas tus paquetes a PostNL: Países Bajos o Bélgica. PostNL usa la dirección del remitente para la fecha de recogida. Al instalar, se ajusta al país de tu tienda si es Países Bajos o Bélgica, y si no, a Países Bajos.

Ship from (postcode): el código postal del remitente, por ejemplo 1234AB en Países Bajos o 1000 en Bélgica. Obligatorio para los puntos de recogida: OpenCart no tiene código postal de tienda, así que no se toma de la dirección de la tienda. Un código postal no válido se guarda vacío con una advertencia.

Al cambiar la clave API, el ajuste de 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 ambas opciones. PostNL no tiene una API pública de tarifas, así que la extensión no solicita tarifas en tiempo real. Para un cliente que paga en otra moneda, OpenCart 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 botón × para eliminarla. 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" y "6,95". Las filas sin precios 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 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 las opciones allí.

Condiciones

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

Minimum subtotal: muestra las opciones solo cuando el subtotal del carrito es al menos este importe. Déjalo vacío para mostrarlas siempre.

Minimum weight (kg): oculta las opciones cuando el carrito pesa menos. Los pesos de los productos se convierten desde su clase de peso. Déjalo vacío para no tener límite.

Maximum weight (kg): oculta las opciones para carritos más pesados. 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, o ningún límite cuando Ignore shipping zones está activado.

Todos los importes y pesos aceptan la coma decimal.

Disponibilidad

Geo zone: ofrece PostNL solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. La zona geográfica no se comprueba cuando Ignore shipping zones está activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.

Ignore shipping zones: cuando está activado, no se comprueba la zona geográfica y PostNL se ofrece para los países seleccionados abajo (todos los países si la lista está vacía). Cuando está desactivado, solo cuenta la zona geográfica.

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 shipping zones está activado. La opción de punto de recogida sigue ofreciéndose solo para Países Bajos y Bélgica.

Avanzado

Debug log: escribe mensajes de depuración en storage/logs/vfd_ptnl_debug.log.php (en OpenCart 4, system/storage/logs/vfd_ptnl_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API y los pedidos sin un punto de recogida válido siempre se registran. No se escribe ninguna clave API ni datos de clientes. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se inicia un registro nuevo.

Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: cuando está activado, al desinstalar la extensión se eliminan los ajustes de PostNL y el registro. Las listas de puntos en caché siempre se eliminan. Los puntos de recogida guardados en los pedidos siempre se conservan.

Importación / Exportación

Exportar: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave API no se exporta.

Importar: 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 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 cada opción de PostNL. Si Ignore shipping zones está activado, PostNL solo se ofrece para un país permitido, sea cual sea la zona geográfica. En caso contrario, si hay una Geo zone definida, la dirección debe estar dentro de ella. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no suman peso y no entran en el subtotal. La extensión comprueba el peso del carrito y el 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, la opción se oculta. Si el subtotal del carrito alcanza Free shipping from, el precio es 0. El precio se muestra al cliente en su moneda, con el impuesto de la Tax class seleccionada.

La opción de punto de recogida solo se ofrece para direcciones de los Países Bajos y Bélgica, y únicamente con clave API. Cuando la dirección de entrega tiene un código postal completo, la extensión pide a la API de Checkout de PostNL los tres puntos de recogida más cercanos. Envía el código postal, la calle y el número de la casa, la ciudad y el país del cliente, y tu dirección de envío. No se envía nada para la opción de entrega a domicilio. Si no se puede conectar con PostNL o no hay puntos para la dirección, la opción de punto de recogida se oculta y la 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 dirección, 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. La caché se guarda en la tabla de base de datos propia de la extensión. El último error se muestra en la página de la extensión hasta la siguiente solicitud correcta.

La extensión no solicita tarifas de PostNL en tiempo real y no crea etiquetas de envío, códigos de barras, seguimiento, devoluciones ni avisos previos. No tiene opciones de entrega por la mañana, por la tarde ni en un día concreto. Crea el envío en Mijn PostNL u otra herramienta de PostNL usando el punto de recogida guardado.

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 una opción de PostNL en la ventana Shipping method options. Los precios son los mismos que en OpenCart 3.

Puntos de recogida

Cuando la dirección de entrega está en los Países Bajos o en Bélgica, aparece una lista de PostNL pickup point debajo de la opción de punto de recogida con los tres puntos más cercanos: nombre de la empresa, dirección y distancia, empezando por el más cercano. La página nunca espera a PostNL: si la lista aún no está en caché, se carga en cuanto se selecciona la opción. Antes de introducir un código postal completo, el cliente ve "Enter your postcode (for example 1234 AB) to see PostNL pickup points." (4 cifras en Bélgica). El punto elegido se guarda para la finalización de compra de inmediato.

El punto es obligatorio. Cuando el cliente hace clic en Continue en el paso de método de envío, el servidor comprueba el punto con la lista de PostNL para la dirección de entrega. Sin punto, el cliente ve "Please choose a PostNL pickup point." Si el punto no figura en la lista, el cliente ve "The chosen PostNL pickup point is not available for this address. Please choose it again." Si no se puede conectar con PostNL, el cliente ve "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method." Nunca se usa para el pedido un punto elegido para otra dirección. El nombre y la dirección guardados con el pedido proceden de PostNL, no del navegador.

Páginas de pedidos, correos electrónicos y factura: el punto se añade al método de envío del pedido, por ejemplo "PostNL pickup point: nombre, dirección" (el nombre de la opción de punto de recogida y, después, el punto) (hasta 128 caracteres, en OpenCart 4 hasta 255). Se muestra en todos los lugares donde OpenCart muestra el método de envío: el historial de pedidos del cliente, los correos electrónicos de pedido, la factura y Sales > Orders.

Página de pedido del administrador: en Sales > Orders, la página del pedido muestra un panel PostNL pickup point encima del historial con el punto, el Location code y el Partner ID. Solo aparece en pedidos con un punto guardado, también después de desactivar la extensión.

En OpenCart 4 la lista de puntos aparece en la ventana Shipping method options, debajo de la opción PostNL pickup point, y se vuelve a cargar cada vez que se abre la ventana, porque la dirección puede cambiar en la finalización de compra de una sola página. El botón Continue de la ventana no continúa sin un punto válido, con los mismos mensajes. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar, y el punto del pedido se actualiza con él.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PostNL es el primer bloque de Extensions > Extensions > Shipping > VibeFox PostNL > 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 eliminar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-postnl y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (se incluyen inglés y ruso).

Si no se acepta la clave, 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 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. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, las opciones de envío de PostNL no se muestran a los clientes en la finalización de compra y no se calcula ningún precio de envío. Un usuario administrador que haya iniciado sesión en el administrador en el mismo navegador sigue viendo las opciones en la tienda, marcadas 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 administrador, así que sin una clave activa las opciones se ocultan a todos. Tras abrir una vez la página Edit, aparece un recordatorio en el Dashboard del administrador. 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 necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del administrador o la página Edit: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por 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

PostNL no aparece en la finalización de compra: comprueba que la licencia está activa y que PostNL pickup point o PostNL home address están activados. Comprueba Geo zone (o que Ignore shipping zones está activado y el país está permitido), que hay un precio definido para el país, los límites de peso y el Minimum subtotal. Comprueba que los productos tienen Requires Shipping en Yes.

La opción de punto de recogida no aparece: solo se muestra para direcciones neerlandesas y belgas, únicamente con clave 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 de la extensión 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 conectar con PostNL, PostNL rechazó la clave API o falta el código postal de envío. La página de la extensión muestra el último error. Una clave de sandbox solo funciona con Sandbox activado, y una clave real 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 de la extensión avisa de que la tienda no tiene una clase de peso "kg", revisa System > Localisation > Weight Classes. Los pesos de los productos se convierten según el nombre de unidad de su clase, y las unidades desconocidas se leen como kg.

La página muestra "Warning: You do not have permission to modify VibeFox PostNL!": tu grupo de usuarios administradores solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_postnl (OpenCart 3) o extension/vfd_postnl/shipping/vfd_postnl (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: la dirección de la API de PostNL puede sustituirse con el ajuste vfd_ptnl_api_url (para pruebas); no tiene campo en la página de configuración.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox PostNL. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre restablece el estado de la extensión, Sort order, Tax class y Geo zone. Las listas de puntos en caché y el último error de la API siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes de PostNL, el registro de depuración y los puntos de las finalizaciones de compra que nunca se convirtieron en pedido. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Los pedidos existentes conservan su método de envío, su coste y el punto de recogida guardado.

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

PostNL es una marca comercial de su respectivo titular. Esta extensión no está afiliada a PostNL ni cuenta con su respaldo.