VibeFox NZ Post for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con la 3.0.5.0) o 4.0.2 y posteriores (probado con la 4.1.0.3).

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 su sitio web. NZ Post te 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 verificación para el lanzamiento. Para las tarifas dentro de Nueva Zelanda también necesitas una cuenta comercial de NZ Post: el número de cuenta y su código de autorización (auth code) o código de sitio (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

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_nz_post-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_nz_post.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 panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_nz_post-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions, elige el tipo de extensión Shipping. Busca VibeFox NZ Post y haz clic en Install (el botón verde +).

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

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

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 (consulta Configuración). Activa Enable NZ Post y haz clic en Save.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_nz_post.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 NZ Post, 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, el método está desactivado hasta que actives Enable NZ Post y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de NZ Post que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox NZ Post > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. Cada guardado también borra las tarifas de NZ Post en caché y los tokens de acceso. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

No se guarda nada y aparece un error cuando Method title está vacío, tiene más de 64 caracteres o contiene < > ; = # { }, cuando un campo numérico contiene texto o un número negativo, cuando la tasa de NZD es 0, cuando Min cart weight (kg) es mayor que Max cart weight (kg), o cuando Sort order no es un número entero. Aparecen avisos encima de los ajustes cuando las tarifas en tiempo real no pueden funcionar con los valores guardados: solo uno de Client ID y Client Secret, sin tasa de conversión a NZD, o datos incompletos para las tarifas nacionales. También aparece un aviso si la tienda no tiene una clase de peso con la unidad kg ni una clase de longitud con la unidad cm: los pesos y las dimensiones se convierten entonces según el nombre de la unidad de su clase (kg, g, lb, oz; cm, mm, m, in), y las demás unidades se leen como kg y cm.

General

Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica, o a países, en Availability.

Enable NZ Post: activa o desactiva el método en la finalización de compra. Por defecto: desactivado.

Method title: el nombre del método de envío que el cliente ve en el carrito y en la finalización de compra. Por defecto: NZ Post. Obligatorio, 64 caracteres como máximo.

Tax class: la clase de impuesto del coste de envío, o No tax (por defecto; el coste de envío no tiene impuestos). Si la tienda añade GST al envío, pon API prices más abajo en Excluding GST para no cobrar el GST dos veces.

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

API de NZ Post (tarifas en tiempo real) (deja el Client ID vacío para usar solo precios fijos)

Environment: Production (api.nzpost.co.nz) (por defecto) 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. Al borrarlo también se borra el Client Secret guardado.

Client Secret: el secreto de cliente OAuth2. Se intercambia por un token de acceso, que se guarda en caché hasta que caduca. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.

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; si lo indicas, NZ Post devuelve tus tarifas contractuales. Al borrarlo también se borra el código de autorización guardado.

Auth code: el código de autorización de la cuenta para las tarifas nacionales. No hace falta si introduces un código de sitio. Como el Client Secret, no se vuelve a mostrar tras guardar.

Site code: la alternativa al auth code: tu código de sitio 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. 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 NZ Post devuelve para el paquete.

API prices: Including GST (por defecto) o Excluding GST. Las tarifas nacionales de NZ Post incluyen el 15 % de GST; el franqueo internacional está exento. Elige Excluding GST cuando el método tenga una clase de impuesto (General), para no cobrar el GST dos veces.

Tasa NZD → (moneda de la tienda): los precios de NZ Post están en NZD. Si la moneda predeterminada de tu tienda no es el NZD, introduce cuántas unidades de tu moneda vale un NZD, por ejemplo 0.55. Sin este valor no se usan las tarifas en tiempo real. La misma tasa convierte el valor del pedido que se envía en las solicitudes internacionales. La tasa debe ser mayor que 0. Si la moneda de tu tienda es el NZD, déjalo vacío.

Paquete para las tarifas en tiempo real

El carrito se envía a NZ Post como un solo paquete. Los pesos y las dimensiones de los productos se convierten de sus clases de peso y longitud a kg y cm (mm en las solicitudes internacionales). El paquete toma la mayor longitud y anchura de los productos, y su altura crece hasta que cabe el volumen de todos los artículos. Los valores de abajo se usan para los productos sin peso o dimensiones.

Default product weight (kg): se usa para cada producto que no tiene peso. Por defecto: 0.5.

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

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

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

Precios fijos (se usan cuando las tarifas en tiempo real no están 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 botón × 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 método en ese caso.

Fixed price per: Order (por defecto) cobra el precio una sola 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 reserva. Las tarifas en tiempo real siempre se calculan para el paquete completo.

Conditions

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

Max cart weight (kg): oculta el método cuando el carrito pesa más. Por defecto: 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 para las direcciones fuera de la Geo zone.

Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.

Free shipping from: el subtotal (después del cupón, antes de impuestos) a partir del cual el envío con NZ Post es gratis. No se envía ninguna solicitud a NZ Post en ese caso. 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.

Availability

Normalmente el método se ofrece en la zona geográfica seleccionada abajo, o en todas partes si no hay ninguna seleccionada.

Geo zone: ofrece NZ Post solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.

Ignore shipping zones: ofrece también NZ Post fuera de la zona geográfica, para los países de abajo. Cuando está activado, solo esos países reciben el método, también dentro de la zona geográfica. Por defecto: desactivado.

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

Avanzado

Debug log: escribe los cálculos de tarifas en storage/logs/vfd_nzpt_debug.log.php (en OpenCart 4, system/storage/logs/vfd_nzpt_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API se registran siempre, incluso con el registro de depuración desactivado. No se registran credenciales, tokens, el número de cuenta ni las direcciones de los clientes. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_nzpt_debug.old.log.php y se inicia un registro nuevo.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar la extensión se borran los ajustes y el registro. Desactivado (por defecto), se conservan para una reinstalación. Las tarifas en caché siempre se borran. Los datos de NZ Post de los pedidos siempre se conservan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El Client Secret y el auth code no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. El Client Secret y el auth code guardados se conservan mientras sigan rellenos su Client ID y su número de cuenta.

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 NZ Post. Si hay una Geo zone configurada y la dirección está fuera de ella, NZ Post solo se ofrece cuando Ignore shipping zones está activado y el país está permitido. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni se incluyen en el importe del pedido. Después la extensión comprueba las condiciones: los países permitidos (con Ignore shipping zones), el peso del carrito y el importe mínimo del pedido. El importe del pedido es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna solicitud a NZ Post. En caso contrario, busca un precio: primero la tarifa en tiempo real de NZ Post, después la tabla de países y después el coste de reserva. Si no hay precio, el método se oculta.

Con las tarifas en tiempo real configuradas, la extensión obtiene un token de acceso con tu Client ID y tu Client Secret y pide a NZ Post un precio. Para una dirección de Nueva Zelanda envía los datos de tu cuenta, la dirección de origen, el barrio, la localidad y el código postal del cliente, y el peso y el tamaño del paquete. OpenCart no tiene campo de barrio: la extensión usa Address 2 cuando contiene el nombre de un barrio (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 la tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada. 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. El token de acceso se conserva hasta que caduca, y un token rechazado se renueva automáticamente.

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

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 NZ Post en la ventana Shipping method options. Las tarifas son las mismas que en OpenCart 3.

La extensión solo calcula tarifas. No crea etiquetas de envío, no genera manifiestos, no reserva recogidas, no hace seguimiento de paquetes, no valida direcciones y no permite al cliente elegir un punto de recogida, un apartado de correos (PO Box) o un locker de paquetes. 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 NZ Post, la extensión guarda en qué se basó el precio de envío. Abre el pedido en Sales > Orders: la página del pedido muestra un panel NZ Post con NZ Post service (el servicio de NZ Post con precio de una tarifa en tiempo real, con su código) y Price source: Live rate (NZ Post ShippingOptions API), Fixed price o Free shipping. El panel muestra los valores del momento del pedido, aunque las tarifas o los ajustes cambien después, y también mientras el método esté desactivado. El cliente no ve el nombre del servicio.

En OpenCart 4, el panel NZ Post se muestra encima de History. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar: el servicio guardado y el origen del precio se actualizan con él. Si el cliente cambia ese pedido a otro método de envío, los datos de NZ Post del pedido se eliminan.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox NZ Post es el primero de la página Extensions > Extensions > Shipping > VibeFox NZ Post > Edit, 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-nz-post 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 el inglés y el 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. 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 método de envío de NZ Post no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el administrador en el mismo navegador sigue viendo el método en la tienda, marcado 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 el método se oculta 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

NZ Post no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable NZ Post esté activado. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso y Minimum order amount. Si NZ Post no devuelve ninguna tarifa, el método solo se muestra con un precio de país o un Fallback cost. Comprueba que los productos tengan Requires Shipping en Yes.

Las tarifas en tiempo real no aparecen: mira los avisos de la parte superior de la página de la extensión. Después activa el Debug log, recarga la finalización de compra y consulta 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 origen, todavía no hay localidad o código postal del cliente, no hay tasa de NZD, o no hay ningún servicio con precio. Mientras corriges el problema se usan los precios fijos.

La solicitud de token falla: revisa 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.

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

Se cobra el GST dos veces en el envío: las tarifas nacionales de NZ Post incluyen el 15 % de GST. Si el método tiene una Tax class, pon API prices en Excluding GST.

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

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

Para desarrolladores: la localidad enviada para una dirección de entrega en Nueva Zelanda se puede cambiar con el evento de OpenCart vfd_nz_post/delivery_suburb (disparador catalog/vfd_nz_post/delivery_suburb). La dirección de la API de NZ Post se puede sustituir con el ajuste vfd_nzpt_api_url (para pruebas); no tiene campo en la página de ajustes.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox NZ Post. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable NZ Post, Sort order, Tax class y Geo zone. Las tarifas en caché y los tokens siempre se eliminan, y el panel NZ Post deja de mostrarse en la página del pedido. Si Remove data on uninstall está activado, también se borran los ajustes de NZ Post y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al reinstalar la extensión. Los datos de NZ Post guardados en los pedidos nunca se borran y vuelven a aparecer tras una reinstalación. Los pedidos existentes conservan su método de envío y su coste.

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 NZ Post en la lista de extensiones instaladas y, después, en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.

NZ Post es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por NZ Post.