VibeFox Shippo for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

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

Cuenta de Shippo: crea una cuenta de Shippo, conecta o activa los transportistas (USPS, UPS, FedEx, DHL y otros) y copia el token de API desde Shippo > Settings > Advanced > API. Shippo cobra las etiquetas compradas, no las solicitudes de tarifas. Las cuentas nuevas de Shippo pueden necesitar verificación por parte de Shippo antes de que se devuelvan tarifas en tiempo real. Sin token, solo se usan los precios de respaldo.

Productos: los productos deben tener peso y dimensiones. Los productos sin dimensiones usan el tamaño de caja predeterminado.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 VibeFox Shippo más tarde 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 (véase Clave de licencia).

4. Pega tu token de API de Shippo y completa la dirección de Ship from. El código postal es obligatorio para las tarifas en tiempo real.

5. Elige la Shippo rate currency (USD si envías desde EE. UU.) y, si la moneda predeterminada de tu tienda es diferente, introduce el Exchange rate.

6. Opcionalmente, introduce precios de respaldo en la tabla de países y peso, y luego haz clic en Save.

Al instalar, el módulo crea el transportista Shippo Shipping con el texto de tiempo de entrega Shippo carriers (USPS, UPS, FedEx, DHL). El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar zonas, grupos de clientes, tiempo de entrega, logotipo y límites de tamaño en Shipping > Carriers. No establezcas 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 Shippo > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de Shippo en caché.

Las advertencias de la parte superior de la página indican cuándo el transportista nunca se mostrará o cuándo las tarifas en tiempo real no se pueden usar: falta el token de API, falta el código postal o el país de origen, falta el tipo de cambio, o la unidad de peso o de dimensiones de la tienda no es una que el módulo conozca (usa kg, g, lb u oz y cm, mm, m o in en International > Localization, Local units). Un aviso te recuerda cuando hay configurado un token de prueba. Al guardar, un valor que no es un número, un número negativo, o un Minimum weight (kg) mayor que Maximum weight (kg), se notifica como error y no se guarda nada hasta que lo corrijas.

General

Enable Shippo shipping: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Name: el nombre del transportista que ve el cliente en la finalización de compra. Predeterminado: Shippo Shipping. Obligatorio, máximo 64 caracteres.

Tax: la regla de impuestos del transportista, o No tax. Las tarifas de Shippo no incluyen impuesto sobre las ventas. No tax las muestra tal como se cotizan; una regla de impuestos añade impuesto al envío según tus reglas fiscales.

Cuenta de Shippo

API token: tu token de API de Shippo. Usa el token real (shippo_live_...) para tarifas reales en la tienda en producción, o un token de prueba (shippo_test_...) para las tarifas de prueba de Shippo. El token solo se envía a Shippo y nunca se registra. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo, o marca Remove the saved API token para eliminarlo.

Allowed carriers / services: opcional, separados por comas. Escribe un transportista tal como lo nombra Shippo (USPS, UPS, FedEx, DHL Express) o un token de nivel de servicio de Shippo (usps_priority, ups_ground). Se muestra la tarifa permitida más barata. Déjalo vacío para mostrar la tarifa más barata de cualquier transportista.

Origen del envío (la dirección desde la que se envían tus paquetes; los campos vacíos se toman de la dirección de la tienda en Shop Parameters > Contact > Stores cuando está en el mismo país)

Sender name / company: el nombre del remitente. También se usa para firmar la declaración aduanera. Si está vacío, se usa el nombre de la tienda.

Street address: la calle del remitente.

City: la ciudad del remitente.

State / province: el código de estado de dos letras, por ejemplo CA o NY. Algunos transportistas lo necesitan.

Postal / ZIP code: obligatorio para las tarifas en tiempo real.

Country: el país desde el que envías. Predeterminado: Estados Unidos.

Tarifas

Parcels: cómo se envía el carrito a Shippo.

