VibeFox Shippo 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.
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 por las etiquetas compradas, no por las consultas de tarifas. Las cuentas nuevas de Shippo pueden necesitar verificación por parte de Shippo antes de que se devuelvan tarifas en vivo. Sin token, solo se usan los precios de reserva.
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
La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_shippo-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_shippo.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 área de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_shippo-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 Shippo 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. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia, en la parte superior de la página Edit, y haz clic en Activate (ver License key).
5. 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 vivo.
6. Elige la Shippo rate currency (USD si envías desde EE. UU.) y, si la moneda predeterminada de tu tienda es otra, introduce el Exchange rate.
7. Opcionalmente, introduce precios de reserva, activa Enable Shippo shipping y haz clic en Save.
OpenCart 4
1. En el área de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_shippo.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 Shippo, 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 7 para OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable Shippo shipping y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Shippo que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Shippo > Edit. Las secciones aparecen a la izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas de Shippo en caché. Solo los administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
Las advertencias en la parte superior de la página te indican cuándo el método nunca puede mostrarse o cuándo no se pueden usar tarifas en vivo: 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 longitud de la tienda no es conocida por la extensión (usa kg, g, lb u oz, y cm, mm, m o in en System > Settings, pestaña Local). Un aviso te recuerda cuando hay un token de prueba configurado. Al guardar, un nombre no válido, un valor que no es un número, un número o una celda de precio negativos, un Minimum weight (kg) mayor que Maximum weight (kg) o un orden de clasificación que no es un número entero se notifican como error, y no se guarda nada hasta que lo corrijas.
General
Enable Shippo shipping: ofrece el método en la finalización de compra. Este es el estado de la extensión en Extensions > Extensions > Shipping.
Name: el nombre del método de envío que ve el cliente en la finalización de compra. Predeterminado: Shippo Shipping. Obligatorio, 64 caracteres como máximo, sin los caracteres < > ; = # { }.
Tax class: la clase de impuesto del coste de envío, o No tax. Las tarifas de Shippo no incluyen el impuesto de ventas. No tax las muestra tal como se cotizan; una clase de impuesto añade el impuesto sobre el envío según tus reglas fiscales.
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 Shippo
API token: tu token de API de Shippo. Usa el token en vivo (shippo_live_...) para tarifas reales en la tienda activa, 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.
Remove the saved API token: actívalo y guarda para eliminar el token guardado.
Allowed carriers / services: opcional, separado por comas. Introduce un transportista 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.
Ship from (la dirección desde la que se envían tus paquetes)
Cuando el país de envío es el país de tu tienda, un nombre de remitente y un estado vacíos se toman del nombre de la tienda y de la región de System > Settings. OpenCart no tiene una calle, ciudad o código postal estructurados para la tienda, así que introdúcelos aquí.
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 vivo, por ejemplo 94105.
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 longitud de tu tienda (que aparece 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 tras guardar, y los demás ajustes sí se guardan.
Shippo rate currency: la moneda en la que Shippo cotiza a tus transportistas, que es la moneda del país de envío: 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 se usan siempre tal cual.
Exchange rate: el precio de 1 unidad de la moneda de tarifas de Shippo en la moneda predeterminada de tu tienda, por ejemplo 0.92. No es necesario si ambas son iguales. Sin él, las tarifas en la otra moneda no se usan y se aplican los precios de reserva. La extensión no convierte divisas automáticamente.
Precios de reserva (se usan cuando no hay tarifa en vivo: 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 campos vacíos para ocultar el método 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. Las columnas son Price y los tramos de peso XS (hasta 1 kg), S (de 1 a 2 kg), M (de 2 a 3 kg), L (de 3 a 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 guardada con todas las celdas vacías cobra 0, así que elimina las filas que no vayas a rellenar.
Other countries: el precio para los países que no están en la tabla anterior (cuando no hay fila * Default). Déjalo vacío para ocultar el método en esos países.
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 el envío es gratuito. No se hace ninguna petición a Shippo en ese caso. Déjalo vacío para desactivarlo.
Minimum subtotal: muestra el método solo si el subtotal de los productos que necesitan envío (después del cupón, 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 método. 0 significa sin límite (predeterminado).
Maximum weight (kg): el método se oculta si el peso del carrito supera este valor. Predeterminado: 30. 0 significa sin límite. Un campo vacío se guarda como 30.
Disponibilidad sin zonas de envío
Normalmente, la zona geo decide dónde se ofrece el método. Alternativamente, puede ofrecerse por país, independientemente de la zona geo.
Geo zone: ofrece el método solo para direcciones en esta zona geo. All zones (predeterminado) significa sin límite. No se usa mientras Ignore shipping zones esté activado. Las zonas geo se gestionan en System > Localisation > Geo Zones.
Ignore shipping zones: ofrece el método para los países indicados abajo, estén o no en la zona geo.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activados de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra las peticiones a Shippo en storage/logs/vfd_shpo_debug.log.php (en OpenCart 4, system/storage/logs/vfd_shpo_debug.log.php). El archivo no se puede leer 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. Cuando el archivo alcanza 5 MB, se mueve a vfd_shpo_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 Shippo y el registro. Si está desactivado (predeterminado), se conservan para una reinstalación. Las tarifas en caché siempre se eliminan. El transportista y el servicio guardados con los pedidos forman parte del historial de pedidos y se conservan.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El token de API 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. El token de API guardado no se modifica.
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 Shippo. Si hay una Geo zone configurada (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, el método no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no se incluyen en el subtotal. Después, la extensión comprueba las condiciones: los países de Ignore shipping zones, el peso del carrito y el subtotal mínimo. Las tarjetas 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 petición a Shippo.
Después, la extensión envía a Shippo la dirección de envío de la tienda, la dirección del cliente y el paquete. En los países donde OpenCart exige código postal, la petición espera a que el cliente lo haya introducido. Para los envíos internacionales se añade una declaración aduanera con los nombres de los artículos (con las opciones elegidas), cantidades, pesos y valores. Shippo devuelve las tarifas de tus transportistas, y la extensión usa la tarifa permitida más barata. El precio se calcula en la moneda predeterminada de tu tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
En el modo por pedido, los artículos se apilan en una caja: los lados más largo y medio 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 tarifica como un paquete propio 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. Tras un tiempo de espera, un token rechazado, un error del servidor o un límite de peticiones, la extensión pausa las peticiones durante 5 minutos y usa los precios de reserva. El tiempo de espera de la petición es de 10 segundos.
Si no hay tarifa en vivo, el precio procede de la tabla de precios de reserva y, después, de Other countries. Si ninguno se aplica, el método se oculta. El cliente nunca ve un error. El motivo se escribe en el registro de depuración.
La extensión solo calcula tarifas. No compra etiquetas, no rastrea paquetes, no valida direcciones, no ofrece puntos de recogida o entrega, ni seguros, opciones de firma o 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 apilamiento descrito, ni recargos ni tarifas de gestión.
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 Shippo en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Pedidos
Cuando se realiza un pedido con una tarifa en vivo de Shippo, la extensión guarda el Carrier / service elegido y, para un paquete por pedido, los Estimated delivery days. Abre el pedido en Sales > Orders: aparecen en el panel Shippo, encima del historial del pedido, para que puedas comprar la etiqueta correspondiente en Shippo. Los datos se guardan con el pedido: los cambios posteriores en el carrito o en los ajustes no los modifican. El panel también se muestra después de desactivar el método. Los pedidos con precio de reserva o envío gratuito no tienen panel de Shippo.
OpenCart 4 mantiene un pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar. La tarifa de Shippo guardada se actualiza con él. Si el cliente cambia a otro método de envío, o si ahora se aplica el precio de reserva, la tarifa guardada se elimina del pedido.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Shippo es el primer bloque de Extensions > Extensions > Shipping > VibeFox Shippo > Edit, por 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 están la línea Product: opencart-shipping-shippo y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los 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 con una fecha. Después de cambiar la dirección de la tienda, o después de liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al 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 hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío de Shippo no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un administrador que ha iniciado sesión en el área 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 se oculta para todos. Después de abrir una vez la página Edit, 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 cuando abres el Dashboard del administrador o la página Edit: 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 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
Shippo no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Shippo shipping esté activado. Revisa Geo zone (o, con Ignore shipping zones activado, Countries), los límites de peso y Minimum subtotal. Sin tarifa en vivo, comprueba que el país, * Default u Other countries tenga un precio. Comprueba que los productos tengan Requires Shipping en Yes.
Las tarifas en vivo no aparecen: activa el Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. 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 todavía no ha introducido su código postal, ningún transportista de tu cuenta de Shippo atiende la dirección, o la cuenta de Shippo aún no está verificada.
Tarifas de prueba en la tienda activa: un token de prueba (shippo_test_...) devuelve tarifas de prueba de Shippo. Usa el token en vivo (shippo_live_...).
Envío gratuito para países inesperados: revisa la tabla de precios por si hay una fila vacía, especialmente una fila * Default vacía. Una fila con todas las celdas vacías cobra 0.
Pesos o tamaños de caja incorrectos: si la página avisa de una unidad de peso o de longitud desconocida, configura una clase de peso en kg, g, lb u oz y una clase de longitud en cm, mm, m o in en System > Settings, pestaña Local.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas de Shippo en caché.
La página dice "Warning: You do not have permission to modify VibeFox Shippo!": tu grupo de usuarios de administración solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_shippo (OpenCart 3) o extension/vfd_shippo/shipping/vfd_shippo (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de Shippo puede sustituirse con el ajuste vfd_shpo_api_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Shippo. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Shippo shipping, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de Shippo y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al reinstalar la extensión. Los pedidos existentes conservan su método de envío, su coste y los datos de transportista y servicio de Shippo.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox Shippo en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Shippo es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Shippo.