VibeFox Canada Post for PrestaShop — Ayuda

Requisitos

PrestaShop: de 8.0 a 9.x.

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

Canada Post Developer Program (solo para tarifas en tiempo real): las tarifas en tiempo real usan la Rating API de Canada Post. Únete al Canada Post Developer Program en el sitio web de Canada Post y copia tu clave de API y tu número de cliente. La clave de API tiene el formato username:password, y Canada Post entrega claves independientes para los entornos de desarrollo (sandbox) y de producción. También necesitas el código postal canadiense desde el que envías. Si solo usas precios fijos, no necesitas claves de 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 subida, haz clic en Configure, o busca más adelante VibeFox Canada 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, introduce el nombre de usuario y la contraseña de la API, tu número de cliente y el código postal de envío. Si la moneda predeterminada de tu tienda no es CAD, introduce el tipo de cambio a CAD. Rellena Country prices si quieres precios fijos o una alternativa (consulta Configuración). Haz clic en Save.

Al instalarse, el módulo crea el transportista Canada Post con el texto del tiempo de tránsito Canada 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 tránsito, el logotipo y los límites de tamaño en Shipping > Carriers. No definas precios allí: el precio siempre viene del módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Canada Post > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Cada guardado también borra las tarifas de Canada Post en caché. Para guardar hace falta el permiso de configuración del módulo.

Si un valor es incorrecto, la página muestra un error y no se guarda nada: un campo numérico o un precio en Country prices que no sea un número igual o mayor que 0 (por ejemplo, -1 o 12abc), un tipo de cambio a CAD de 0, Min cart weight (kg) mayor que Max cart weight (kg), o un Method title de más de 64 caracteres. Si la unidad de peso o de dimensiones de tu tienda es una que el módulo no conoce, la página advierte de que los pesos se leen en kg (las dimensiones, en cm). Configura kg, g, lb u oz (cm, mm, m o in) en International > Localization, sección Local units.

Después de guardar, la página muestra una advertencia cuando la configuración no puede funcionar como se pretende: solo se ha rellenado uno de los campos de nombre de usuario y contraseña de la API; el código postal de envío no es un código postal canadiense (formato A1A 1A1); falta el tipo de cambio a CAD en una tienda con otra moneda; o no hay ni credenciales de API ni precios fijos. La advertencia también indica lo que ocurre mientras tanto: se usan los precios fijos por país, o el transportista se oculta en la finalización de compra cuando la tabla Country prices está vacía.

General

Enable Canada 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 ve el cliente en la finalización de compra. Predeterminado: Canada Post, también cuando el campo se deja vacío. Hasta 64 caracteres, sin los caracteres que PrestaShop no permite en los nombres de transportistas.

Tax: la regla de impuesto que PrestaShop añade sobre el coste de envío, o No tax (no sujeto a impuestos).

Canada Post API (tarifas en tiempo real)

Con el nombre de usuario y la contraseña de la API rellenados, el precio viene de la Rating API de Canada Post. Si la API no devuelve ninguna tarifa (API caída, código postal incorrecto, servicio no disponible), se usa el precio fijo de Country prices, o el transportista se oculta si no hay ninguno. La sección enlaza con el Canada Post Developer Program, donde encontrarás las claves de API y tu número de cliente. Los detalles de los errores van al registro, nunca al cliente.

API username: la parte de la clave de API anterior a los dos puntos. Usa la clave de desarrollo con Sandbox y la clave de producción en una tienda real.

API password: la parte de la clave de API posterior a los dos puntos. Después de guardar, el campo queda vacío y muestra A password is saved. Leave empty to keep it; clear the username and save to remove both. Escribe un valor nuevo solo si quieres cambiarlo. La contraseña se guarda exactamente como la escribes y nunca se escribe en el registro.

Customer number: con un número de cliente, Canada Post devuelve las tarifas comerciales (con descuento) de tu cuenta. Déjalo vacío para las tarifas minoristas (de mostrador). Los espacios se eliminan.

Contract number: opcional, para clientes con contrato. Solo se usa junto con el número de cliente.

Sandbox: usa el entorno de desarrollo de Canada Post, para hacer pruebas con la clave de API de desarrollo. Los precios son datos de prueba. Desactívalo en una tienda real.

Ship-from postal code: el código postal canadiense desde el que se envían los paquetes, por ejemplo K1A 0B1. Las tarifas en tiempo real lo necesitan.