Default box size: largo x ancho x alto en la unidad de dimensiones de tu tienda (que se muestra en el nombre del campo), por ejemplo 30 x 20 x 10. Shippo necesita el tamaño de la caja. Se usa cuando un producto del carrito no tiene dimensiones. Déjalo vacío para usar 30 x 20 x 10 cm. Un valor que no se puede leer se ignora con un aviso después de guardar.

Shippo rate currency: la moneda en la que Shippo cotiza a tus transportistas, que es la moneda del país de origen: USD (EE. UU.), CAD (Canadá), GBP (Reino Unido), EUR (eurozona) o AUD (Australia). Predeterminado: USD. Las tarifas que Shippo devuelve en la moneda predeterminada de tu tienda siempre se usan tal como son.

Exchange rate: el precio de 1 unidad de la moneda de tarifas de Shippo, expresado en la moneda predeterminada de tu tienda, por ejemplo 0.92. No hace falta cuando ambas monedas son iguales. Sin él, las tarifas en la otra moneda no se usan y se aplican los precios de respaldo. El módulo no convierte monedas automáticamente.

Precios de respaldo (se usan cuando no hay tarifa en tiempo real: sin token de API, Shippo inaccesible, token rechazado o sin tarifas de transportistas para la dirección; precios en la moneda predeterminada de tu tienda, sin impuestos; deja ambos vacíos para ocultar el transportista en ese caso)

Country prices: una tabla de precios por país y peso del carrito. Haz clic en Add country para añadir una fila y en el icono de papelera para quitar una. Las columnas son Price y los tramos de peso XS (hasta 1 kg), S (hasta 2 kg), M (hasta 3 kg), L (hasta 5 kg) y XL (más de 5 kg). Un tramo vacío o 0 usa la columna Price. La fila * Default se aplica a los países sin fila propia. Una fila nueva empieza como * Default. Una fila guardada con todas las celdas vacías cobra 0, así que elimina las filas que no vayas a rellenar.

Other countries: el precio de los países que no están en la tabla anterior (cuando no hay fila * Default). Déjalo vacío para ocultar el transportista en esos países.

Condiciones

Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual el envío es gratis. En ese caso no se hace ninguna solicitud a Shippo. Déjalo vacío para desactivarlo.

