VibeFox ShipStation 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 ShipStation: conecta tus transportistas en ShipStation (Settings > Shipping > Carriers) y copia la API Key y el API Secret desde ShipStation > Settings > Account > API Settings. El acceso a la API depende de tu plan de ShipStation. La extensión usa la API V1 de ShipStation (API Key y API Secret). Sin claves, solo se usan los precios de reserva.
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_shipstation-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_shipstation.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_shipstation-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 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 ShipStation 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. 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 (ver Clave de licencia).
5. Pega la API Key y el API Secret, introduce el código postal de origen y haz clic en Save. La página muestra ahora los códigos de transportista de tu cuenta. Escribe el o los que quieras en Carrier codes y guarda de nuevo.
6. Si la moneda predeterminada de tu tienda no es la moneda de tu cuenta de ShipStation, configura Exchange rate. Opcionalmente, rellena los precios de reserva.
7. Activa Enable ShipStation shipping y haz clic en Save.
OpenCart 4
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_shipstation.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 ShipStation, 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 de OpenCart 3. La página de configuración y sus campos son los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que lo actives y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de ShipStation que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado borra las tarifas de ShipStation en caché y comprueba la clave y el secreto de la API. Después, la página muestra los transportistas conectados a tu cuenta con sus códigos, por ejemplo "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Solo los administradores con el permiso de modificación de esta extensión pueden guardar la configuración.
Las advertencias en la parte superior de la página indican cuándo no pueden funcionar las tarifas en tiempo real: sin claves, sin código de transportista, sin código postal de origen, sin tipo de cambio, con la comprobación de conexión fallida o con códigos de transportista que no están conectados a tu cuenta. También aparece una advertencia si la unidad de peso o de longitud de la tienda no es una que la extensión pueda convertir. Usa kg, g, lb u oz y cm, mm, m o in (System > Settings > Option). Un nombre no válido, un campo numérico o una celda de precio con un valor negativo o con texto que no es un número, un Minimum weight mayor que el Maximum weight, o un orden de clasificación que no es un número entero se notifican como error, y no se guarda nada.
General
Enable ShipStation shipping: muestra u oculta 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: ShipStation Shipping. Obligatorio, máximo 64 caracteres, sin los caracteres < > ; = # { }.
Tax class: la clase de impuesto del coste de envío, o No tax. Las tarifas de ShipStation no incluyen impuesto sobre las ventas. No tax las muestra tal como se cotizaron; una clase de impuesto añade impuesto al envío según tus reglas fiscales.
Sort order: la posición del método entre los métodos de envío en la finalización de compra. Un número entero.
ShipStation account
API Key: la API Key de ShipStation > Settings > Account > API Settings. Se envía solo a ShipStation 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 cambiarla.
API Secret: el API Secret de la misma página. Se guarda igual que la clave.
Remove the saved API key and secret: aparece una vez guardadas las claves. Márcalo y guarda para eliminar ambas.
Carrier codes: uno o más códigos de transportista de ShipStation, separados por comas, por ejemplo stamps_com, ups_walleted. Se usan hasta 5 códigos, con una petición a la API por transportista. Si introduces más, solo se conservan los primeros 5 y la página te lo indica. Se muestra la tarifa más barata de estos transportistas. Toma los códigos de la lista que aparece tras guardar.
Allowed services: opcional, códigos de servicio de ShipStation separados por comas, por ejemplo usps_priority_mail, ups_ground. Déjalo vacío para mostrar el servicio más barato de los transportistas indicados arriba.
Package code: "package" (el valor predeterminado) calcula las tarifas para tu propia caja y deja fuera los sobres y las cajas de tarifa plana del transportista. Déjalo vacío para calcular las tarifas de todos los tipos de paquete que ofrece el transportista.
Ship from
Ship-from postal code: obligatorio para las tarifas en tiempo real, por ejemplo 78703. ShipStation calcula las tarifas solo con el código postal, que debe estar en el país de tu cuenta de ShipStation. OpenCart no tiene código postal de tienda, así que nunca se toma de la dirección de la tienda.
Rates
Parcels: cómo se envía el carrito a ShipStation.
ShipStation account currency: la moneda en la que ShipStation devuelve las tarifas: USD, CAD, GBP, AUD, NZD o EUR. Predeterminado: USD (cuentas de EE. UU.).
Exchange rate: el precio de 1 unidad de la moneda de la cuenta en la moneda predeterminada de tu tienda, por ejemplo 0.92. Solo hace falta cuando la moneda predeterminada es distinta de la de la cuenta. Sin él, no se usan las tarifas en tiempo real y se aplican los precios de reserva. Los tipos de cambio no se actualizan automáticamente.
Fallback prices (se usan cuando no hay tarifa en tiempo real: sin claves de API, ShipStation no disponible o sin tarifas de transportista para la dirección; precios en la moneda predeterminada de tu tienda; deja vacía la tabla y Other countries para ocultar el método en ese caso)
Prices by country: una tabla con un precio Base por país y columnas de tamaño según el peso del paquete: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg y XL por encima de 5 kg. Haz clic en Add country para añadir una fila. Un tamaño vacío usa el precio base. Un precio base de 0 significa envío gratis. La fila * Default (all other countries) se aplica a los países sin fila propia. Una fila sin ningún precio no se guarda.
Other countries: el precio cuando la tabla no tiene precio para el país. Déjalo vacío para ocultar el método en ese caso.
Conditions
Free shipping from: el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) a partir del cual el envío es gratis. En ese caso no se hace ninguna petición a ShipStation. Déjalo vacío para desactivarlo.
Minimum subtotal: muestra el método solo si el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Minimum weight: el peso mínimo del carrito, en la unidad de peso de tu tienda (indicada en el nombre del campo), para mostrar el método. 0 significa sin límite (predeterminado).
Maximum weight: el método se oculta por encima de este peso del carrito, en la unidad de peso de tu tienda. 0 significa sin límite (predeterminado).
Availability
Geo zone: ofrece el método solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. No se comprueba mientras Ignore shipping zones esté activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore shipping zones: ofrece el método para los países indicados abajo, sea cual sea la zona geográfica.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Advanced
Debug log: registra las peticiones a ShipStation en storage/logs/vfd_shst_debug.log.php (en OpenCart 4, system/storage/logs/vfd_shst_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. La clave y el secreto de la API y las direcciones de los clientes nunca se registran. El código postal se enmascara. Cuando el archivo llega a 5 MB, se traslada a vfd_shst_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 ShipStation y el registro. Si está desactivado (predeterminado), se conservan para una reinstalación. Las tarifas en caché siempre se eliminan. El servicio de ShipStation de los pedidos realizados siempre se conserva.
Import / Export
Export: haz clic en Download JSON para guardar la configuración como archivo JSON. La clave y el secreto de la API no se exportan.
Import: pega el JSON exportado previamente y haz clic en Import para restaurar la configuración, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. La clave y el secreto de la API guardados se conservan.
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 ShipStation. Si hay una Geo zone definida (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 definido en Yes: los demás no añaden peso y no se incluyen en el subtotal. Después la extensión comprueba las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. Los certificados regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratis, el método se muestra con precio 0 y no se envía ninguna petición a ShipStation.
Después la extensión envía a ShipStation el código postal de origen, el país de destino, el código de estado, la ciudad y el código postal, el peso del paquete y el tamaño de la caja. No se hace ninguna petición antes de que el cliente introduzca un código postal. Los países sin códigos postales reciben los precios de reserva. Los artículos se apilan en una caja. Si un producto no tiene dimensiones, el paquete se tarifica solo por peso.
ShipStation se consulta una vez por cada código de transportista. La extensión usa la tarifa más barata permitida, convertida a la moneda predeterminada de tu tienda y redondeada a sus decimales. El precio se muestra después en la moneda del cliente con el impuesto de la Tax class seleccionada.
Cada respuesta se guarda en caché durante 1 hora. Cuando ShipStation responde sin una tarifa utilizable, la respuesta se recuerda durante 10 minutos. Cuando ShipStation rechaza las claves o no está disponible, las peticiones se pausan durante 5 minutos. Tras un límite de peticiones, la pausa sigue la hora de reinicio que indique ShipStation. El tiempo de espera de la petición es de 12 segundos.
Si no hay tarifa en tiempo real, el precio sale de la tabla de precios de reserva y, después, de Other countries. Si ninguno aplica, el método se oculta. El cliente nunca ve textos de error de ShipStation. Los detalles van al registro de depuración.
La extensión solo calcula tarifas. No compra etiquetas, no crea pedidos ni envíos en ShipStation, no hace seguimiento de paquetes y no gestiona devoluciones. No hay puntos de recogida, ni elección entre varios servicios en la finalización de compra, ni validación de direcciones, seguro, confirmación de firma, empaquetado en varios paquetes ni recargos sobre las tarifas.
En OpenCart 4, el cliente hace clic en Choose en el bloque de método de envío de la página de finalización de compra y elige ShipStation 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 tiempo real de ShipStation, el servicio elegido se guarda con el pedido. Abre el pedido en Sales > Orders: el panel ShipStation encima del historial del pedido lo muestra como Service, por ejemplo "USPS Ground Advantage - Package", para que puedas crear la etiqueta correspondiente en ShipStation. En el modo por artículo, los servicios aparecen separados por comas. Los cambios posteriores en el carrito no lo modifican, y el panel también se muestra si desactivas el método después. Los pedidos con precio de reserva o con envío gratis no tienen panel de ShipStation.
OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar. El servicio de ShipStation guardado se actualiza con él. Si el cliente cambia a otro método de envío, o si ahora se aplica el precio de reserva, el servicio guardado 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 ShipStation es el primero de la página Extensions > Extensions > Shipping > VibeFox ShipStation > 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 aparecen la línea Product: opencart-shipping-shipstation 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 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, 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. 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, ShipStation no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador que tenga la sesión iniciada 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 se oculta a 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 a la semana. No es necesaria ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
ShipStation no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable ShipStation shipping esté activado. Revisa Geo zone (o, con Ignore shipping zones activado, Countries), los límites de peso y el Minimum subtotal. Sin tarifa en tiempo real, comprueba que el país, * Default u Other countries tenga un precio. Comprueba que los productos tengan Requires Shipping definido en Yes.
La finalización de compra muestra el precio de reserva en lugar de la tarifa de ShipStation: revisa las advertencias en la parte superior de la página de la extensión (claves, código de transportista, código postal de origen, tipo de cambio). Activa Debug log, recarga la finalización de compra y mira el campo Log. El código postal del cliente es obligatorio. No se hace ninguna petición hasta que se introduce.
Qué código de transportista introducir: guarda la configuración con la clave y el secreto. La página muestra los códigos de transportista de tu cuenta. Usa uno o más de ellos.
La comprobación de conexión con ShipStation ha fallado: el mensaje indica el motivo. Revisa la API Key y el API Secret y guarda de nuevo para repetir la comprobación.
La tarifa no coincide con la de ShipStation: el paquete se construye con los pesos y dimensiones de los productos, con los artículos apilados en una caja. Los productos sin dimensiones se tarifican solo por peso. Las tarifas se guardan en caché durante 1 hora. Haz clic en Save en la página de la extensión para borrar la caché.
La página muestra "Warning: You do not have permission to modify VibeFox ShipStation!": es posible que tu grupo de usuarios solo pueda ver la configuración. Da al grupo el permiso de modificación para extension/shipping/vfd_shipstation (OpenCart 3) o extension/vfd_shipstation/shipping/vfd_shipstation (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de ShipStation puede cambiarse con el ajuste vfd_shst_api_url (para pruebas); 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 ShipStation. La clave de licencia y el estado de la licencia de esta extensión se eliminan siempre. OpenCart restablece siempre Enable ShipStation shipping, Sort order, Tax class y Geo zone. Las tarifas en caché y el resultado de la comprobación de conexión siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de ShipStation y el registro de depuración también se borran. 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 su servicio de ShipStation.
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 ShipStation en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.
ShipStation es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por ShipStation.