VibeFox FedEx for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con 3.0.5.0) o 4.0.2 y posteriores (probado con 4.1.0.3).

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

Cuenta de FedEx y claves de API (solo para tarifas en tiempo real): en el Portal para desarrolladores de FedEx (developer.fedex.com), crea un proyecto con la API de tarifas, vincula tu cuenta de envío de FedEx y copia la clave de API (API Key) y la clave secreta (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. La extensión usa la API REST de FedEx con OAuth 2.0; no necesita un número de medidor ni una 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 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_fedex-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_fedex.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_fedex-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, también 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 FedEx 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 (véase Clave de licencia).

5. 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 estado de 2 letras). Desactiva Sandbox cuando uses claves de producción. Opcionalmente, introduce precios fijos como alternativa. Activa Enable/Disable y haz clic en Save.

OpenCart 4

1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_fedex.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 FedEx, 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 configuración y sus campos son iguales en ambas versiones.

Tras la instalación, el método permanece desactivado hasta que actives Enable/Disable y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de FedEx que conservaste.

Configuración

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

En la parte superior de la página, la extensión muestra advertencias: solo algunas de las tres credenciales de API están rellenadas, no hay claves de API ni precios fijos (entonces el método nunca se muestra), no hay código postal de origen, no hay estado de origen para EE. UU. o Canadá, la moneda de la tienda no tiene tipo de cambio para tarifas en la moneda de la cuenta de FedEx, una unidad de peso que la extensión no reconoce cuando no hay una clase de peso en kg (añade una en System > Localisation > Weight Classes) o, si hay un tamaño de caja, una unidad de longitud que no reconoce. Los campos numéricos aceptan punto o coma decimal. Al guardar, se notifica y no se guarda un número o tamaño de caja no válido, un tipo de cambio de 0, una moneda de cuenta que no es un código de 3 letras, o un nombre u orden de clasificación no válidos; el campo conserva su valor anterior y los demás campos sí se guardan (The other settings were saved.). También se notifica si el peso mínimo es mayor que el máximo, y ambos pesos conservan sus valores anteriores.

General

Los ajustes se aplican a todas las zonas geográficas. FedEx se ofrece en el checkout como una única opción de envío: el servicio de FedEx más económico, o el precio fijo cuando FedEx no devuelve ninguna tarifa.

Enable/Disable: activa o desactiva el envío con FedEx en la finalización de compra. Por defecto: desactivado.

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

Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Con una clase de impuesto, OpenCart añade impuestos al coste de envío, así que se usa el cargo de FedEx sin impuestos. Con No tax, se usa tal cual el cargo neto de FedEx.

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

API de FedEx (tarifas en tiempo real)

La sección enlaza con el Portal para desarrolladores de FedEx. Sin claves se usan los precios fijos.

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

API Key: la API Key (client_id) de tu proyecto del Portal para desarrolladores de FedEx. Borrarla también elimina la Secret Key guardada.

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. Clearing the API Key removes it too. Introduce un valor nuevo solo para cambiarlo.

FedEx account number: la cuenta de envío de FedEx de 9 dígitos vinculada al proyecto. Las tarifas de cuenta (negociadas) se cotizan para ella.

Rates: Account rates (your negotiated FedEx prices) (por defecto) 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. Por defecto: activado.

Box size (L x W x H): dimensiones opcionales de la caja en la unidad de longitud de la tienda que indica el nombre del campo, por ejemplo 30x20x15. FedEx aplica entonces el peso volumétrico. 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á. Por defecto: USD. A FedEx siempre se le pide también cotizar 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 distinta: 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, y un importe en otra moneda nunca se muestra como si fuera tu moneda.

Cache: el botón Clear cached FedEx token and rates vacía la caché al momento. Los tokens de FedEx se guardan en caché hasta que caducan, las tarifas durante 1 hora y las peticiones fallidas durante 5 a 10 minutos.

Ship from

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

Country: el país desde el que envías. Por defecto: 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 del envío.

ZIP / postal code: el código postal de origen. FedEx lo necesita para cotizar tarifas. OpenCart no tiene un código postal de tienda, así que introdúcelo aquí.

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 método en ese caso.

Country prices: una lista de países de destino y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add row para añadir una fila y en el botón × para eliminarla. Elige * Any other country para un precio que se usa en cualquier país sin fila propia. Las filas sin país o precio válidos se ignoran y se notifican al guardar.

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

Fixed price is: Per order (por defecto) 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 de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual este método es gratuito. Entonces no se hace ninguna petición a FedEx. Déjalo vacío para no dar nunca envío gratuito.

Minimum subtotal: muestra el método solo cuando el mismo subtotal es al menos este importe. Déjalo vacío para mostrarlo siempre.

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

Max weight (kg): el peso máximo del carrito. El método se oculta si se supera. 0 significa sin límite (por defecto).

