VibeFox Canada 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.

Canada Post Developer Program (solo para tarifas en tiempo real): las tarifas en tiempo real usan la Canada Post Rating API. Ú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 la forma username:password, y Canada Post entrega claves separadas 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 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_canada_post-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_canada_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 administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_canada_post-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, puedes copiar el contenido de la carpeta upload del paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Canada 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 configuración.

4. Introduce 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 (ver License key).

5. 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 un precio de reserva (ver Configuración). Activa Enable Canada Post y haz clic en Save.

OpenCart 4

1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_canada_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 Shipping. Busca VibeFox Canada Post, haz clic en Install (el botón verde +) y luego 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 está desactivado hasta que actives Enable Canada Post y guardes. Si vuelves a instalar la extensión después de desinstalarla, se vuelven a usar los ajustes que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Canada Post > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas de Canada Post en caché. Solo los usuarios del administrador con el permiso de modificación para esta extensión pueden guardar los ajustes.

Si un valor es incorrecto, la página muestra un error y no se guarda nada: un campo numérico o un precio de 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), un Method title de más de 64 caracteres o con los caracteres < > ; = # { }, un Sort order que no sea un número entero, o una clase de impuesto o una zona geográfica desconocidas. Si la tienda no tiene una clase de peso con la unidad "kg" ni una clase de longitud con la unidad "cm", la página avisa de que los pesos y las dimensiones se convierten según el nombre de la unidad de cada clase (kg, g, lb, oz; cm, mm, m, in), y de que las demás unidades se leen como kg o cm.

Tras guardar, la página muestra un aviso cuando los ajustes no pueden funcionar como se espera: solo se ha rellenado uno de los dos campos, el nombre de usuario o la 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. El aviso también indica qué ocurre mientras tanto: se usan los precios fijos por país, o el método se oculta en la finalización de compra cuando la tabla Country prices está vacía.

General

Los ajustes se aplican a todas las zonas geográficas. El precio siempre procede de esta extensión: una tarifa en tiempo real de Canada Post o los precios fijos por país.

Enable Canada Post: muestra u oculta Canada Post en la finalización de compra. Predeterminado: desactivado.

Method title: el nombre del método de envío que el cliente ve en la finalización de compra. Predeterminado: Canada Post, también si el campo se deja vacío. Como máximo 64 caracteres.

Tax class: la clase de impuesto que OpenCart añade sobre el coste de envío, o No tax (no gravado).

Sort order: la posición de Canada Post entre los métodos de envío en la finalización de compra.

API de Canada Post (tarifas en tiempo real)

Con el nombre de usuario y la contraseña de la API rellenados, el precio procede de la Canada Post Rating API. 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 método 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. Tras guardar, el campo queda vacío y muestra A password is saved. Leave empty to keep it; clear the API username and save to remove both. Escribe un valor nuevo solo si quieres cambiarla. La contraseña se guarda exactamente como se escribe 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 de mostrador (minoristas). Los espacios se eliminan.

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

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

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: el más barato disponible, Regular Parcel (DOM.RP, predeterminado), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) o Priority (DOM.PC).

