VibeFox Purolator 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, con la extensión cURL. No se necesita la extensión SOAP de PHP.

Purolator E-Ship Web Services (solo para tarifas en vivo): regístrate en E-Ship Web Services en el Purolator E-Ship Resource Centre del sitio web de Purolator. Purolator entrega claves y contraseñas distintas para los entornos de desarrollo y de producción. También necesitas el número de tu cuenta de facturación de Purolator y el código postal canadiense desde el que envías. Si usas solo precios fijos, no necesitas claves 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_purolator-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_purolator.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_purolator-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no hace falta actualizar Extensions > Modifications. En lugar del Installer, 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 Purolator 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 (ver Clave de licencia).

5. Para tarifas en vivo, completa la sección Purolator API (live rates): clave API, contraseña, número de cuenta de facturación, código postal canadiense de origen y, si la moneda de tu tienda no es CAD, el tipo de cambio a CAD. Para hacer pruebas, activa Development environment con la clave de desarrollo. Completa Country prices o Fallback price si quieres precios fijos o un respaldo (ver Configuración). Activa Enable Purolator y haz clic en Save.

OpenCart 4

1. En el administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_purolator.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 Purolator, 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 Purolator y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Purolator que conservaste.

Configuración

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

Si las tarifas en vivo no pueden funcionar con los valores guardados (falta la clave, la contraseña o la cuenta de facturación, no hay código postal canadiense de origen, no hay tipo de cambio a CAD), o si no hay ni credenciales API ni precios fijos, aparece una advertencia en la sección General. También indica si, mientras tanto, se usan los precios fijos o el método queda oculto. Aparece además una advertencia si la unidad de peso de la tienda no es una que la extensión conoce. En ese caso los pesos de los productos se leen como kg; añade una clase de peso con la unidad kg en System > Localisation > Weight Classes.

Un campo numérico que no contiene un número igual o mayor que 0 no se guarda. Un mensaje tras Save indica el campo y el valor. El campo queda vacío, o toma su valor predeterminado en los campos de peso. Un valor incorrecto en Country prices se guarda como 0, y el mensaje indica el país y la columna. No se guarda nada y aparece un error si el título del método está vacío o tiene más de 64 caracteres, si Min cart weight (kg) es mayor que Max cart weight (kg), si el orden de clasificación no es un número entero, o si la clase de impuesto o la zona geográfica no son válidas.

General

El cliente ve una única tarifa de Purolator. 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 Purolator: muestra u oculta Purolator en la finalización de compra. Por defecto: desactivado.

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

Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Decide si la tienda añade impuestos encima. En direcciones canadienses, el total de Purolator ya incluye GST/HST/PST/QST. Ver más abajo Canadian sales taxes.

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

API de Purolator (tarifas en vivo)

Con la clave API, la contraseña y la cuenta de facturación completadas, el precio procede del servicio web Purolator E-Ship Estimating (Quick Estimate, según el peso total del carrito). Si Purolator no devuelve tarifa, se usa el precio fijo, o el método se oculta cuando no hay ninguno. La sección incluye un enlace al Purolator E-Ship Resource Centre, donde te registras y obtienes las claves. Los detalles de los errores van al registro, nunca al cliente.

API key: tu clave de E-Ship Web Services para el entorno seleccionado. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.

API password: la contraseña que corresponde a la clave. Igual que la clave, no se vuelve a mostrar tras guardar.

Billing account number: tu número de cuenta de Purolator. Las estimaciones usan las tarifas de esta cuenta. El entorno de desarrollo acepta la cuenta de prueba de la documentación de Purolator. Vaciar este campo también elimina la clave API y la contraseña guardadas.

Development environment: usa el entorno de desarrollo de Purolator (devwebservices) con la clave de desarrollo. Los precios son datos de prueba. Desactívalo en una tienda en producción.