Default product weight (kg): el peso usado para los productos sin peso, en las tarifas de FedEx y en los límites de peso anteriores. Por defecto: 0.5; un campo vacío también equivale a 0.5 kg. Los pesos de los productos se convierten desde la clase de peso de cada producto.

Geo zone: ofrece FedEx solo para direcciones de 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 usa cuando Ignore shipping zones está activado.

Disponibilidad sin zonas de envío

Ignore shipping zones: no comprueba la zona geográfica; ofrece el método para los países indicados abajo. Por defecto: desactivado.

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

Avanzado

Debug log: escribe las peticiones a la API y los cálculos de tarifas en storage/logs/vfd_fdx_debug.log.php (en OpenCart 4, system/storage/logs/vfd_fdx_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, incluso con el registro desactivado. Las claves, los tokens, el número de cuenta y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_fdx_debug.old.log.php y se inicia un registro nuevo.

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 de FedEx, los tokens y tarifas en caché y el registro. Si está desactivado (por defecto), todo se conserva para una reinstalación. Las tarifas de FedEx de los pedidos realizados siempre se conservan.

Importar / Exportar

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

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. La Secret Key guardada se conserva.

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 FedEx. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, no se ofrece FedEx. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no entran en el subtotal. El subtotal es el precio de estos productos después del descuento del cupón y antes de impuestos; no se tienen en cuenta los certificados de regalo, los puntos de recompensa ni el crédito de la tienda. Después la extensión comprueba los países permitidos (con Ignore shipping zones), el peso del carrito y el subtotal mínimo. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna petición a FedEx.

En caso contrario, si la API Key, la Secret Key y el número de cuenta están definidos, la extensión obtiene un token OAuth y envía a la API de tarifas de FedEx la dirección de origen, la dirección de destino, el peso del carrito (en kg, o en lb para tiendas cuya clase de peso sea lb u oz), el tamaño de la caja si está definido, y tu moneda predeterminada como moneda preferida. En los países con Postcode Required activado en OpenCart, la petición solo se hace después de que el cliente introduzca un código postal. En 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, la extensión 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 económico. El precio se redondea a los decimales de tu moneda predeterminada y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.

El token se guarda en caché hasta que caduca y se vuelve a solicitar 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 máximo 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 método se oculta. El motivo se escribe en el registro de depuración.

La extensión solo calcula tarifas. No crea envíos de FedEx, no imprime etiquetas, no reserva recogidas, no rastrea paquetes ni permite a los clientes elegir una ubicación de FedEx. Muestra una opción (el servicio más económico), no varias, y no hay empaquetado de cajas: el carrito se cotiza como un único paquete.

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

Pedidos

Cuando se realiza un pedido con FedEx, la tarifa mostrada al cliente se guarda con el pedido. En Sales > Orders, la página del pedido tiene un panel FedEx shipping. Muestra el FedEx service de la tarifa (para tarifas en tiempo real), el 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 congelan cuando se realiza el pedido: los cambios posteriores en la configuración no los modifican. En OpenCart 4 se mantiene un único pedido para la finalización de compra, que se actualiza cada vez que el cliente vuelve a confirmar: la tarifa de FedEx guardada se actualiza con él, y se elimina cuando el cliente cambia a otro método de envío.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox FedEx es el primero de Extensions > Extensions > Shipping > VibeFox FedEx > 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 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-fedex 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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el 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. 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, FedEx 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 queda oculto 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 requieren 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 tras introducir la clave, y después una vez por semana. No se necesita ningún cron job. Al desinstalar la extensión 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. Revisa Geo zone, o Ignore shipping zones y Countries. Revisa las advertencias de la parte superior de la página de la extensión, los límites de peso y Minimum subtotal. Sin tarifa en tiempo real, el método necesita un precio por país, una fila * Any other country o un Fallback cost. Comprueba que los productos tengan Requires Shipping en Yes.

Las tarifas en tiempo real no aparecen: activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Allí se registran las claves incorrectas, el entorno equivocado (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 usa USD: a FedEx se le pide la tarifa en la moneda predeterminada de tu tienda. Si tu cuenta devuelve solo su propia moneda, define 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 como 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 de la extensión borra la caché. También puedes hacer clic en Clear cached FedEx token and rates.

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

Para desarrolladores: otras extensiones pueden cambiar la dirección de la API, los servicios de FedEx permitidos y la petición de tarifa mediante los eventos de OpenCart vfd_fedex/api_base_url, vfd_fedex/allowed_services y vfd_fedex/rate_request (registrados como catalog/vfd_fedex/...); el ajuste vfd_fdx_api_url sustituye la dirección de la API para pruebas y no tiene campo en la página de configuración.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox FedEx. OpenCart siempre restablece Enable/Disable, Sort order, Tax class y Geo zone. Los tokens y tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes de FedEx y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Las tarifas de FedEx de los pedidos realizados se conservan en ambos casos, y los pedidos mantienen 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, haz clic en Uninstall (el botón naranja −) junto a VibeFox FedEx en la lista de extensiones instaladas y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

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