Minimum subtotal: muestra el transportista solo si el subtotal del carrito (después de descuentos, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.

Minimum weight (kg): el peso mínimo del carrito para mostrar el transportista. 0 significa sin límite.

Maximum weight (kg): el transportista se oculta por encima de este peso del carrito. Predeterminado: 30. 0 significa sin límite. Un campo vacío se guarda como 30.

Disponibilidad sin zonas de envío

Normalmente el transportista se ofrece en sus zonas de envío en Shipping > Carriers. Alternativamente, se puede ofrecer por país, independientemente de las zonas.

Ignore shipping zones: ofrece el transportista para los países de abajo, tenga o no asignada su zona. Mientras esté activado, el transportista se añade a todas las zonas, incluidas las zonas creadas más adelante. Al desactivarlo, se eliminan esas zonas añadidas y el transportista conserva sus propias zonas.

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

Avanzado

Debug log: registra las solicitudes a Shippo en logs/vfd_shpo_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. El token de API y las direcciones de los clientes nunca 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 el módulo se borran sus ajustes, el transportista y el registro. Si está desactivado, todo se conserva para una reinstalación. Las tarifas en caché siempre se eliminan. El transportista y el servicio guardados con los pedidos son historial de pedidos y se conservan.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de Shippo. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el subtotal. El módulo primero comprueba las condiciones: los países de Ignore shipping zones, el peso del carrito y el subtotal mínimo. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna solicitud a Shippo.

Después, el módulo envía a Shippo la dirección de origen, la dirección del cliente y el paquete. Para los países donde PrestaShop exige código postal, la solicitud espera hasta que el cliente lo introduzca. En los envíos internacionales se añade una declaración aduanera con los nombres, cantidades, pesos y valores de los artículos. Shippo devuelve las tarifas de tus transportistas y el módulo usa la tarifa permitida más barata. El precio se calcula en la moneda predeterminada de tu tienda y después se muestra en la moneda del carrito del cliente.

En el modo por pedido, los artículos se apilan en una caja: los lados más largos y medianos de los artículos más grandes, y los lados más cortos de todas las unidades sumados. Si algún producto no tiene dimensiones, se usa el tamaño de caja predeterminado para todo el paquete. En el modo por artículo, cada producto se cotiza como su propio paquete y la tarifa se multiplica por su cantidad.

Cada respuesta se guarda en caché durante 1 hora por dirección y paquete. Cuando Shippo responde sin una tarifa utilizable, la dirección se recuerda durante 10 minutos. Después de un tiempo de espera, un token rechazado, un error del servidor o un límite de solicitudes, el módulo pausa las solicitudes durante 5 minutos y usa los precios de respaldo. El tiempo de espera de la solicitud es de 10 segundos.

Si no hay tarifa en tiempo real, el precio sale de la tabla de respaldo y, después, de Other countries. Si ninguna aplica, el transportista se oculta. El cliente nunca ve un error. El motivo se escribe en el registro de depuración.

Si editas el transportista en Shipping > Carriers después de que tenga pedidos, 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 compra etiquetas, no hace seguimiento de paquetes, no valida direcciones, no ofrece puntos de recogida o entrega, seguro, opciones de firma ni etiquetas de devolución. Solo se muestra la tarifa permitida más barata, no una lista de todos los servicios. No hay empaquetado de cajas más allá del apilado descrito arriba, ni recargos ni tasas de gestión sobre la tarifa.

Pedidos

Cuando se realiza un pedido con una tarifa de Shippo en tiempo real, el módulo guarda el Carrier / service elegido y, en el modo de un paquete por pedido, los Estimated delivery days. Aparecen en el bloque Shippo de la página del pedido en el back office, para que puedas comprar la etiqueta correspondiente en Shippo. Los datos se congelan con el pedido: los cambios posteriores del carrito no los modifican. Los pedidos con precio de respaldo o envío gratis no tienen bloque de Shippo.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Shippo es el primero de la página Modules > Module Manager > VibeFox Shippo > Configure, 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 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-shippo y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 tras 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 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. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, el transportista de Shippo no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. El front office 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 aviso 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 necesitan 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 hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Shippo no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Shippo shipping 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 permitido). Revisa los límites de peso y el Minimum subtotal. Sin tarifa en tiempo real, comprueba que el país, * Default u Other countries tengan un precio. Los productos también pueden limitarse a ciertos transportistas en la página del producto.

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 del módulo. Motivos habituales: falta el token de API o el código postal de origen, la moneda predeterminada de la tienda es distinta de la moneda de tarifas de Shippo sin tipo de cambio, el cliente aún no ha introducido su código postal, ningún transportista de tu cuenta de Shippo atiende la dirección, o la cuenta de Shippo todavía no está verificada.

Tarifas de prueba en la tienda en producción: un token de prueba (shippo_test_...) devuelve tarifas de prueba de Shippo. Usa el token real (shippo_live_...).

Envío gratis en países inesperados: revisa la tabla de precios por si hay una fila vacía, sobre todo una fila * Default vacía. Una fila con todas las celdas vacías cobra 0.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las tarifas de Shippo en caché.

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

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Shippo y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se borra (los pedidos conservan su historial) y se eliminan los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Volver a instalar el módulo devuelve al transportista el estado que tenía antes. Los pedidos existentes conservan los datos del transportista y del servicio de Shippo.

Shippo es una marca comercial de su respectivo titular. Este módulo no está afiliado a Shippo ni avalado por Shippo.