VibeFox NZ Post for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

WooCommerce: 5.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

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 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_nz_post a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Shipping > VibeFox NZ Post, 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. Para las tarifas en tiempo real, rellena la sección NZ Post API (live rates). Opcionalmente, introduce precios fijos, que se usan sin tarifas en tiempo real y como alternativa (ver Configuración).

6. Añade VibeFox NZ Post a una zona de envío en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones y elige los países.

Configuración

Todos los ajustes están en una misma página: WooCommerce > Settings > Shipping > VibeFox NZ Post. Se aplican a todas las zonas de envío. Cuando añades el método a una zona, la ventana de la zona tiene un único campo:

Title (zone): el nombre que ven los clientes para esta zona. Déjalo vacío para usar el Method title general.

Cada vez que guardas los ajustes, se borran las tarifas de NZ Post en caché y los tokens de acceso. Si 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, datos incompletos para las tarifas nacionales), aparece una advertencia encima de los ajustes.

General

Enable/Disable: activa o desactiva el método en todas las zonas a la vez.

Method title: el nombre del método de envío que se muestra en el carrito y en la finalización de compra. Una zona puede cambiarlo. Predeterminado: NZ Post.

Tax status: Taxable añade el impuesto de WooCommerce al coste del envío; None no lo añade. Consulta también API prices más abajo.

NZ Post API (tarifas en tiempo real) (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 ID de cliente OAuth2 de tu aplicación de la API de NZ Post.

Client Secret: el secreto de cliente OAuth2. Se intercambia por un token de acceso, que se guarda en caché hasta que caduca.

Account number: el número de tu cuenta comercial (de facturación) de NZ Post. Es obligatorio para las tarifas dentro de Nueva Zelanda. Para las tarifas internacionales es opcional; con él, NZ Post devuelve tus tarifas contractuales.

Auth code: el código de autenticación de la cuenta para las tarifas nacionales. No es necesario si introduces un site code.

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

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

Ship-from city: la localidad o ciudad desde la que se envían los paquetes, por ejemplo Lower Hutt. Es 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. Es 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 Tax status sea Taxable, para no cobrar el GST dos veces.

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

Paquete para las tarifas en tiempo real

El carrito se envía a NZ Post como un único paquete. Los pesos y las dimensiones de los productos se convierten de las unidades de tu tienda a kg y cm. El paquete toma la mayor longitud y anchura de los productos, y su altura crece hasta caber el volumen de todos los artículos. Los valores siguientes se usan para los productos sin peso ni 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.

Precios fijos (se usan cuando no están configuradas las tarifas en tiempo real o NZ Post no devuelve ninguna tarifa)

Los precios están en la moneda de la tienda.

Country prices: una fila por país de destino. Haz clic en + Add country para añadir una fila y en la cruz 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, los códigos de país no válidos 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 método 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 todo el paquete.

Condiciones

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

Max cart weight (kg): oculta el método cuando el carrito pesa más. Predeterminado: 25 (los paquetes de mensajería de NZ Post pesan hasta 25 kg). 0 significa sin límite.

Minimum order amount: muestra el método solo cuando el subtotal del carrito alcanza este importe. Déjalo vacío para mostrarlo siempre.

Excluded shipping classes: oculta el método cuando el carrito contiene un producto de cualquiera de estas clases de envío de WooCommerce.

Free shipping from: el subtotal del carrito a partir del cual el envío con NZ Post es gratis. Se aplica solo cuando el método tiene un precio: un precio por país o el coste de respaldo (entonces no se envía ninguna solicitud a NZ Post), o una tarifa en tiempo real. Déjalo vacío para no ofrecer nunca envío gratis.

El peso del carrito para estas condiciones cuenta los productos sin peso como 0.

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece NZ Post para los países indicados abajo, aunque el método no se haya añadido a ninguna zona de envío.

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

Avanzado

Debug log: escribe los cálculos de tarifas en WooCommerce > Status > Logs (origen "vfd-nz-post"). 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.

Remove data on uninstall: si está activado, al eliminar el plugin se borran sus ajustes, los métodos de las zonas y las tarifas en caché. Desactivar el plugin nunca borra nada.

Cómo funciona en la finalización de compra

Cuando el cliente introduce una dirección de entrega, WooCommerce pide al plugin una tarifa. Primero el plugin comprueba las condiciones: país de entrega, peso del carrito, importe mínimo del pedido y clases de envío excluidas. Luego busca un precio: 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 método se oculta. Si se aplica el envío gratis, el cliente ve el método sin coste.

Con las tarifas en tiempo real configuradas, el plugin 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 barrio, la ciudad y el código postal del cliente, así como el peso y el tamaño del paquete. WooCommerce no tiene campo de barrio: el plugin usa Address line 2 cuando contiene el nombre de un barrio; si no, usa la localidad o la ciudad. Una tarifa nacional se solicita solo cuando el cliente ha introducido una ciudad 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 importe del pedido en NZD.

Se usa el servicio más barato permitido que tenga precio, incluidos los recargos y los complementos obligatorios. El precio se convierte de NZD a la moneda de tu tienda. El servicio con precio se guarda con el pedido como NZ Post service y se ve en la pantalla del pedido. 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 sin configurar, 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 método se oculta. El motivo se escribe en el registro.

El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con WooCommerce High-Performance Order Storage (HPOS).

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

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox NZ Post. 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 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, NZ Post no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión lo siguen viendo, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un aviso 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 requieren renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

NZ Post 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 shipping zones esté activado y el país permitido). Revisa los límites de peso, Minimum order amount y Excluded shipping classes. Si NZ Post no devuelve ninguna tarifa, el método solo se muestra con un precio por país o con un Fallback cost.

Las tarifas en tiempo real no aparecen: abre WooCommerce > Status > Logs, origen "vfd-nz-post". Los errores de la API siempre están ahí. Activa Debug log para ver los detalles. 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, el cliente aún no ha indicado ciudad o código postal, 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, ni al revés.

Faltan las tarifas nacionales, pero las internacionales funcionan: las tarifas dentro de Nueva Zelanda requieren 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 ciudad y un código postal de 4 dígitos. Los desarrolladores pueden cambiar el barrio enviado para la dirección de entrega con el filtro vfd_nzpt_delivery_suburb.

Mi tienda no usa NZD: introduce el NZD → (store currency) rate. Los precios fijos siempre están en la moneda 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 Tax status es Taxable, pon API prices en Excluding GST.

Las tarifas parecen desactualizadas tras un cambio: guarda la página de ajustes. Así se borran las tarifas de NZ Post y los tokens en caché.

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 conserva todos los datos. 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. Los ajustes, los métodos de zona, las tarifas en caché y los tokens de acceso 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.

NZ Post es una marca comercial de su propietario. Este plugin no está afiliado ni respaldado por NZ Post.