VibeFox FedEx for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior con la extensión cURL. Sin ellos, el módulo no se instala.

Cuenta de FedEx y claves de API (solo para tarifas en tiempo real): en el FedEx Developer Portal (developer.fedex.com) crea un proyecto con la Rate API, vincula tu cuenta de envío de FedEx y copia la API Key y la Secret Key. También necesitas tu número de cuenta de FedEx de 9 dígitos. Las claves de prueba funcionan solo con Sandbox activado, y las de producción solo con él desactivado. El módulo usa la API REST de FedEx con OAuth 2.0; no necesita número de medidor ni contraseña de servicios web. Si solo usas precios fijos, no necesitas claves de FedEx.

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 FedEx 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. Introduce la API Key, la Secret Key, el número de cuenta de FedEx de 9 dígitos y la dirección de Ship from (código postal y, para EE. UU. y Canadá, el código de estado de 2 letras). Desactiva Sandbox si usas claves de producción. Opcionalmente, introduce precios fijos como alternativa. Haz clic en Save.

Al instalar, el módulo crea el transportista FedEx con el texto de tiempo de entrega FedEx 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 entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures 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 FedEx > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra el token y las tarifas de FedEx en caché.

En la parte superior de la página, el módulo muestra advertencias: solo algunas de las tres credenciales de API están rellenadas; no hay claves de API ni precios fijos (en ese caso el transportista nunca se muestra); no hay código postal de origen; no hay código de estado de origen para EE. UU. o Canadá; la moneda de la tienda es distinta de la moneda de la cuenta de FedEx sin tipo de cambio; la unidad de peso de la tienda (o, con tamaño de caja, la unidad de dimensión) no es compatible con el módulo; o hay un transportista eliminado. Los campos numéricos aceptan punto o coma como separador decimal. Un número o un tamaño de caja no válidos, un tipo de cambio de 0, una moneda de cuenta que no es un código de 3 letras y un nombre de más de 64 caracteres no se guardan y se notifican; el campo conserva su valor anterior y los demás campos se guardan. También se notifica si el peso mínimo es mayor que el máximo, y ambos pesos conservan sus valores anteriores.

General

Enable/Disable: activa o desactiva el envío con FedEx. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Name: el nombre del método de envío que ve el cliente en la finalización de compra (el nombre del transportista). Predeterminado: FedEx. Obligatorio.

Tax status: la regla de impuesto del transportista, o No tax. Con una regla de impuesto (y con los impuestos activados en la tienda), PrestaShop añade el impuesto al coste de envío, así que se usa el coste de FedEx sin impuestos. Con No tax, se usa el coste neto de FedEx tal cual.

API de FedEx (tarifas en tiempo real)

Sin claves se usan los precios fijos que aparecen más abajo. La sección tiene el botón Clear cached FedEx token and rates.

Sandbox: usa el sandbox de FedEx (apis-sandbox.fedex.com) con claves de prueba. Desactívalo para tarifas reales (apis.fedex.com) con claves de producción. Predeterminado: activado.

API Key: la API Key (client_id) de tu proyecto del FedEx Developer Portal.

Secret Key: la Secret Key (client_secret) del mismo proyecto. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Borrar la API Key elimina también la Secret Key guardada.

FedEx account number: el número de cuenta de envío de FedEx de 9 dígitos vinculado al proyecto. Las tarifas de cuenta (negociadas) se cotizan para esa cuenta.

Rates: Account rates (your negotiated FedEx prices) (predeterminado) o List rates (FedEx published prices).

Residential delivery: cotiza las direcciones de los clientes como residenciales (FedEx Home Delivery, recargo residencial). Desactívalo si envías sobre todo a empresas. Predeterminado: activado.

Box size: dimensiones opcionales de la caja en la unidad de dimensión de tu tienda, por ejemplo 30x20x15. Entonces FedEx aplica el peso dimensional. Déjalo vacío para cotizar solo por peso.