Ship-from postal code: el código postal canadiense desde el que se envían los paquetes, por ejemplo L4W 5M8. OpenCart no tiene código postal de tienda, así que no se toma de la dirección de la tienda: introdúcelo aquí.

Service in Canada: Cheapest available (por defecto), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM o Purolator Express Evening.

Service to the USA: Cheapest available (por defecto), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM o Purolator Express U.S. 12:00.

International service: Cheapest available (por defecto), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM o Purolator Express International 12:00.

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

Canadian sales taxes: usa precios de Purolator sin GST/HST/PST/QST. En direcciones canadienses, el total de Purolator incluye estos impuestos. Actívalo cuando la tienda añada impuestos al envío por sí misma (una clase de impuesto en General), para no cobrarlos dos veces. Por defecto: desactivado.

CAD → (store currency) rate: los precios de Purolator están en CAD. Si la moneda predeterminada de tu tienda no es CAD, indica cuántas unidades de tu moneda equivalen a un CAD, por ejemplo 0.68. Sin este valor no se usan las tarifas en vivo. Si tu moneda predeterminada es CAD, déjalo vacío.

Default product weight (kg): se usa en cada producto que no tiene peso. Por defecto: 0.5. Los pesos se convierten desde la clase de peso del producto y se envían a Purolator como peso total en libras enteras, redondeado hacia arriba.

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

Country prices: un precio por país y peso del carrito en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add country para añadir una fila y en el botón × para eliminarla. Elige * Default (all other countries) para una fila que cubra todos los países sin fila propia. Cada fila tiene un precio Base y columnas de tamaño: XS hasta 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg y XL por encima de 5 kg. Un precio de tamaño vacío o cero usa Base. Un Base de 0, o un Base vacío, significa envío gratuito para los pesos sin precio de tamaño propio. Se aceptan tanto 9.99 como 9,99. Las filas sin ningún precio no se guardan, y solo se conserva una fila por país.

Fallback price: el precio para un país que no tiene fila en Country prices ni fila *. Déjalo vacío para ocultar el método en esos países.

Fixed price per: Order (por defecto) cobra el precio una 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 vivo siempre se calculan para el envío completo.

Condiciones

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: 30. Si lo dejas vacío, se usan 30 kg. 0 significa sin límite.

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 de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual la entrega es gratuita. Entonces no se envía ninguna solicitud a Purolator. Déjalo vacío para no ofrecer nunca envío gratuito.

Disponibilidad

