VibeFox USPS for OpenCart — Ayuda

Requisitos

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

PHP: 8.0 o posterior, con la extensión cURL.

Aplicación del Portal para desarrolladores de USPS (solo para tarifas en tiempo real): inicia sesión en el Portal para desarrolladores de USPS (developers.usps.com) con una cuenta empresarial gratuita de USPS, crea una aplicación y copia su Consumer Key y su Consumer Secret. La extensión usa las API actuales de USPS con OAuth 2.0. El antiguo Web Tools User ID no funciona con ellas. Sin claves, solo se usan los precios fijos.

Código postal de origen: las tarifas en tiempo real necesitan el código postal de EE. UU. de 5 dígitos desde el que se envían los paquetes.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

La descarga es un archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_usps-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_usps.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_usps-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 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 USPS 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 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. Introduce el Consumer Key y el Consumer Secret, el Ship from ZIP code de 5 dígitos y elige los Services. Si la moneda predeterminada de tu tienda no es USD, introduce el USD exchange rate.

6. Opcionalmente, introduce precios fijos como alternativa, activa Enable USPS shipping 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_usps.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 USPS, 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 a 6 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 USPS shipping y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de USPS que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox USPS > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. Cada guardado borra el token y las tarifas de USPS en caché. Solo los administradores con permiso de modificación para esta extensión pueden guardar los ajustes, borrar la caché o borrar el registro.

Un valor no válido no se guarda: la página indica el campo, restaura el valor anterior y muestra The other settings were saved. Esto se aplica a un nombre vacío, demasiado largo o con caracteres prohibidos, un número negativo o no numérico, un código postal que no tiene 5 dígitos, un tamaño de caja incorrecto, un Min weight (kg) superior a Max weight (kg) (ambos límites conservan sus valores), un orden de clasificación que no es un número entero, y una clase de impuesto o una zona geográfica desconocidas. Los precios por país que no son números se borran y aparecen en una lista. Las advertencias encima de los ajustes te indican cuando solo una de las dos claves está configurada, cuando no hay claves ni precios fijos (entonces el método nunca se muestra), cuando falta el código postal, cuando no hay ningún servicio seleccionado, cuando falta el tipo de cambio en USD, cuando el entorno de prueba está activado o cuando la extensión no reconoce la unidad de peso o de longitud de la tienda.

General

Los ajustes se aplican a todas las zonas geográficas. USPS se ofrece como una opción de envío en la finalización de compra.

Enable USPS shipping: ofrece el envío por USPS en la finalización de compra. Predeterminado: desactivado.

Name: el nombre del método de envío que ve el cliente en la finalización de compra. Predeterminado: USPS. Obligatorio, máximo 64 caracteres, sin < > ; = # { }.

Tax class: la clase de impuesto del coste de envío. Las tarifas de USPS no incluyen impuestos. No tax (predeterminado) significa que el envío no tiene impuestos.

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

API de USPS (tarifas en tiempo real)

Consumer Key: el Consumer Key (client_id) de tu aplicación de desarrollador de USPS. Borrarlo también elimina el Consumer Secret guardado.

Consumer Secret: el Consumer Secret (client_secret) de la misma aplicación. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Clearing the Consumer Key removes it too. Escribe un valor nuevo solo si quieres cambiarlo.

Test environment: usa el Testing Environment de USPS para remitentes. Solo para aplicaciones que tengan acceso a él. Déjalo desactivado para obtener precios reales. Predeterminado: desactivado.

Prices: qué lista de precios de USPS se usa.

Services: los servicios de USPS que pueden cotizarse. Se muestra el servicio seleccionado más barato que USPS ofrece para el paquete. Elige entre USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) y Library Mail (libraries and schools only). Predeterminado: Ground Advantage, Priority Mail y First-Class Package International. Las tarifas Flat Rate, Cubic, Hold for Pickup y Sunday nunca se usan. Si no hay ningún servicio seleccionado, no se usan tarifas en tiempo real.

USD exchange rate: las tarifas de USPS están en USD. Si la moneda predeterminada de tu tienda no es USD, introduce el precio de 1 USD en tu moneda, por ejemplo 0.92. Debe ser mayor que 0. Sin él, no se usan tarifas en tiempo real y se aplican los precios fijos. Si la moneda de tu tienda es USD, no hace falta. El tipo de cambio no se actualiza automáticamente.