FedEx account currency: la moneda de tu cuenta de FedEx, por ejemplo USD para cuentas de EE. UU. o CAD para Canadá. Predeterminado: USD. A FedEx siempre se le pide también que cotice en la moneda predeterminada de la tienda.

Exchange rate: solo es necesario cuando FedEx devuelve tarifas únicamente en la moneda de la cuenta y la moneda predeterminada de tu tienda es otra: el precio de 1 unidad de la moneda de la cuenta en tu moneda predeterminada, por ejemplo 0.92. Sin él, esas tarifas no se usan.

Origen del envío

La dirección desde la que FedEx recoge los paquetes o donde los dejas. Se usa para las tarifas en tiempo real.

Country: el país desde el que envías. Predeterminado: United States.

State / province code: el código de 2 letras, obligatorio para EE. UU. y Canadá, por ejemplo TN, CA u ON.

City: la ciudad de origen.

ZIP / postal code: el código postal de origen. FedEx lo necesita para cotizar las tarifas.

Precios fijos

Se usan cuando no hay claves de API introducidas y como alternativa cuando FedEx no devuelve ninguna tarifa (API caída, claves incorrectas, sin servicio). Deja ambos campos vacíos para ocultar el transportista en ese caso.

Country prices: una tabla con códigos de país de destino de 2 letras y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add row para añadir un país y en el icono de papelera para eliminarlo. Usa * como código de país para cualquier otro país. Las filas que no tengan un código de país (o *) con un precio se ignoran y se notifican al guardar.

Fallback cost: un precio fijo cuando ningún precio de país coincide. Déjalo vacío para ocultar el transportista.

Fixed price is: Per order cobra el precio una sola vez. Per item (price x number of items) lo multiplica por el número de artículos del carrito. Esto se aplica solo a los precios fijos. Las tarifas en tiempo real de FedEx siempre se cotizan para el peso total del carrito.

Condiciones

Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual este transportista es gratuito. Déjalo vacío para no ofrecer nunca envío gratuito.

Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito sea al menos este importe. Déjalo vacío para mostrarlo siempre.

Min weight: el peso mínimo del carrito en kg para que aparezca el transportista. 0 significa sin límite.

Max weight: el peso máximo del carrito en kg. El transportista se oculta si se supera. 0 significa sin límite.

Default product weight: el peso en kg que se usa para los productos sin peso, para las tarifas de FedEx y para los límites de peso anteriores. Predeterminado: 0.5. Los pesos de los productos se convierten desde la unidad de peso de tu tienda (kg, g, lb u oz), configurada en International > Localization (Local units).

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece el transportista para los países siguientes aunque su zona no esté asignada a él. Al guardar, el transportista se vincula a todas las zonas, también a las creadas más adelante. Al desactivarlo, el transportista recupera sus zonas anteriores.

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

Avanzado

Debug log: registra las peticiones a la API y el cálculo de tarifas en logs/vfd_fdx_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de API siempre se registran. Las claves, los tokens 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 eliminan todos sus ajustes, el transportista y los servicios de FedEx guardados de los pedidos. Si está desactivado, todo se conserva para una reinstalación.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de FedEx. Solo cuentan los productos físicos: los productos virtuales no suman peso ni se incluyen en el subtotal. El módulo comprueba primero los países permitidos (con Ignore shipping zones), el peso del carrito y el subtotal mínimo. Si se aplica envío gratuito, el precio es 0 y no se envía ninguna petición a FedEx.

En caso contrario, el módulo obtiene un token OAuth y envía a la Rate API de FedEx la dirección de origen, la dirección de entrega, el peso del carrito (en kg, o en lb para las tiendas que usan lb u oz), el tamaño de caja si está definido y tu moneda predeterminada como moneda preferida. En los países que requieren código postal, la petición se hace solo después de que el cliente haya introducido uno. En los envíos internacionales se envía el valor aduanero del carrito. Los códigos de estado solo se envían para EE. UU. y Canadá.