Geo zone: ofrece Purolator solo para direcciones en 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 comprueba cuando Ignore shipping zones está activado.

Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona geográfica seleccionada.

Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países habilitados en tu 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_prlr_debug.log.php (en OpenCart 4, system/storage/logs/vfd_prlr_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, incluso con el registro de depuración desactivado. Las claves API, la cuenta de facturación y los códigos postales de los clientes no se registran. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se traslada a vfd_prlr_debug.old.log.php y se inicia un registro nuevo.

Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: cuando está activado, al desinstalar la extensión se eliminan los ajustes de Purolator y el registro. Si está desactivado, se conservan para una reinstalación. Las tarifas en caché siempre se eliminan. El servicio de Purolator de los pedidos realizados siempre se conserva.

Importación / Exportación

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

Import: pega el JSON exportado anteriormente 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 clave API y la contraseña guardadas se conservan.

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 Purolator. Si hay una Geo zone definida y la dirección queda fuera, Purolator no se ofrece (salvo que Ignore shipping zones esté activado). Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni entran en el importe del pedido. La extensión comprueba primero las condiciones: países permitidos (con Ignore shipping zones), 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 fidelidad 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 Purolator. Después busca un precio: primero la tarifa en vivo de Purolator, luego la tabla por país y después el precio de respaldo. Si no hay precio, el método se oculta.

Con credenciales API, la extensión envía a Purolator una solicitud Quick Estimate: tu cuenta de facturación, el código postal de origen, la ciudad, provincia o estado del cliente, el país y el código postal, y el peso total del carrito en libras enteras. Para Canadá se necesita un código postal válido, para Estados Unidos un código ZIP válido; los demás países se envían con el código postal tal como se introdujo. No se envían las dimensiones (peso volumétrico). Purolator responde en francés cuando el cliente ve la tienda en francés, y en inglés en los demás casos. Purolator devuelve los precios de todos los servicios; la extensión toma el servicio elegido o el más barato, quita los impuestos de venta canadienses si está configurado así, y convierte el precio desde CAD. 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, de modo que el mismo carrito no provoca una solicitud nueva. Una solicitud fallida se guarda en caché durante 10 minutos, así que una caída de Purolator no ralentiza cada actualización de la finalización de compra. El tiempo de espera de la API es de 10 segundos.

Si Purolator no devuelve tarifa (API caída, credenciales o código postal incorrectos, servicio no disponible, no hay tipo de cambio a CAD), el cliente no ve ningún error. Se usa el precio fijo, o el método se oculta si no hay precio fijo. El motivo se escribe en el registro.

La extensión solo calcula tarifas. No crea envíos de Purolator, no imprime etiquetas, no reserva recogidas, no gestiona devoluciones ni rastrea paquetes. No usa la Full Estimate (dimensiones, varias piezas, opciones como firma o mercancías peligrosas), no muestra fechas de entrega, no presenta varios servicios como opciones separadas y no obtiene tipos de cambio automáticamente. El cliente no ve el nombre del servicio de Purolator, solo el título de tu método.

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 Purolator en la ventana Shipping method options. El método funciona igual que en OpenCart 3.

Pedidos

Cuando se realiza un pedido con tarifa en vivo de Purolator, el servicio se guarda con el pedido. En Sales > Orders, la página del pedido muestra un panel Purolator encima del historial, con Purolator service (nombre y código) y Live rate (excl. tax). El panel sigue visible aunque el método se desactive después. Los pedidos con precios fijos o con envío gratuito no tienen ese panel. El propio pedido muestra el título del método y el coste de envío como cualquier otro método de envío de OpenCart.

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 de Purolator guardado se actualiza con él a la última tarifa en vivo. Si el pedido cambia a otro método de envío o a un precio sin tarifa en vivo, el servicio guardado se elimina del pedido.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Purolator es el primero en Extensions > Extensions > Shipping > VibeFox Purolator > 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 eliminar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-purolator 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 inglés y 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. Eliminar 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 Purolator 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

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

Las tarifas en vivo no aparecen: mira el campo Log en la página de la extensión. Los errores de la API siempre aparecen ahí. Activa el Debug log y recarga la finalización de compra para ver detalles. Con claves API, la dirección debe tener un código postal válido (Canadá) o un código ZIP válido (Estados Unidos). Revisa también las advertencias de la sección General.

HTTP 401 en el registro: la clave API o la contraseña no coinciden con el entorno seleccionado. Las claves de desarrollo solo funcionan con Development environment activado, y las de producción solo con él desactivado.

La tarifa no coincide con la web de Purolator: la Quick Estimate usa las tarifas de tu cuenta de facturación y el peso total redondeado hacia arriba a libras enteras, sin peso volumétrico. En direcciones canadienses el total incluye impuestos de venta; usa Canadian sales taxes si has configurado una Tax class. Los precios se convierten con tu CAD → (store currency) rate.

Un valor desapareció tras guardar: lee el mensaje que aparece después de Save. El valor no era un número igual o mayor que 0, así que no se guardó. Introdúcelo de nuevo como número simple.

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

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

Para desarrolladores: la dirección de la API de Purolator se puede cambiar con el ajuste vfd_prlr_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 Purolator. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Purolator, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes de Purolator y el registro de depuración. 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, y los servicios de Purolator guardados en los pedidos siempre se conservan.

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

Purolator es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Purolator.