VibeFox EasyPost for PrestaShop — Ayuda

Requisitos

PrestaShop: de la 8.0 a la 9.x.

PHP: 8.0 o posterior con la extensión cURL. El módulo no se instala sin ellas.

Cuenta de EasyPost (solo para tarifas en tiempo real): crea una cuenta en el sitio web de EasyPost, conecta tus cuentas de transportista (USPS, UPS, FedEx y otras) en el panel de EasyPost y copia la clave de API desde EasyPost Dashboard > Account Settings > API Keys. EasyPost cobra por las etiquetas compradas, no por las consultas de tarifas. Si solo usas precios de reserva, no necesitas una cuenta de EasyPost.

Productos: los productos necesitan un peso y, mejor aún, dimensiones.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 EasyPost más tarde en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).

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

5. Si tu moneda predeterminada no es USD, introduce el USD exchange rate. Opcionalmente, introduce precios de reserva (véase Configuración). Haz clic en Save.

Al instalarse, el módulo crea el transportista EasyPost Shipping con el texto de tiempo de entrega Live carrier rate (EasyPost). 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 definas precios allí: el precio siempre procede del módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox EasyPost > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de EasyPost en caché.

En la parte superior de la página, el módulo muestra advertencias cuando no se pueden usar las tarifas en tiempo real: no hay clave de API (con o sin precios de reserva), no hay código postal o país de origen, o la moneda predeterminada no es USD y no hay tipo de cambio. También aparece una nota cuando se define una clave de API de prueba, un error cuando se borró el transportista del módulo y una advertencia cuando la unidad de peso o de dimensiones de tu tienda (International > Localization) no es una que el módulo conozca (kg, g, lb, oz; cm, mm, m, in).

Al guardar, un valor que no es un número (o es negativo) no se guarda: una advertencia indica el campo y se conserva el valor anterior. Lo mismo ocurre cuando USD exchange rate es 0, o cuando Minimum weight es mayor que Maximum weight.

General

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

Name: el nombre del transportista que ve el cliente en la finalización de compra, de 64 caracteres como máximo (un nombre más largo se rechaza y no se guarda nada). Predeterminado: EasyPost Shipping. Si el nombre está vacío o tiene caracteres que PrestaShop no permite en el nombre de un transportista, se usa el nombre predeterminado.

Cuenta de EasyPost

API key: tu clave de API de EasyPost desde EasyPost Dashboard > Account Settings > API Keys. Una clave de producción (empieza por EZAK) devuelve tarifas reales. Una clave de prueba (empieza por EZTK) devuelve tarifas de prueba de EasyPost; úsala solo para pruebas. Después de guardar, el campo queda vacío y muestra la clave guardada enmascarada, por ejemplo EZAK******abcd. Deja el campo vacío para conservarla. Escribe un valor nuevo solo para cambiarla.

Remove the saved API key: marca esta casilla y haz clic en Save para borrar la clave guardada.

Allowed carriers / services: opcional, separados por comas. Introduce un transportista (USPS) o un transportista y un servicio (USPS:Priority, UPS:Ground) tal como los nombra EasyPost. 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. Si el Country es el país de tu tienda, los campos vacíos se toman de la dirección de la tienda en Shop Parameters > Contact > Stores (y el nombre del remitente, del nombre de la tienda).

Sender name / company: el nombre del remitente o de la empresa.

Street address: la calle de la dirección de origen.

City: la ciudad de origen.

State: el código de estado de dos letras, por ejemplo CA o NY.

ZIP code: el código postal de origen. Obligatorio para las tarifas en tiempo real.

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

Tarifas

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

One parcel per order (the cart is packed into one box): todas las unidades se apilan en una caja y se tarifan una vez. Es la opción predeterminada.

One parcel per item (every unit ships in its own box): cada producto se tarifa como un paquete propio y la tarifa se aplica a cada unidad. Los precios de reserva también se aplican por unidad.