Service in Canada: el servicio para direcciones canadienses: Cheapest available, Regular Parcel (DOM.RP, predeterminado), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) o Priority (DOM.PC).

Service to the USA: Cheapest available (predeterminado), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) o Priority Worldwide parcel USA (USA.PW.PARCEL).

International service: Cheapest available (predeterminado), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) o Priority Worldwide parcel International (INT.PW.PARCEL).

Si el servicio elegido no se ofrece para la dirección o el paquete, se usa el más barato disponible.

Use Canada Post prices without GST/HST/PST: para las direcciones canadienses, el precio de Canada Post incluye estos impuestos. Actívalo cuando PrestaShop añada el impuesto al envío por sí mismo (Tax más arriba), para no cobrar el impuesto dos veces.

CAD to … rate: el nombre del campo muestra la moneda predeterminada de tu tienda, por ejemplo CAD to USD rate. Los precios de Canada Post están en CAD. Si tu moneda predeterminada no es CAD, introduce cuántas unidades de tu moneda equivalen a un CAD, por ejemplo 0.68. Sin este valor no se usan las tarifas en tiempo real. Si tu moneda predeterminada es CAD, déjalo vacío. El tipo de cambio debe ser mayor que 0. Se aceptan tanto el punto como la coma como separador decimal.

Default product weight (kg): se envía a Canada Post para cada producto que no tenga peso. Predeterminado: 0.5. Los pesos de los productos (en la unidad de peso de tu tienda) y las dimensiones se convierten, y el carrito se tarifica como un solo paquete.

Precios fijos (se usan sin credenciales de API y como alternativa cuando la API no devuelve ninguna tarifa)

Country prices: una tabla de países con un precio Base y precios por peso del carrito en la moneda predeterminada de tu tienda, sin impuestos: XS hasta 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL más de 5 kg. Un precio de tamaño vacío o igual a cero usa el precio Base. Haz clic en Add country para añadir una fila y en el icono de cruz para eliminar una. La fila * Default (all other countries) define los precios de todos los países que no tengan fila propia. Un país sin fila (y sin *) no recibe precio fijo. Un precio base de 0 significa envío gratuito para ese país. Una fila sin ningún precio no se guarda.