Cache: las cotizaciones se guardan en caché durante 1 hora y una cotización fallida durante 10 minutos. Tras un tiempo de espera, error del servidor, límite de solicitudes o claves rechazadas, no se llama a USPS durante 5 minutos. Haz clic en Clear cached USPS token and rates para vaciar la caché de inmediato.

Origen y paquete (las tarifas de USPS dependen del código postal de origen, el peso y el tamaño del paquete; el carrito se cotiza como un solo paquete)

Ship from ZIP code: el código postal de EE. UU. de 5 dígitos desde el que se envían los paquetes. El ZIP+4 se recorta a 5 dígitos. OpenCart no tiene código postal de tienda, así que introdúcelo aquí.

Box size (L x W x H): dimensiones opcionales de la caja en la unidad de longitud de tu tienda (que aparece en el nombre del campo), por ejemplo 30x20x15. Déjalo vacío para usar las dimensiones del producto: la longitud más larga, la anchura más ancha y las alturas apiladas. Los productos sin dimensiones se cotizan como una caja de 10 x 8 x 4 pulgadas.

Default product weight (kg): el peso usado para los productos sin peso, en las tarifas de USPS, los límites de peso y los tramos de peso. Predeterminado: 0.5. Vacío también significa 0,5 kg.

Precios fijos (precios en la moneda predeterminada de tu tienda, sin impuestos; se usan cuando no se introduce ninguna clave de API y como alternativa cuando USPS no devuelve ninguna tarifa; deja ambos vacíos para ocultar el método en ese caso)

Country prices: precios según el país de destino y el peso del carrito. Haz clic en Add country para añadir una fila y en el botón de eliminar para borrar una. Los tramos de peso son XS hasta 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg y XL por encima de 5 kg. Un tramo vacío o 0 usa Price. * Default (any other country) se aplica a todos los demás países.

Fallback cost: un precio fijo cuando no coincide ningún precio por país. Déjalo vacío para ocultar el método en ese caso.

Fixed price is: Per order (predeterminado) cobra el precio una sola vez, según el peso de todo el carrito. Per item (each item priced by its own weight x quantity) fija el precio de cada producto según su propio peso y lo multiplica por su cantidad. Las tarifas en tiempo real de USPS siempre se cotizan para el paquete completo.

Condiciones

Free shipping from: el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) a partir del cual este método es gratuito. En ese caso no se envía ninguna solicitud a USPS. Déjalo vacío para no ofrecer nunca envío gratuito.

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

Min weight (kg): el peso mínimo del carrito para que aparezca este método. 0 significa sin límite (predeterminado).

Max weight (kg): el método se oculta por encima de este peso del carrito. Predeterminado: 30. Vacío significa 30 kg, 0 significa sin límite. USPS acepta hasta 70 lb (31,7 kg): los paquetes más pesados reciben los precios fijos.

Geo zone: ofrece USPS solo para direcciones de esta zona geográfica. All zones (predeterminado) 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

Ignore shipping zones: no comprueba la zona geográfica. El método se ofrece para los países indicados a continuación.

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

Avanzado