Los pesos se convierten de la unidad de tu tienda a onzas (mínimo 1 oz) y las dimensiones a pulgadas. Si algún producto no tiene dimensiones, el paquete se tarifa solo por peso.

USD exchange rate: las tarifas de EasyPost están en USD. Introduce el precio de 1 USD en tu moneda predeterminada, por ejemplo 0.92. Sin este valor no se usan las tarifas en tiempo real, solo los precios de reserva. No es necesario si la moneda predeterminada es USD. Las tiendas en USD y CAD piden a EasyPost que cotice en su propia moneda. Se acepta tanto el punto como la coma como separador decimal.

Tax: la regla fiscal del transportista, o No tax. Las tarifas de EasyPost no incluyen el impuesto sobre las ventas. Elige las reglas fiscales que se aplican al envío.

Precios de reserva

Se usan cuando no hay tarifa en tiempo real: no hay clave de API, no se puede contactar con EasyPost, la clave es rechazada o ningún transportista tiene tarifa para la dirección. Los precios están en tu moneda predeterminada, sin impuestos. Deja ambos campos vacíos para ocultar el transportista en ese caso.

Country prices: una línea por país: código de país de dos letras, dos puntos y el precio, por ejemplo US:9.99. Las líneas con otro formato se ignoran y se indican en una advertencia al guardar.

Other countries: el precio para los países que no están en la lista anterior. Déjalo vacío para ocultar el transportista en ellos.

Condiciones

Free shipping from: el subtotal del carrito (productos a enviar, después de descuentos, antes de impuestos, en tu moneda predeterminada) a partir del cual el envío es gratis. En ese caso no se hace ninguna consulta a EasyPost. Déjalo vacío para desactivarlo.

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

Minimum weight: oculta el transportista cuando el carrito pese menos, en la unidad de peso de tu tienda (indicada en la etiqueta del campo). 0 significa sin límite.

Maximum weight: oculta el transportista cuando el carrito pese más, en la unidad de peso de tu tienda. 0 significa sin límite.

Disponibilidad sin zonas de envío

Normalmente el transportista se ofrece en las zonas que tiene asignadas en Shipping > Carriers. Como alternativa, puede ofrecerse por país, independientemente de las zonas.

Ignore shipping zones: ofrece el transportista para los países indicados abajo, tanto si su zona está asignada al transportista como si no. Al guardar con esta opción activada, el transportista se asigna a todas las zonas, incluidas las que se creen después. Al desactivarla, el transportista recupera sus zonas anteriores.

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

Avanzado

Debug log: escribe las peticiones de EasyPost en modules/vfd_easypost/logs/vfd_ep.log.php. El archivo no se puede abrir desde la web y se rota al llegar a 5 MB. Los errores de la API siempre se registran, incluso con esta opción desactivada. La clave de API y las direcciones de los clientes nunca se registran.

Remove data on uninstall: si está activada, al desinstalar el módulo se borran sus ajustes, tablas y registro. Desactivar el módulo nunca borra los ajustes.

Log: el panel bajo los ajustes muestra las últimas 100 líneas del registro. Haz clic en Clear log para vaciarlo.

Cómo funciona en la finalización de compra

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

En caso contrario, el módulo envía a EasyPost la dirección de origen, la dirección de entrega y el paquete, y recibe las tarifas de todas tus cuentas de transportista. Elige la tarifa permitida más barata, la convierte a tu moneda predeterminada y la muestra en la moneda del carrito del cliente. En los países que requieren código postal, la petición se hace solo cuando la dirección de entrega lo tiene. Antes de que el cliente introduzca una dirección, solo se conoce el país del visitante, así que en los países que requieren código postal se aplica el precio de reserva hasta que se introduce la dirección.

