VibeFox NZ Post for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

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

Acceso a la API de NZ Post (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API ShippingOptions de NZ Post. Solicita el acceso a la API en el Developer Resource Centre de NZ Post, en el sitio web de NZ Post. NZ Post entrega un Client ID y un Client Secret, primero para el entorno de pruebas (UAT) y después para producción, tras su lista de comprobación de puesta en marcha. Para las tarifas dentro de Nueva Zelanda también necesitas una cuenta comercial de NZ Post: el número de cuenta y su auth code o site code. Si solo usas precios fijos, no necesitas acceso a la API.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 carga, haz clic en Configure, o busca más tarde VibeFox NZ Post en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (consulta Clave de licencia).

4. Para las tarifas en tiempo real, rellena la sección NZ Post API (live rates). Opcionalmente, introduce precios fijos, que se usan cuando no hay tarifas en tiempo real y como alternativa (ver Configuración). Haz clic en Save.

Al instalar, el módulo crea el transportista NZ Post con el texto de tiempo de entrega NZ Post parcel delivery. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el tiempo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures 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 NZ Post > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda la página completa. Cada guardado también borra las tarifas de NZ Post en caché y los tokens de acceso.

Encima de los ajustes aparecen advertencias cuando las tarifas en tiempo real no pueden funcionar con los valores guardados: solo uno de Client ID y Client Secret, sin tipo de cambio NZD o datos incompletos para las tarifas nacionales. También aparece una advertencia si el módulo no reconoce la unidad de peso o de dimensiones de la tienda (en ese caso los pesos se toman como kg y las dimensiones como cm). Configura las unidades en International > Localization (Local units). Los campos numéricos deben contener 0 o un número positivo; de lo contrario, la página muestra un error y no se guarda nada.

General

Enable NZ Post: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Method title: el nombre del transportista que se muestra en el carrito y en la finalización de compra. Predeterminado: NZ Post. Obligatorio, 64 caracteres como máximo.

Tax: la regla de impuesto del transportista, o No tax (el coste de envío no tributa). Si la tienda añade GST al envío, configura API prices más abajo en Excluding GST para que el GST no se cobre dos veces.

NZ Post API (live rates) (deja el Client ID vacío para usar solo precios fijos)

Environment: Production (api.nzpost.co.nz) (predeterminado) o Testing / UAT (api.uat.nzpost.co.nz). Usa el entorno para el que se emitió tu Client ID.

Client ID: el client ID de OAuth2 de tu aplicación de la API de NZ Post. Al borrarlo también se borra el Client Secret guardado.

Client Secret: el client secret de OAuth2. Se intercambia por un token de acceso, que se guarda en caché hasta que caduca. 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.

Account number: tu número de cuenta comercial (de facturación) de NZ Post. Obligatorio para las tarifas dentro de Nueva Zelanda. Para las tarifas internacionales es opcional; con él, NZ Post devuelve tus tarifas contractuales. Al borrarlo también se borra el auth code guardado.

Auth code: el código de autorización de la cuenta para las tarifas nacionales. No hace falta si introduces un site code. Como el Client Secret, no se muestra de nuevo después de guardar.

Site code: la alternativa al auth code: tu código de sitio de recogida de NZ Post.

Ship-from suburb: el suburbio (suburb) de la dirección desde la que se envían los paquetes, por ejemplo Petone. Necesario para las tarifas nacionales.

Ship-from city: la localidad o ciudad desde la que se envían los paquetes, por ejemplo Lower Hutt. Necesaria para las tarifas nacionales.

Ship-from postcode: el código postal neozelandés de 4 dígitos desde el que se envían los paquetes, por ejemplo 5012. Necesario para las tarifas nacionales.

Services: códigos de servicio opcionales de NZ Post, separados por comas, por ejemplo CPOLP, ICOU. Solo se calculan estos servicios. Déjalo vacío para usar el servicio más barato que devuelva NZ Post para el paquete.

API prices: Including GST (predeterminado) o Excluding GST. Los precios nacionales de NZ Post incluyen el 15% de GST; el envío internacional tiene tipo cero. Elige Excluding GST cuando el transportista tenga una regla de impuesto (Tax más arriba), para que el GST no se cobre dos veces.

NZD → (shop currency) rate: los precios de NZ Post están en NZD. Si la moneda predeterminada de tu tienda no es NZD, indica cuántas unidades de tu moneda vale un NZD, por ejemplo 0.55. Sin él no se usan las tarifas en tiempo real. El mismo tipo de cambio convierte el valor del pedido que se envía en las solicitudes internacionales. El tipo debe ser mayor que 0. Si la moneda de tu tienda es NZD, déjalo vacío.

Parcel for live rates

El carrito se envía a NZ Post como un solo paquete. Los pesos y las dimensiones de los productos se convierten de las unidades de tu tienda a kg y cm. El paquete toma el mayor largo y ancho de los productos, y su altura crece hasta que cabe el volumen de todos los artículos. Los valores siguientes se usan para los productos sin peso o dimensiones.

Default product weight (kg): se usa para cada producto que no tenga peso. Predeterminado: 0.5.

Default parcel length (cm): se usa cuando ningún producto del carrito tiene dimensiones. Predeterminado: 30.

Default parcel width (cm): se usa cuando ningún producto del carrito tiene dimensiones. Predeterminado: 20.

Default parcel height (cm): se usa cuando ningún producto del carrito tiene dimensiones. Predeterminado: 10.

Fixed prices (se usan cuando no hay tarifas en tiempo real configuradas o NZ Post no devuelve ninguna tarifa)

Los precios están en la moneda predeterminada de la tienda, sin impuestos.

Country prices: una fila por país de destino. Haz clic en Add country para añadir una fila y en el icono de papelera para quitarla. Elige * Default para una fila que cubra todos los demás países. Cada fila tiene un precio Any weight y columnas de peso opcionales: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg y > 5 kg (peso del carrito). Una columna de peso rellena sustituye a Any weight; una columna vacía o con 0 usa Any weight. Un precio Any weight de 0 significa envío gratis a ese país. Se aceptan tanto «9.99» como «9,99». Las filas sin ningún precio y los precios negativos se eliminan al guardar. Solo se conserva una fila por país.

Fallback cost: se usa cuando ni la API ni la tabla de países dan un precio. Déjalo vacío para ocultar el transportista en ese caso.

Fixed price per: Order cobra el precio una vez. Item (price × quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo a los precios fijos y al coste de respaldo. Las tarifas en tiempo real siempre se calculan para el paquete completo.

Conditions

Min cart weight (kg): oculta el transportista cuando el carrito pesa menos. 0 significa sin límite.

Max cart weight (kg): oculta el transportista cuando el carrito pesa más. Predeterminado: 25 (los paquetes de mensajería de NZ Post llegan hasta 25 kg); un campo vacío también significa 25. 0 significa sin límite. Con Ignore shipping zones activado, un campo vacío significa sin límite fuera de las zonas propias del transportista. Si Min cart weight es mayor que Max cart weight, la página muestra un error y no se guarda nada, porque el transportista nunca se mostraría.

Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (productos que necesitan envío, después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.

Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual el envío de NZ Post es gratis. En ese caso no se envía ninguna solicitud a NZ Post. Déjalo vacío para no ofrecer nunca envío gratis.

Para estas condiciones, el peso del carrito cuenta los productos sin peso como 0.

Availability without shipping zones

Normalmente el transportista se muestra en las zonas que tiene asignadas en Shipping > Carriers.

Ignore shipping zones: ofrece NZ Post para los países indicados abajo, sea cual sea la zona que coincida. Al guardar, el transportista se añade a todas las zonas (también a las zonas creadas más tarde). Si desactivas la opción, se quitan de nuevo las zonas añadidas.

Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.

Advanced

Debug log: escribe los cálculos de tarifas en logs/vfd_nzpt_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso con el registro de depuración desactivado. No se registran credenciales, tokens ni direcciones 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, el transportista, las tarifas en caché, los datos guardados de los pedidos y los registros. Si está desactivado, todo se conserva para una reinstalación.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de NZ Post. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el importe del pedido. El módulo comprueba primero las condiciones: países permitidos (con Ignore shipping zones), peso del carrito e importe mínimo del pedido. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna solicitud a NZ Post. Si no, busca un precio: primero la tarifa en tiempo real de NZ Post, después la tabla de países y por último el coste de respaldo. Si no hay precio, el transportista se oculta.

Con las tarifas en tiempo real configuradas, el módulo obtiene un token de acceso con tu Client ID y tu Client Secret y pide a NZ Post un precio. Para una dirección en Nueva Zelanda envía los datos de tu cuenta, la dirección de origen, el suburbio, la localidad y el código postal del cliente, y el peso y el tamaño del paquete. PrestaShop no tiene campo de suburbio: el módulo usa Address line 2 cuando contiene el nombre de un suburbio (sin dígitos); si no, usa la localidad. La tarifa nacional solo se solicita después de que el cliente haya introducido una localidad y un código postal de 4 dígitos. Para otros países envía el país de destino, el peso y el tamaño del paquete y el valor del pedido en NZD.

Se usa el servicio permitido más barato con precio, incluidos los recargos y los complementos obligatorios. El precio se convierte de NZD a la moneda predeterminada de tu tienda y después se muestra en la moneda del carrito del cliente. Cada respuesta se guarda en caché durante 1 hora. Una solicitud fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a NZ Post en cada actualización. El tiempo de espera de la API es de 10 segundos. Un token de acceso caducado se renueva automáticamente.

Si NZ Post no devuelve ninguna tarifa (API no configurada, error, dirección incompleta, servicio no disponible, sin tipo de cambio NZD), el cliente no ve ningún error. Se usa el precio de la tabla de países y, después, el coste de respaldo. Si no hay precio fijo, el transportista se oculta. El motivo se escribe en el registro.

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

El módulo solo calcula tarifas. No crea etiquetas de envío, no reserva recogidas, no genera manifiestos, no hace seguimiento de paquetes, no valida direcciones y no permite a los clientes elegir un punto de recogida, un apartado de correos (PO Box) ni un casillero de paquetes (parcel locker). El carrito se calcula como un solo paquete, y el cliente ve una tarifa de NZ Post, no una lista de servicios.

Pedidos

Cuando se realiza un pedido con el transportista NZ Post, el módulo guarda en qué se basó el precio de envío. La página de pedido del administrador muestra un bloque NZ Post con NZ Post service (el servicio de NZ Post con precio de una tarifa en tiempo real) y Price source: Live rate (NZ Post ShippingOptions API), Fixed price o Free shipping. El bloque muestra los valores del momento del pedido, aunque las tarifas o los ajustes cambien después.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox NZ Post es el primer bloque de Modules > Module Manager > VibeFox NZ Post > Configure, por encima de los ajustes. Introduce 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 aparecen la línea Product: presta-shipping-nz-post 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 tras 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, el transportista NZ Post 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, por lo que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio 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 por semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

NZ Post no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable NZ Post esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o que Ignore shipping zones esté activado y el país esté permitido). Revisa los límites de peso y el Minimum order amount. Si NZ Post no devuelve ninguna tarifa, el transportista solo se muestra con un precio por país o un Fallback cost. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.

Las tarifas en tiempo real no aparecen: mira las advertencias de la parte superior de la página del módulo. Después activa el Debug log, recarga la finalización de compra y mira el campo Log. Los errores de la API siempre aparecen ahí. El registro muestra el motivo: falta el Client ID o el Client Secret, un token rechazado, faltan datos de la cuenta o de la dirección de origen, todavía no hay localidad o código postal del cliente, no hay tipo de cambio NZD o no hay ningún servicio con precio. Mientras corriges el problema se usan los precios fijos.

Falla la solicitud de token: comprueba el Client ID, el Client Secret y el Environment. Las credenciales de UAT no funcionan en producción, y viceversa.

Faltan las tarifas nacionales, pero las internacionales funcionan: las tarifas dentro de Nueva Zelanda necesitan el Account number, el Auth code o el Site code, y la dirección de origen completa con un código postal de 4 dígitos. El cliente debe introducir una localidad y un código postal de 4 dígitos. Los desarrolladores pueden cambiar el suburbio enviado para la dirección de entrega con el hook actionVfdNzptDeliverySuburb.

Mi tienda no usa NZD: introduce el NZD → (shop currency) rate. Los precios fijos siempre están en la moneda predeterminada de la tienda.

El GST se cobra dos veces en el envío: los precios nacionales de NZ Post incluyen el 15% de GST. Si el transportista tiene una regla de impuesto en Tax, configura API prices en Excluding GST.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las tarifas de NZ Post y los tokens en caché.

La página indica que no se encontró el transportista NZ Post: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox NZ Post y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las tarifas y los tokens en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes, los datos guardados de los pedidos y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, o con un Reset, el transportista guardado recupera el estado que tenía antes (activado o desactivado).

NZ Post es una marca registrada de su respectivo propietario. Este módulo no está afiliado a NZ Post ni cuenta con su respaldo.