Debug log: registra las solicitudes a la API y el cálculo de tarifas en storage/logs/vfd_usps_debug.log.php (en OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, aunque esta opción esté desactivada. Las claves, los tokens, los códigos postales y las direcciones de los clientes nunca se registran. Cuando el archivo alcanza 5 MB, se mueve a vfd_usps_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 de USPS y el registro. Las tarifas en caché siempre se eliminan. Los servicios de USPS de los pedidos realizados siempre se conservan. Si está desactivado, los ajustes se mantienen para una reinstalación.

Importación / Exportación

Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. El Consumer Secret no se exporta.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. Se conserva el Consumer Secret guardado.

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 USPS. Si hay una Geo zone configurada y la dirección está fuera de ella, no se ofrece USPS (con Ignore shipping zones, decide en su lugar la lista de países). Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso y no se incluyen en el subtotal. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Después, la extensión comprueba las condiciones: peso del carrito y subtotal mínimo. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a USPS.

La extensión obtiene un token OAuth de USPS y lo conserva hasta poco antes de que caduque. Para destinos en EE. UU. y sus territorios (Puerto Rico, las Islas Vírgenes de EE. UU., Guam, Samoa Americana, las Islas Marianas del Norte, los Estados Federados de Micronesia, las Islas Marshall y Palaos) solicita las tarifas nacionales y necesita el código postal de 5 dígitos del cliente: sin él, no hay solicitud. Para los demás países solicita las tarifas internacionales.

La solicitud contiene el código postal de origen, el peso del carrito, el tamaño del paquete y el tipo de precio. Los paquetes de más de 70 lb reciben los precios fijos. El cliente ve una sola opción con el servicio seleccionado más barato. El precio en USD se convierte a tu moneda predeterminada, se redondea a sus decimales y se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada.

Cada cotización se guarda en caché durante 1 hora. Una cotización fallida se recuerda durante 10 minutos. Tras un tiempo de espera, error del servidor, límite de solicitudes o claves rechazadas, no se llama a USPS durante 5 minutos. El tiempo de espera HTTP es de 10 segundos.

Si USPS no devuelve ninguna tarifa, el precio sale de Country prices y, después, de Fallback cost. Si ninguno aplica, el método se oculta. El cliente nunca ve los textos de error de USPS. El motivo se escribe en el registro de depuración.

La extensión solo calcula tarifas. No compra franqueo ni etiquetas de envío, no reserva recogidas, no hace seguimiento de paquetes ni permite al cliente elegir una oficina de correos o un punto de recogida. Muestra una sola opción, no varios servicios de USPS. No hay empaquetado de cajas: el carrito se cotiza como un solo paquete. El seguro y otros servicios adicionales no están incluidos.

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

Pedidos

Cuando se realiza un pedido con USPS, la extensión guarda cómo se obtuvo el precio del envío. La página del pedido en Sales > Orders muestra un panel de USPS con el USPS service (para una tarifa en tiempo real, por ejemplo USPS Ground Advantage), la Price source (USPS live rate, Fixed price o Free shipping) y el Calculated price (excl. tax). Estos valores se guardan cuando se realiza el pedido.

OpenCart 4 mantiene un solo pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar. Los valores guardados se actualizan con él. Si el cliente cambia a otro método de envío, se eliminan del pedido. En OpenCart 4 el panel USPS se muestra encima de la sección History.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox USPS es el primer bloque de Extensions > Extensions > Shipping > VibeFox USPS > Edit, encima de los ajustes. Introduce 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-usps 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 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 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, USPS 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 panel 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 para 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 necesitan una renovación. 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 a la semana. No se necesita ninguna tarea cron. Al desinstalar la extensión siempre se elimina la clave de licencia y el estado de la licencia.

Solución de problemas

USPS no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable USPS shipping esté activado. Revisa la Geo zone, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y el Minimum subtotal. Sin claves de USPS que funcionen, el método necesita un precio fijo (Country prices o Fallback cost). Comprueba que los productos tengan Requires Shipping en Yes.

Las tarifas en tiempo real no aparecen: revisa las advertencias en la parte superior de la página Edit: ambas claves, el código postal, al menos un servicio y, para tiendas que no usan USD, el tipo de cambio. Los clientes de EE. UU. deben introducir un código postal. Activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión.

Las tarifas no son precios reales: desactiva Test environment.

La página avisa sobre la unidad de peso o de longitud: sin una clase de peso con la unidad kg, las unidades de peso desconocidas se leen como kg. Añade una clase de peso en kg en System > Localisation > Weight Classes. Una unidad de longitud desconocida de la tienda se trata como cm. Usa cm, mm, m o in como clase de longitud de la tienda (System > Settings, pestaña Option).

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión o en Clear cached USPS token and rates.

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

Para desarrolladores: la dirección de la API de USPS se puede reemplazar con el ajuste vfd_usps_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 USPS. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable USPS shipping, Sort order, Tax class y Geo zone. El token y las tarifas de USPS en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de USPS y el registro de depuración. Si está desactivado, se conservan los demás ajustes y se usan de nuevo cuando vuelvas a instalar la extensión. Los datos de USPS de los pedidos realizados nunca se eliminan, y 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 USPS en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

USPS es una marca registrada de su titular. Esta extensión no está afiliada ni respaldada por USPS.