Cada respuesta se guarda en caché durante 1 hora para la misma dirección y el mismo paquete. Una dirección sin tarifas utilizables se recuerda durante 10 minutos. Tras un tiempo de espera agotado, una clave rechazada, un límite de peticiones o un error del servidor de EasyPost, no se hacen peticiones durante 5 minutos. El tiempo de espera de la API es de 10 segundos. En todos estos casos el cliente no ve ningún error: se usa el precio de reserva o, si no hay precio de reserva, el transportista se oculta. El motivo se escribe en el registro.

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, ni añade opciones de seguro o de firma. Muestra una sola opción (la tarifa permitida más barata), no una lista de servicios. No hay empaquetado de cajas más allá de apilar los artículos en un solo paquete, ni recargos sobre la tarifa ni gastos de gestión.

Pedidos

Cuando se realiza un pedido con el transportista de EasyPost, la tarifa que se mostró en la finalización de compra se guarda con el pedido. La página del pedido en el back office muestra el bloque EasyPost shipping:

Carrier / service: el transportista y el servicio de EasyPost de la tarifa, por ejemplo USPS Priority. En el modo de un paquete por artículo se enumeran todos los servicios utilizados.

Estimated delivery days: los días de entrega que devuelve EasyPost (solo en el modo de un paquete por pedido, cuando EasyPost los devuelve).

Price source: Live EasyPost rate, Fallback price (no live rate) o Free shipping threshold.

Calculated price (excl. tax): el precio en tu moneda predeterminada.

Los cambios posteriores en el carrito desde el back office no modifican estos valores. Úsalos para comprar la etiqueta en tu cuenta de EasyPost. Las tarifas de los carritos abandonados se eliminan después de 30 días.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox EasyPost es el primer bloque de Modules > Module Manager > VibeFox EasyPost > Configure, 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-easypost 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 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 conectar con el 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. 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 EasyPost 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 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 a la semana. No se necesita ningún cron job. Desinstalar o restablecer el módulo siempre elimina la clave de licencia y el estado de la licencia.

Solución de problemas

EasyPost no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable EasyPost shipping esté activado. En Shipping > Carriers comprueba que el transportista esté activado y cubra la zona del país del cliente y el grupo del cliente (o que Ignore shipping zones esté activado y el país seleccionado). Revisa los límites de peso y el Minimum subtotal. Sin tarifa en tiempo real, el transportista necesita un precio de reserva para el país o para Other countries. En la página del producto también se pueden limitar los productos a determinados transportistas.

No aparecen las tarifas en tiempo real: lee las advertencias de la parte superior de la página del módulo, luego activa Debug log, recarga la finalización de compra y mira el panel Log. Motivos habituales: no hay clave de API ni código postal de origen, una tienda que no usa USD sin USD exchange rate, la dirección de entrega todavía no tiene código postal, ningún transportista de tu cuenta de EasyPost atiende la dirección, o Allowed carriers / services filtra todas las tarifas.

Las tarifas parecen precios de prueba: hay una clave de prueba (EZTK...) definida. Usa una clave de producción (EZAK...) en la tienda en vivo.

Las tarifas se detuvieron durante unos minutos: tras un tiempo de espera agotado, una clave rechazada o un error del servidor de EasyPost, el módulo pausa las peticiones durante 5 minutos y usa los precios de reserva. Revisa la clave de API y el registro.

¿Están incluidos los impuestos? Las tarifas de EasyPost no incluyen el impuesto sobre las ventas. Elige la regla fiscal en Tax para añadir impuestos al envío.

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

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

Hooks para desarrolladores: los hooks actionVfdEpShipmentRequest (cuerpo de la petición), actionVfdEpSelectedRate (tarifa elegida) y actionVfdEpApiUrl (URL base de la API) permiten ajustar el módulo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox EasyPost y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. El transportista se elimina de la finalización de compra (los pedidos conservan su historial) y las tarifas en caché siempre se borran. Si Remove data on uninstall está activado, también se borran los ajustes, las tarifas guardadas de los pedidos y el registro. Si está desactivado, se conservan los ajustes y los datos de EasyPost de los pedidos realizados para una reinstalación. Instalar o restablecer el módulo crea un transportista nuevo. Si se conservaron los ajustes, el transportista recibe el estado (activado o desactivado) del transportista anterior.

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