Service to the USA: el más barato disponible (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: el más barato disponible (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: en direcciones canadienses, el precio de Canada Post incluye estos impuestos. Actívalo cuando OpenCart añada el impuesto del envío por su cuenta (Tax class, 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 vale 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.

Default product weight (kg): se envía a Canada Post por cada producto que no tenga peso. Predeterminado: 0.5. Los pesos y las dimensiones de los productos se convierten a partir de sus clases de peso y de longitud, y el carrito se tarifica como un único paquete (hasta 30 kg).

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 según el peso del carrito, en la moneda predeterminada de tu tienda y 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. La fila * All other countries fija los precios de todos los países que no tengan fila propia. Un país sin fila (y sin *) no tiene precio fijo. Un precio base de 0 significa envío gratuito para ese país.

Fixed price per: Order (predeterminado) 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. Las tarifas en tiempo real siempre se calculan para el paquete completo.

Conditions

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

Max cart weight (kg): oculta el método por encima de este peso del carrito. Predeterminado: 25, también si el campo está vacío. 0 significa sin límite. Los paquetes de Canada Post pueden pesar hasta 30 kg.

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) 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 envía ninguna solicitud a la API. Se usa solo cuando Free shipping está activado.

Geo zone: ofrece Canada Post solo a las direcciones de esta zona geográfica. All zones (predeterminado) significa en todas partes. No se usa cuando Ignore shipping zones está activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.

Disponibilidad sin zonas de envío

Normalmente el método se ofrece en la zona geográfica seleccionada en Conditions.

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. Déjalo vacío para permitir todos los países activados de la tienda. Solo se usa cuando Ignore shipping zones está activado.

Avanzado

Debug log: escribe los cálculos de tarifas en storage/logs/vfd_canada_post.log.php. El archivo no se puede leer desde la web. Cuando llega a 5 MB, se traslada a vfd_canada_post.old.log.php y se inicia un registro nuevo. Los errores de la API siempre se registran, aunque 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.

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 la extensión se borran los ajustes, los servicios guardados de los pedidos, las tarifas en caché y el registro. Si está desactivado (predeterminado), se conservan para una nueva instalación. Los pedidos nunca se tocan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La contraseña de la API no se exporta.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. La contraseña de la API guardada se conserva mientras el nombre de usuario de la API siga rellenado.

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 Canada Post. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, Canada Post no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso y no se incluyen en el importe del pedido. La extensión comprueba primero las condiciones: países permitidos (con Ignore shipping zones activado), peso del carrito e 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 gratuito, el precio es 0 y no se envía ninguna solicitud a Canada Post.

Con credenciales de API, la extensión 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 Estados Unidos el código ZIP, y para el resto de países solo el país. Se solicita una tarifa en tiempo real solo cuando una dirección canadiense o estadounidense tiene un código postal o ZIP válido. Canada Post devuelve todos los servicios del paquete. La extensión elige el servicio seleccionado para el grupo de destino o el más barato, quita los impuestos canadienses si Use Canada Post prices without GST/HST/PST está activado, y convierte el precio de CAD con tu tipo de cambio. 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 se guarda en caché durante 1 hora, para que el mismo carrito y la misma dirección no generen una nueva solicitud. 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 método se oculta si no hay precio fijo. El cliente nunca ve los detalles de los errores de la API; van al registro.

La extensión 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 única tarifa de Canada Post, sin fechas de entrega, seguro ni opciones de firma. El carrito siempre se tarifica como un único paquete, y los tipos de cambio no se actualizan automáticamente.

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 Canada Post en la ventana Shipping method options, por ejemplo Canada Post - $12.50. El método funciona igual que en OpenCart 3.

Pedidos

Cuando se realiza un pedido con Canada Post, la extensión guarda cómo se calculó su precio. En la página del pedido del administrador (Sales > Orders, abre un pedido) aparece un bloque Canada Post que 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.

En OpenCart 4 el bloque se muestra encima de History. La finalización de compra conserva un solo pedido: cuando el cliente vuelve a confirmar el pedido, el servicio y la fuente de precio guardados se sustituyen, y se eliminan si el cliente eligió otro método de envío.

El servicio no se añade a los correos electrónicos de pedido ni a la página de pedidos del cliente; estos muestran el nombre del método y el coste de envío como cualquier otro método de envío de OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Canada Post es el primer bloque de Extensions > Extensions > Shipping > VibeFox Canada Post > Edit, por encima de los ajustes. Introduce 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-canada-post y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios del administrador con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (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 después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, 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. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Canada Post no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario del 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. Después de abrir la página Edit una vez, 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 requieren renovarla. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del administrador 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. Desinstalar la extensión siempre elimina 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. Revisa la Geo zone, o que Ignore shipping zones esté activado y el país permitido. Revisa los límites de peso y el Minimum order amount, y que los productos tengan Requires Shipping en Yes. Debe haber una tarifa: con credenciales de API, la dirección necesita un código postal válido (Canadá) o un código ZIP (Estados Unidos); de lo contrario, debe existir un precio fijo para el país o para *.

Las tarifas en tiempo real no aparecen: activa el Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. 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 obtienen el precio fijo si lo hay.

La tarifa es diferente a la de la web de Canada Post: con un número de cliente obtienes las tarifas comerciales (con descuento) de tu cuenta; sin él, las tarifas de mostrador (minoristas). 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 se cobra dos veces en el envío: activa Use Canada Post prices without GST/HST/PST, o cambia Tax class a 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 de la extensión. Esto borra las tarifas de Canada Post en caché.

La página dice "Warning: You do not have permission to modify VibeFox Canada Post!": es posible que tu grupo de usuarios del administrador solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_canada_post (OpenCart 3) o extension/vfd_canada_post/shipping/vfd_canada_post (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: la dirección de la API de Canada Post se puede cambiar con el ajuste vfd_cp_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 Canada Post. La clave de licencia y el estado de la licencia de esta extensión se eliminan siempre. OpenCart siempre restablece Enable Canada Post, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes, los servicios guardados de los pedidos y el registro. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al instalar la extensión de nuevo. 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 desinstalarla y haz clic en Uninstall (el botón naranja −) junto a VibeFox Canada Post en la lista de extensiones instaladas, y luego en Delete (el botón rojo con la papelera) para eliminar el paquete subido.

Canada Post es una marca comercial de su respectivo propietario. Esta extensión no está afiliada a Canada Post ni cuenta con su respaldo.