VibeFox Estafeta 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 DrEnvio (solo para tarifas en tiempo real): las tarifas de Estafeta en tiempo real proceden de DrEnvio, socio de Estafeta en México. Crea una cuenta en drenvio.com, activa Estafeta, configura allí tu dirección de recogida y copia la clave de API de tu panel de DrEnvio. Es la misma clave que usa el plugin oficial de DrEnvio. Si solo usas tus propios precios, no necesitas una cuenta de DrEnvio.

Productos: los productos necesitan un peso para las tarifas en tiempo real.

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_estafeta-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_estafeta.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_estafeta-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 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 Estafeta 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 DrEnvio API key y, opcionalmente, el Origin postcode. Si tu moneda predeterminada no es MXN, introduce el MXN exchange rate. Define un precio por país para MX o un Fallback cost si el método debe seguir visible cuando DrEnvio no tenga tarifa. 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_estafeta.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 Estafeta, haz clic en Install (el botón verde +) y luego 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 ajustes y sus campos son los mismos en ambas versiones.

Tras la instalación el método está 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 Estafeta que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Estafeta > 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 las tarifas de DrEnvio 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 avisos: falta la clave de API de DrEnvio, la moneda predeterminada no es MXN y no hay tipo de cambio, no hay precio por país para MX ni coste alternativo (en ese caso el método se oculta cuando no hay tarifa en tiempo real, o nunca se muestra sin clave de API), o no hay una clase de peso en kg (los pesos de los productos se convierten según el nombre de la unidad de su clase de peso, y las unidades desconocidas se toman como kg; añade una clase en kg en System > Localisation > Weight Classes). Los campos numéricos aceptan punto o coma decimal. Al guardar, un valor incorrecto se notifica y se borra o se restablece como se describe en cada campo, el formulario muestra el valor guardado y los demás ajustes sí se guardan (The other settings were saved.).

General

El método se ofrece para la zona geográfica indicada más abajo (o para todas las direcciones), o para los países de Availability without shipping zones.

Enable/Disable: activa o desactiva el envío con Estafeta. Por defecto: desactivado.

Name: el nombre del método de envío que ve el cliente en la finalización de compra. Por defecto: Estafeta. Obligatorio: de 1 a 64 caracteres, sin < > ; = # { }. Un nombre no válido se notifica y se conserva el nombre anterior.

Tax class: la clase de impuesto que se añade al coste de envío, o No tax (por defecto). Que los precios de DrEnvio incluyan IVA depende de tu cuenta de DrEnvio. Si ya incluyen IVA, elige No tax.

Geo zone: ofrece Estafeta solo para direcciones de esta zona geográfica, por ejemplo una zona "México". 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.

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

Tarifas en tiempo real (API de DrEnvio)

La sección explica dónde obtener la clave. Se ofrece el servicio de Estafeta más económico para la dirección. Sin clave se usan los precios de Prices without a live rate.

DrEnvio API key: la clave de API de tu panel de DrEnvio. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla.

Remove the saved API key: solo se muestra mientras hay una clave guardada. Actívalo y guarda para eliminar la clave. Después solo se usan Country prices y el Fallback cost. Una clave escrita en el campo de arriba sustituye a la guardada.

Origin country: el código de país de dos letras de la dirección de recogida. Por defecto: MX. Solo se envía junto con el código postal de origen. Un código no válido se notifica y vuelve a MX.

Origin postcode: el código postal de 5 dígitos de la dirección de recogida. Déjalo vacío para usar la dirección de origen guardada en tu cuenta de DrEnvio. Un código postal que no tenga 5 dígitos se borra y se notifica al guardar.

MXN exchange rate: DrEnvio cotiza en pesos mexicanos. Solo hace falta si tu moneda predeterminada no es MXN: el valor de 1 MXN en tu moneda predeterminada, por ejemplo 0.05. Sin él no se usan las tarifas en tiempo real. Debe ser mayor que 0. Si la moneda de la tienda es MXN, déjalo vacío.

Precios sin tarifa en tiempo real

Se usan cuando no hay clave de API o DrEnvio no devuelve ninguna tarifa de Estafeta (API caída, código postal desconocido, o aún no se ha introducido ningún código postal). Los precios están en la moneda predeterminada de tu tienda, sin impuestos.

Country prices: un país de destino por línea, con el formato CC:PRECIO, por ejemplo MX:150. Usa punto o coma decimal, sin separador de miles. Las partes con otro formato se ignoran y se notifican al guardar.

Fallback cost: el precio cuando no hay tarifa en tiempo real ni precio por país. Déjalo vacío para ocultar el método; 0 significa envío gratuito.

Calculation type: 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 a Country prices y al Fallback cost. Una tarifa en tiempo real de DrEnvio siempre es el precio de todo el paquete.

Condiciones

Free shipping from: el envío es gratuito cuando el subtotal de los productos que necesitan envío (después del cupón y antes de impuestos) alcanza este importe. Entonces no se hace ninguna petición a DrEnvio. Déjalo vacío para no ofrecer nunca envío gratuito.

Minimum subtotal: muestra el método solo si 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. Si se supera, el método se oculta. Por defecto: 30. 0 significa sin límite.