Fixed price per: Order cobra el precio una sola vez. Item (price x 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 siempre se calculan para el paquete completo.

Condiciones

Min cart weight (kg): oculta el transportista por debajo de este peso del carrito. 0 significa sin límite.

Max cart weight (kg): oculta el transportista por encima de este peso del carrito. Predeterminado: 25, también cuando el campo está vacío. 0 significa sin límite. Los paquetes de Canada Post pueden pesar hasta 30 kg. No puede ser menor que Min cart weight (kg).

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

Free shipping: activa el envío gratuito a partir del importe indicado a continuación.

Free shipping from: el subtotal del carrito a partir del cual el envío es gratuito. En ese caso no se hace ninguna solicitud a la API. Se usa solo cuando Free shipping está activado.

Disponibilidad sin zonas de envío

Normalmente, el transportista se muestra en las zonas a las que está asignado en Shipping > Carriers.

Ignore shipping zones: ofrece el transportista para los países indicados a continuación, sin importar qué zona coincida. Al guardar, el transportista se añade a todas las zonas, y también a las zonas que crees más adelante. Cuando desactivas la opción y guardas, las zonas que añadió el módulo se eliminan de nuevo, y el transportista conserva sus propias zonas.

Countries: los países de destino para ese modo. Mantén pulsada la tecla Ctrl (Cmd) para seleccionar varios. Déjalo vacío para permitir todos los países activos. Este campo se usa solo cuando Ignore shipping zones está activado.

Avanzado

Debug log: registra los cálculos de tarifas en var/logs/vfd_canada_post.log.php. El archivo no se puede abrir desde la web y se archiva al alcanzar 5 MB. Los errores de la API siempre se registran, incluso cuando esta opción está desactivada. Las claves de API, los números de cliente y los códigos postales de los clientes no se registran.

Remove data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes, los servicios guardados de los pedidos, las tarifas en caché y el registro. El transportista siempre se elimina de la finalización de compra al desinstalar. Los pedidos nunca se modifican.

Log: el panel bajo los ajustes muestra el nombre del archivo y las últimas 50 entradas. Haz clic en Clear log para borrarlo.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de Canada Post. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el importe del pedido. Primero el módulo comprueba las condiciones: países permitidos (con Ignore shipping zones), peso del carrito e importe mínimo del pedido. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Canada Post.

Con credenciales de API, el módulo envía a Canada Post el código postal de envío, el destino, el peso del paquete y, cuando todos los productos tienen dimensiones, el tamaño estimado del paquete. Para Canadá el destino es el código postal, para EE. UU. el código ZIP, y para el resto de países solo el país. Una tarifa en tiempo real se solicita solo cuando una dirección canadiense o estadounidense tiene un código postal o ZIP válido. Canada Post devuelve todos los servicios para el paquete. El módulo elige el servicio seleccionado del grupo de destino o el más barato, quita los impuestos de ventas canadienses (GST/HST/PST) si Use Canada Post prices without GST/HST/PST está activado, y convierte el precio en CAD con tu tipo de cambio. El precio se calcula en 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, así que el mismo carrito y la misma dirección no generan una solicitud nueva. Una solicitud fallida se guarda en caché durante 10 minutos, para que una caída de Canada Post no ralentice cada actualización de la finalización de compra. El tiempo de espera de la API es de 10 segundos. Los paquetes de más de 30 kg no se envían a la API.

Si la API no devuelve ninguna tarifa, se usa el precio fijo, o el transportista se oculta cuando no hay precio fijo. El cliente nunca ve los detalles de los errores de la API; estos van al registro.

Si editas el transportista en Shipping > Carriers, 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 envíos, no imprime etiquetas, no crea manifiestos ni devoluciones, y no hace seguimiento de paquetes. Los clientes no pueden elegir una oficina de correos ni un punto de recogida. Muestra una sola tarifa de Canada Post, sin fechas de entrega, opciones de seguro ni de firma. El carrito siempre se tarifica como un solo paquete, y los tipos de cambio de moneda no se actualizan automáticamente.

Pedidos

Cuando se realiza un pedido con el transportista de Canada Post, el módulo guarda cómo se calculó su precio. En la página de pedido del back office (Orders > Orders, abre un pedido) un bloque Canada Post muestra:

Canada Post service: el nombre y el código del servicio de una tarifa en tiempo real, por ejemplo Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API), Fixed price o Free shipping.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Canada Post es el primer bloque de Modules > Module Manager > VibeFox Canada Post > Configure, 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: presta-shipping-canada-post y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso de configuración del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el 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 después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, el transportista de Canada Post no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así 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 es necesario configurar 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

Canada Post no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Canada 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 Minimum order amount. Debe haber una tarifa: con credenciales de API, la dirección necesita un código postal válido (Canadá) o un código ZIP (EE. UU.); si no, debe existir un precio fijo para el país o para *. Además, los productos pueden estar limitados a ciertos transportistas en la página del producto.

Las tarifas en tiempo real no aparecen: activa Debug log, recarga la finalización de compra y mira el panel Log en la página del módulo. Muestra el motivo: falta el nombre de usuario o la contraseña de la API, un código postal de envío o de destino no válido, falta el tipo de cambio a CAD, un paquete de más de 30 kg o el mensaje de error de Canada Post. Mientras tanto, los clientes reciben el precio fijo si hay uno.

La tarifa es distinta a la del sitio web de Canada Post: con un número de cliente obtienes las tarifas comerciales (con descuento) de tu cuenta; sin él, las tarifas minoristas (de mostrador). Para las direcciones canadienses, el precio de Canada Post incluye GST/HST/PST. Los precios se convierten con tu tipo de cambio a CAD.

El impuesto del envío se cobra dos veces: activa Use Canada Post prices without GST/HST/PST, o pon Tax en No tax.

Probar precios en una tienda real: desactiva Sandbox y usa la clave de API de producción.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Así se borran las tarifas de Canada Post en caché.

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

No tienes permiso para configurar este módulo: tu perfil de empleado puede abrir la página del módulo, pero no guardarla. Pide a un administrador que dé a tu perfil el permiso de configuración del módulo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Canada Post y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. El transportista siempre se elimina de la finalización de compra (los pedidos conservan su transportista y su historial). Si Remove data on uninstall está activado, se eliminan los ajustes, los servicios guardados de los pedidos, las tarifas en caché y el registro. Si está desactivado, solo se eliminan las tarifas en caché y se conservan todos los ajustes. Al volver a instalar el módulo (o con Reset), se restaura el transportista anterior con su estado anterior: un transportista que habías desactivado sigue desactivado.

Canada Post es una marca comercial de su respectivo titular. Este módulo no está afiliado a Canada Post ni cuenta con su respaldo.