VibeFox Australia Post 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 de API PAC de Australia Post (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API Postage Assessment Calculator (PAC) de Australia Post. La clave es gratuita: regístrate para obtener una clave de la API PAC en el Australia Post Developer Centre (developers.auspost.com.au). La página de ajustes enlaza con la página de registro. También necesitas el código postal australiano de 4 dígitos desde el que envías. Si solo usas precios fijos por país, no necesitas clave de API.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_australia_post-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_australia_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_australia_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 y elige el tipo de extensión Shipping. Busca VibeFox Australia 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. 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 (véase Clave de licencia).
5. Elige el origen de las tarifas (Rate source). Para precios fijos, añade filas en Country prices. Para tarifas en tiempo real, introduce la clave de la API PAC, el código postal de origen y, si la moneda predeterminada de tu tienda no es AUD, el tipo de cambio a AUD (véase Configuración). Activa Enable Australia 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_australia_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 Australia 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 los mismos en ambas versiones.
Tras la instalación, el método queda desactivado hasta que actives Enable Australia Post y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Australia Post que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Australia Post > Edit. Las secciones aparecen a la izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas de Australia Post en caché. Solo los administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
Algunos errores impiden guardar, y entonces no se guarda nada: un Method title de más de 64 caracteres, un Sort order que no es un número entero, o una clase de impuesto o zona geográfica desconocida. Otros problemas se muestran como advertencias encima del panel, y el resto de los ajustes se guarda. Un campo numérico con un valor que no es un número o es negativo conserva su valor anterior, y la advertencia indica el campo. Los campos numéricos aceptan el punto o la coma como separador decimal.
Si se elige una fuente de tarifas en tiempo real, pero falta la clave de la API, el código postal de origen de 4 dígitos o el tipo de cambio a AUD, se muestra una advertencia después de guardar. También indica qué ocurre hasta que lo corrijas: el método se oculta en la finalización de compra, o se usan los precios fijos por país en el modo de alternativa. La página también avisa si tu 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 de los productos se convierten entonces según 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 en Conditions, o a una lista de países en Availability without shipping zones.
Enable Australia Post: muestra u oculta Australia Post 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: Australia Post. Como máximo 64 caracteres: un título más largo se rechaza y no se guarda nada. Si el campo está vacío, se muestra una advertencia y se usa Australia Post.
Rate source: cómo se calcula el precio.
Los detalles de los errores van al registro, nunca al cliente.
Sort order: la posición de Australia Post entre los métodos de envío de la finalización de compra. Un número entero.
API de Australia Post (tarifas en tiempo real) (no necesaria para precios fijos)
PAC API key: tu clave gratuita de la API PAC de Australia Post. Se envía a Australia Post en la cabecera AUTH-KEY. 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.
Remove the saved API key: actívalo y guarda para borrar la clave guardada. Entonces las tarifas en tiempo real dejan de funcionar.
Ship-from postcode: el código postal australiano de 4 dígitos desde el que se envían los paquetes, por ejemplo 2000.
Domestic service: se usa para envíos dentro de Australia (hasta 22 kg, 105 cm por lado): Parcel Post (por defecto) o Express Post.
International service: se usa para envíos fuera de Australia (hasta 20 kg): International Standard (por defecto), International Express o International Courier.
Remove GST: divide entre 1,1 los precios nacionales de la API. Los precios nacionales de Australia Post incluyen un 10 % de GST. Actívalo cuando OpenCart añada impuestos al envío por su cuenta (hay una Tax class seleccionada), para que el GST no se cobre dos veces. El envío internacional está libre de GST y nunca se modifica.
AUD → (your currency) rate: la etiqueta muestra la moneda predeterminada de tu tienda. Los precios de Australia Post están en AUD. Si tu moneda predeterminada no es AUD, introduce cuántas unidades de tu moneda vale un AUD, por ejemplo 0,61. El tipo debe ser mayor que 0. Sin él, las tarifas en tiempo real no se usan. Si tu moneda predeterminada es AUD, el campo indica que no hace falta conversión: déjalo vacío.
Paquete para tarifas en tiempo real
El carrito se envía como un único paquete. Los pesos y las dimensiones de los productos se convierten desde sus clases de peso y de longitud de OpenCart a kg y cm. Los valores siguientes se usan para los productos sin peso ni dimensiones.
Default product weight (kg): se usa para cada producto sin peso, en la solicitud a Australia Post y en la comprobación de Min cart weight (kg) / Max cart weight (kg). Por defecto: 1.
Default parcel length (cm): se usa cuando ningún producto del carrito tiene dimensiones. Por defecto: 22.
Default parcel width (cm): se usa cuando ningún producto del carrito tiene dimensiones. Por defecto: 16.
Default parcel height (cm): se usa cuando ningún producto del carrito tiene dimensiones. Por defecto: 8.
Cuando los productos tienen dimensiones, el paquete toma la mayor longitud y anchura entre ellos, y la altura aumenta hasta que el paquete contiene el volumen de todos los artículos.
Precios fijos (se usan con precios fijos y como alternativa de las tarifas en tiempo real)
Country prices: una lista de países y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add row para añadir una fila y en el botón × para quitar una. Elige * All other countries para un precio que se usa en todos los países sin fila propia. Un país sin precio (y sin fila *) no tiene tarifa fija, así que el método se oculta para él. Las filas sin precio se descartan al guardar. La tabla está vacía hasta que añadas precios.
Fixed price per: Order (por defecto) 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. Las tarifas en tiempo real se calculan siempre para el paquete completo.
Condiciones
Min cart weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (por defecto).
Max cart weight (kg): oculta el método por encima de este peso del carrito. Por defecto: 22. 0 significa sin límite, y un campo vacío significa 22 kg. Paquetes de Australia Post: 22 kg nacional, 20 kg internacional. Si Min cart weight (kg) es mayor que el máximo, el método nunca se mostraría: aparece una advertencia y ambos pesos conservan sus valores anteriores.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, sin impuestos, en tu moneda predeterminada) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping: activa el envío gratuito a partir del importe indicado abajo.
Free shipping from: el subtotal de los productos que necesitan envío (después del cupón, sin impuestos) a partir del cual el envío es gratuito. En ese caso no se hace ninguna solicitud a la API. Solo se usa cuando Free shipping está activado.
Tax class: la clase de impuesto del coste del envío, o No tax (por defecto). Los precios nacionales de Australia Post incluyen GST: con una clase de impuesto, activa Remove GST.
Geo zone: ofrece Australia 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. No se usa con Ignore shipping zones.
Disponibilidad sin zonas de envío
Normalmente el método se ofrece en la zona geográfica elegida en Conditions (All zones significa en todas partes).
Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona geográfica.
Countries: los países de destino para ese modo. Escribe para buscar y selecciona varios. Déjalo vacío para permitir todos los países activos de la tienda. Solo se usa con Ignore shipping zones.
Avanzado
Debug log: registra los cálculos de tarifas en storage/logs/vfd_ap.log.php. El archivo no se puede leer desde la web. Los errores de la API siempre se registran. La clave de la API y los códigos postales de los clientes no se registran. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_ap.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, las tarifas en caché y el registro. Si está desactivado (por defecto), se conservan para una reinstalación.
Importar / exportar
Exportar: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de la 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 como en un guardado normal. La clave de la 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 Australia Post. Si hay una Geo zone (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, Australia Post no se ofrece. Con Ignore shipping zones, decide la lista de Countries. Solo cuentan los productos con Requires Shipping ajustado a Yes: los demás productos no suman peso ni se incluyen en el importe del pedido. Después, la extensión comprueba el peso del carrito y el Minimum order amount. 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 envío gratuito, el precio es 0 y no se envía ninguna solicitud a Australia Post.
En el modo de precios fijos, el precio se toma de la tabla. En los modos de tarifas en tiempo real, la extensión envía a Australia Post el peso del paquete y, para entregas dentro de Australia, los códigos postales de origen y de destino y el tamaño del paquete; para envíos internacionales, el país de destino. Una tarifa nacional en tiempo real solo se pide cuando la dirección de entrega tiene un código postal de 4 dígitos. No se envía ninguna solicitud si el paquete supera los límites de Australia Post (22 kg o 105 cm nacional, 20 kg internacional). El precio en AUD se convierte con tu tipo de cambio, y el GST se quita de los precios nacionales si Remove GST está activado. El precio se calcula en tu moneda predeterminada, se redondea a sus decimales y se muestra al cliente en su moneda, con el impuesto de la Tax class seleccionada.
Cada respuesta correcta se guarda en caché durante 1 hora, de modo que el mismo carrito no genera una nueva solicitud. Una solicitud fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a Australia Post en cada actualización. El tiempo de espera de la API es de 10 segundos. Los errores de la API nunca se muestran al cliente: el método se oculta, o se usa el precio fijo en el modo de alternativa. El motivo se escribe en el registro.
La extensión solo calcula tarifas. No crea etiquetas de envío, envíos ni manifiestos de eParcel o MyPost Business, no hace seguimiento de paquetes y no permite que los clientes elijan taquillas automáticas u oficinas de correos. No añade nada a los pedidos: el pedido muestra el nombre del método y el coste del envío como cualquier otro método de envío de OpenCart. El carrito siempre se tarifica como un único paquete. Las cartas, las bolsas y las tarifas por contrato (eParcel) no están incluidas.
En OpenCart 4, el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige Australia Post en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Australia Post es el primero de Extensions > Extensions > Shipping > VibeFox Australia Post > Edit, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, 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-australia-post y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los administradores con permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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 y una fecha. Después de cambiar la dirección de la tienda, o después de liberar un hueco 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 dominio: la dirección de la tienda de la configuración de OpenCart. Quitar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, Australia Post no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), así que puedes 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 panel, así que sin una clave activa el método se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. 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 requieren renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del panel de administración o la página Edit: 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 hace falta ninguna tarea cron. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.
Solución de problemas
Australia Post no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Australia Post esté activado. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso del carrito y Minimum order amount. En el modo de precios fijos, comprueba que el país o * All other countries tenga un precio. Comprueba que los productos tengan Requires Shipping ajustado a Yes.
Las tarifas en tiempo real no aparecen: activa el Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Muestra el motivo: no hay clave de la API ni código postal de origen, aún no hay código postal de destino de 4 dígitos, un paquete que supera los límites, no hay tipo de cambio a AUD, o el mensaje de error de Australia Post. Con Live rates, fixed price if the API gives no rate, los clientes siguen viendo el precio fijo mientras corriges el problema.
Mi tienda no está en AUD: introduce el tipo de cambio (cuántas unidades de tu moneda predeterminada vale un AUD) en el campo AUD → (your currency) rate. Los precios fijos siempre están en tu moneda predeterminada.
El GST se cobra dos veces en el envío: los precios nacionales de Australia Post incluyen un 10 % de GST. Si hay una Tax class seleccionada, activa Remove GST, o pon Tax class en No tax.
El precio es demasiado alto o demasiado bajo: revisa los pesos y las dimensiones de los productos, sus clases de peso y de longitud, y los valores predeterminados de Parcel for live rates. Con Item (price × quantity), los precios fijos se multiplican por el número de artículos.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas de Australia Post en caché.
La página dice "Warning: You do not have permission to modify VibeFox Australia Post!": es posible que el grupo de usuarios de administración solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_australia_post (OpenCart 3) o extension/vfd_australia_post/shipping/vfd_australia_post (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API PAC se puede cambiar con el ajuste vfd_ap_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 Australia Post. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Australia Post, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de Australia Post y el registro también se borran. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensió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 después de desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox Australia Post en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.
Australia Post es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Australia Post.