Si Min weight es mayor que Max weight, al guardar aparece un error y ambos pesos no cambian. Los pesos de los productos se convierten a kg según la clase de peso de cada producto.

Disponibilidad sin zonas de envío

Ignore shipping zones: ofrece el método para los países indicados sin comprobar la zona geográfica. 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_est_debug.log.php (en OpenCart 4 system/storage/logs/vfd_est_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. La clave de API y las direcciones de los clientes nunca se registran. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_est_debug.old.log.php y se inicia un registro nuevo.

Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar la extensión se borran todos sus ajustes y el registro. Si está desactivado (por defecto), se conserva todo para una reinstalación. Los servicios de Estafeta guardados en los pedidos siempre se conservan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. La clave 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. La clave de API 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 Estafeta. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, no se ofrece Estafeta. 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 las condiciones: la lista Countries (cuando Ignore shipping zones está activado), el peso del carrito y el subtotal mínimo. Si se aplica envío gratuito, el precio es 0 y no se envía ninguna petición a DrEnvio.

En caso contrario, la extensión envía a DrEnvio el país y el código postal de destino, el peso del carrito, el número de artículos y el subtotal en MXN, y el código postal de origen si lo has definido. Los códigos postales mexicanos deben tener 5 dígitos; hasta que el cliente introduzca una dirección de entrega con uno, no se hace ninguna petición. DrEnvio devuelve cotizaciones de todas las empresas de transporte de tu cuenta. La extensión usa solo las cotizaciones de Estafeta, ignora los precios a cero, elige la más económica y la convierte a tu moneda predeterminada. El precio se redondea a los decimales de esa moneda y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.

Cada respuesta se guarda en caché durante 1 hora. Una petición fallida o una ruta sin tarifa de Estafeta se recuerda durante 5 minutos, para que una API lenta o averiada nunca ralentice cada actualización de la finalización de compra. El tiempo máximo de espera de la API es de 12 segundos. En estos casos el cliente no ve ningún error: se usa el precio por país o el coste alternativo, o el método se oculta si no hay ninguno. El motivo se escribe en el registro.

El cliente solo ve el nombre del método y el precio. La extensión solo calcula tarifas. No crea envíos, no imprime guías ni rastrea paquetes; crea el envío en tu cuenta de DrEnvio o de Estafeta. El cliente no puede elegir un servicio concreto de Estafeta ni una oficina de Estafeta, y los tipos de cambio no se actualizan automáticamente.

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

Pedidos

Cuando se realiza un pedido con Estafeta, la extensión guarda la tarifa que se mostró al cliente, sin una nueva petición a DrEnvio. Los cambios posteriores del pedido en el administrador no lo modifican. En OpenCart 4 la finalización de compra mantiene un único pedido y lo actualiza cada vez que el cliente vuelve a confirmar, así que la tarifa guardada se sustituye por la última tarifa de 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.

La página del pedido en Sales > Orders muestra un panel Estafeta:

Estafeta service: el servicio de Estafeta de la cotización de DrEnvio y su plazo de entrega. Solo se muestra para las tarifas en tiempo real.

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

Shipping cost: el precio de envío calculado en la finalización de compra en tu moneda predeterminada, sin impuestos.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Estafeta es el primero de Extensions > Extensions > Shipping > VibeFox Estafeta > 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-estafeta 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 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Estafeta no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un 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 se oculta 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 después de introducir la clave, y después una vez por semana. No se necesita ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Estafeta 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 los avisos de la parte superior de la página de la extensión, los límites de peso y Minimum subtotal. Sin clave de API, o cuando DrEnvio no tiene tarifa de Estafeta, el método necesita un precio por país para el destino o un coste alternativo. 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. Muestra el motivo: no hay clave de API, no hay tipo de cambio para una tienda cuya moneda predeterminada no es MXN, un código postal falta o no es válido, la clave de API fue rechazada (HTTP 401 o 403 de DrEnvio; revisa la clave de API), no hay tarifa de Estafeta para la ruta (el registro enumera las empresas de transporte que devolvió DrEnvio), o hay una tarifa en una moneda distinta de MXN.

¿El precio incluye IVA? Depende de tu cuenta de DrEnvio. Si los precios de DrEnvio ya incluyen IVA, define Tax class en No tax.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas de DrEnvio en caché.

La página del pedido no tiene panel de Estafeta: el panel solo se muestra en los pedidos realizados con Estafeta mientras la extensión estaba instalada y activada.

La página dice "Warning: You do not have permission to modify VibeFox Estafeta!": tu grupo de usuarios de administración solo puede ver la configuración. Da al grupo el permiso de modificación para extension/shipping/vfd_estafeta (OpenCart 3) o extension/vfd_estafeta/shipping/vfd_estafeta (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: la dirección de la API de DrEnvio se puede cambiar con el ajuste vfd_est_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 Estafeta. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable/Disable, 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 Estafeta 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. Los servicios de Estafeta guardados en los pedidos se conservan en ambos casos, y los pedidos mantienen su método y coste de envío.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox Estafeta en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Estafeta y DrEnvio son marcas comerciales de sus respectivos propietarios. Esta extensión no está afiliada ni respaldada por Estafeta ni por DrEnvio.