FedEx devuelve los servicios disponibles. Para cada servicio, el módulo toma la tarifa de cuenta o de lista que elegiste, prefiere una tarifa en tu moneda predeterminada, convierte una tarifa en la moneda de la cuenta de FedEx con tu tipo de cambio y descarta las tarifas que no puede convertir. Se usa el servicio más barato para el precio, y el precio se muestra en la moneda del carrito del cliente.

El token se guarda en caché por entorno y clave, y se vuelve a pedir automáticamente cuando FedEx lo rechaza. Las cotizaciones se guardan en caché durante 1 hora. Una petición de tarifa fallida se recuerda durante 10 minutos y una petición de token fallida durante 5 minutos, para que una caída no ralentice cada actualización de la finalización de compra. El tiempo de espera de la API es de 15 segundos. Si FedEx no responde, el cliente no ve ningún error: se usa el precio fijo o el transportista se oculta. 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 crea envíos de FedEx, no imprime etiquetas, no reserva recogidas, no hace seguimiento de paquetes y no permite que los clientes elijan un punto de FedEx. Muestra una opción (el servicio más barato), no varias, y no hay empaquetado en cajas: el carrito se cotiza como un único paquete.

Pedidos

En la página del pedido en el back office, los pedidos con el transportista FedEx tienen un bloque FedEx shipping. Muestra el FedEx service de la tarifa (para tarifas en tiempo real), la Price source (FedEx live rate, Fixed price (no live rate) o Free shipping threshold) y el Calculated price (excl. tax) en tu moneda predeterminada. Los valores se fijan cuando se realiza el pedido: los cambios posteriores en los ajustes no los modifican.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox FedEx es el primer bloque de Modules > Module Manager > VibeFox FedEx > 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-fedex y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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 y 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 acceder al 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. Eliminar 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 FedEx 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 renovarla. 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 tras introducir la clave, y después una vez a la semana. No hace falta ninguna tarea cron. Al desinstalar o restablecer el módulo, siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

FedEx no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. En Shipping > Carriers comprueba que el transportista cubra la zona del país del cliente y su grupo (o activa Ignore shipping zones y revisa Countries). Revisa las advertencias de la parte superior de la página del módulo, los límites de peso y Minimum subtotal. Sin tarifa en tiempo real, el transportista necesita un precio por país, una fila * o un Fallback cost. Además, los productos 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 revisa el campo Log en la página del módulo. Ahí se registran las claves incorrectas, el entorno incorrecto (claves de prueba con Sandbox desactivado, o claves de producción con él activado), un código postal de entrega que falta y los códigos de error de FedEx.

Mi tienda no está en USD: a FedEx se le pide la tarifa en tu moneda predeterminada. Si tu cuenta devuelve solo su propia moneda, configura FedEx account currency y Exchange rate. Sin tipo de cambio, esas tarifas se ignoran y se usa el precio fijo, así que un importe en USD nunca se muestra en euros.

¿"Per item" multiplica la tarifa de FedEx? No. Per item se aplica solo a los precios fijos.

Las tarifas parecen desactualizadas tras un cambio: guardar la página del módulo borra la caché. También puedes hacer clic en Clear cached FedEx token and rates.

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

Solo se deberían ofrecer algunos servicios: los desarrolladores pueden restringir los servicios con el hook actionVfdFdxAllowedServices. Los hooks actionVfdFdxRateRequest y actionVfdFdxApiBaseUrl cambian la petición de tarifas y la dirección de la API.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox FedEx y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Los tokens y las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se eliminan los ajustes, el registro y los servicios de FedEx guardados de los pedidos. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo (o con Reset), el transportista guardado recupera el estado que tenía antes de la desinstalación.

FedEx es una marca registrada de su respectivo propietario. Este módulo no está afiliado a FedEx ni cuenta con su respaldo.