VibeFox EasyPost for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
PHP: 8.0 o posterior con cURL.
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 las etiquetas que compras, no las solicitudes de tarifas. Si solo usas precios alternativos, 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 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_easypost-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_easypost.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_easypost-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 del paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox EasyPost 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. Pega 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. Pega tu clave de API de EasyPost y rellena la dirección de Ship from. El código postal es obligatorio para las tarifas en tiempo real.
6. Si la moneda predeterminada no es USD, introduce el USD exchange rate. Opcionalmente, introduce los precios alternativos (véase Configuración). Activa Enable EasyPost 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_easypost.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 EasyPost, 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 a 6 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.
Tras la instalación el método queda desactivado hasta que actives Enable EasyPost shipping y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox EasyPost > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas de EasyPost en caché. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes o borrar el registro.
En la parte superior de la página, la extensión muestra advertencias cuando no se pueden usar las tarifas en tiempo real: no hay clave de API (con o sin precios alternativos), no hay código postal o país de origen del envío, o la moneda predeterminada no es USD y no hay tipo de cambio. También aparece una nota cuando hay una clave de API de prueba, y una advertencia cuando la unidad de peso o de longitud de tu tienda (System > Settings > Option) no es una que la extensión conozca (kg, g, lb, oz; cm, mm, m, in).
Al guardar, un nombre de más de 64 caracteres, un Sort order que no es un número entero, o una clase de impuesto o una zona geográfica desconocidas impiden el guardado, y entonces no se guarda nada. 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, mientras que los demás ajustes sí se guardan. Lo mismo ocurre cuando el USD exchange rate es 0, o cuando el Minimum weight es mayor que el Maximum weight.
General
Enable EasyPost shipping: ofrece el método en la finalización de compra. Es el estado de la extensión en Extensions > Extensions > Shipping. Por defecto: desactivado.
Name: el nombre del método de envío que ve el cliente en la finalización de compra, como máximo 64 caracteres. Por defecto: EasyPost Shipping. Si el nombre está vacío, se usa el nombre predeterminado. Un nombre con los caracteres < > ; = # { } se sustituye por el nombre predeterminado, con una advertencia.
Sort order: la posición del método entre los métodos de envío de la finalización de compra. Un número entero.
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. Tras guardar, el campo queda vacío y muestra la clave guardada enmascarada, por ejemplo Saved key: EZAK******abcd. Leave the field empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Sin clave, solo se usan los precios alternativos.
Remove the saved API key: actívalo y haz clic en Save para borrar la clave guardada.
Allowed carriers / services: opcional, separado 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.
Dirección de origen
La dirección desde la que se envían tus paquetes. Si el Country es el país de tu tienda, el campo vacío Sender name / company se toma del nombre de la tienda y el campo vacío State de la región de tu tienda (System > Settings). OpenCart no tiene código postal de tienda, así que el código postal debe introducirse aquí.
Sender name / company: el nombre del remitente o la empresa. Vacío significa el nombre de la tienda (solo en el mismo país).
Street address: la calle de la dirección de origen del envío.
City: la ciudad de origen del envío.
State: el código de estado de dos letras, por ejemplo CA o NY.
ZIP code: el código postal de origen del envío, por ejemplo 94105. Obligatorio para las tarifas en tiempo real.
Country: el país desde el que envías. Por defecto: United States.
Tarifas
Parcels: cómo se envía el carrito a EasyPost.
Los pesos se convierten de la unidad de peso de tu tienda a onzas (mínimo 1 oz) y las dimensiones de la unidad de longitud de tu tienda a pulgadas. Si algún producto no tiene dimensiones, el paquete se tarifica solo por peso.
USD exchange rate: las tarifas de EasyPost están en USD. Introduce el precio de 1 USD en la moneda predeterminada de tu tienda, por ejemplo 0.92. Sin él, no se usan las tarifas en tiempo real, solo los precios alternativos. 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 aceptan tanto el punto como la coma como separador decimal.
Tax class: la clase de impuesto aplicada al envío, o No tax. Las tarifas de EasyPost no incluyen el impuesto sobre ventas.
Precios alternativos
Se usan cuando no hay tarifa en tiempo real: no hay clave de API, EasyPost no se puede conectar, la clave es rechazada o ningún transportista tiene tarifa para la dirección. Los precios están en la moneda predeterminada de tu tienda, sin impuestos. Deja ambos campos vacíos para ocultar el método 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 método en ellos.
Condiciones
Free shipping from: el subtotal del carrito (productos a enviar, después del cupón, antes de impuestos, en la moneda predeterminada) a partir del cual el envío es gratuito. En ese caso no se hace ninguna solicitud a EasyPost. Déjalo vacío para desactivarlo.
Minimum subtotal: muestra el método solo si el subtotal del carrito (productos a enviar, después del cupón, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Minimum weight: oculta el método cuando el carrito pesa menos, en la unidad de peso de tu tienda (que aparece en la etiqueta del campo). 0 significa sin límite (por defecto).
Maximum weight: oculta el método cuando el carrito pesa más, en la unidad de peso de tu tienda. 0 significa sin límite (por defecto).
Disponibilidad
Normalmente la zona geográfica decide dónde se ofrece el método. Como alternativa, se puede ofrecer por país, independientemente de la zona geográfica.
Geo zone: ofrece el método solo a 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 con Ignore shipping zones.
Ignore shipping zones: ofrece el método a los países indicados abajo, estén o no en la zona geográfica.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activados de tu tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe las solicitudes de EasyPost en storage/logs/vfd_ep.log.php (en OpenCart 4 system/storage/logs/vfd_ep.log.php). El archivo no se puede leer desde la web. Cuando alcanza 5 MB, se mueve a vfd_ep.old.log.php y se inicia un registro nuevo. Los errores y las advertencias 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.
Log: muestra el tamaño y las últimas 100 líneas del registro. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: cuando está activado, al desinstalar la extensión se borran sus ajustes y el registro. Los datos de EasyPost de los pedidos realizados se conservan. Desactivar el método nunca borra los ajustes.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de API no se exporta.
Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. La clave de API guardada no cambia.
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 EasyPost. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección queda fuera de ella, el método no se ofrece. Solo cuentan los productos con Requires Shipping configurado en Sí: los demás productos no añaden peso ni se incluyen en el subtotal. La extensión comprueba primero las condiciones: país de destino (con Ignore shipping zones), peso del carrito y subtotal mínimo. El subtotal es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a EasyPost.
En caso contrario, la extensión 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 la moneda predeterminada de tu tienda y la muestra en la moneda del cliente, con el impuesto de la Tax class seleccionada. Para los países marcados con Postcode Required en System > Localisation > Countries, la solicitud se hace solo si la dirección de entrega tiene código postal. En los datos estándar de OpenCart esta marca está desactivada para Estados Unidos, así que también se envía una dirección de EE. UU. sin código postal; EasyPost devuelve entonces un error y se usa el precio alternativo.
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, una clave rechazada, un límite de solicitudes o un error del servidor de EasyPost, no se hacen solicitudes 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 alternativo, o el método se oculta si no hay precio alternativo. El motivo se escribe en el registro.
La extensión solo calcula tarifas. No compra etiquetas, no hace seguimiento de paquetes, no valida direcciones, no ofrece puntos de recogida o entrega, ni añade seguros u opciones 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 paquete, y no hay recargos ni tasas de gestión sobre la tarifa.
En OpenCart 4 el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige el método de EasyPost en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Pedidos
Cuando se realiza un pedido con el método de EasyPost, la tarifa mostrada en la finalización de compra se guarda con el pedido. La página del pedido del administrador (Sales > Orders) muestra el panel EasyPost shipping encima del historial:
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 usados.
Estimated delivery days: los días de entrega devueltos por 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 la moneda predeterminada de tu tienda.
El panel se muestra aunque la extensión se desactive más tarde. Los cambios posteriores del pedido en el panel de administración no modifican estos valores. Úsalos para comprar la etiqueta en tu cuenta de EasyPost. OpenCart crea un registro de pedido cada vez que la finalización de compra llega al paso de confirmación; las tarifas guardadas de esos pedidos sin terminar se eliminan después de 30 días.
En OpenCart 4 la finalización de compra mantiene un único pedido y lo actualiza cada vez que el cliente vuelve a confirmar. La tarifa guardada se actualiza con él: es la tarifa que el cliente vio en la finalización de compra. Si el cliente cambia a otro método de envío, el panel ya no se muestra para ese pedido.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox EasyPost es el primer bloque de la página Extensions > Extensions > Shipping > VibeFox EasyPost > Edit, encima de los ajustes. Pega 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-easypost 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 panel de administración (se incluyen inglés y ruso).
Si la clave no es aceptada, 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. Tras 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, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un 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. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío de EasyPost 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 de administración en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), así que puedes 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 está oculto para todos. Tras 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 renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard o la página Edit del administrador: 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 ninguna tarea cron. Al desinstalar la extensión siempre se eliminan 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. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso y el Minimum subtotal. Sin tarifa en tiempo real, el método necesita un precio alternativo para el país o para Other countries. Comprueba que los productos tienen Requires Shipping configurado en Sí.
Las tarifas en tiempo real no aparecen: lee las advertencias en la parte superior de la página de la extensión, luego activa Debug log, vuelve a cargar la finalización de compra y mira el campo Log. Motivos habituales: no hay clave de API ni código postal de origen, una tienda que no usa USD sin el USD exchange rate, la dirección de entrega aún 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...) configurada. Usa una clave de producción (EZAK...) en la tienda en directo.
Las tarifas se detuvieron durante unos minutos: tras un tiempo de espera, una clave rechazada o un error del servidor de EasyPost, la extensión pausa las solicitudes durante 5 minutos y usa los precios alternativos. Revisa la clave de API y el registro.
¿Está incluido el impuesto? Las tarifas de EasyPost no incluyen el impuesto sobre ventas. Elige la clase de impuesto en Tax class para añadir impuesto al envío.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas de EasyPost en caché.
La página muestra "Warning: You do not have permission to modify VibeFox EasyPost!": tu grupo de usuarios administradores puede tener solo permiso de lectura de los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_easypost (OpenCart 3) o extension/vfd_easypost/shipping/vfd_easypost (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: otras extensiones pueden ajustar el cuerpo de la solicitud, la tarifa elegida y la URL base de la API con los eventos de OpenCart vfd_easypost/shipment_request, vfd_easypost/selected_rate y vfd_easypost/api_url.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox EasyPost. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable EasyPost shipping, Sort order, Tax class y Geo zone. La extensión siempre elimina sus eventos y las tarifas en caché. Si Remove data on uninstall está activado, también se borran los demás ajustes y el registro. Si está desactivado, los ajustes se conservan y se usan de nuevo al volver a instalar la extensión. Los datos de EasyPost de los pedidos realizados nunca se borran, 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 EasyPost en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
EasyPost es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por EasyPost.