VibeFox Coordinadora 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.

Clave de API de Coordinadora (solo para cotizaciones en vivo): las cotizaciones en vivo provienen del Cotizador de Coordinadora a través del servicio WooCommerce de Coordinadora, el mismo que usa el complemento oficial de Coordinadora. Coordinadora emite la clave de API a clientes con un acuerdo comercial activo. Pregunta a tu gestor de cuenta de Coordinadora o consulta wc.coordinadora.com. También necesitas el código DANE de 8 dígitos de la ciudad desde la que envías. Sin clave, el método funciona solo con precios fijos.

Productos: para una cotización en vivo, cada producto del carrito necesita peso y tres dimensiones (largo, ancho, alto).

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_coordinadora-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_coordinadora.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_coordinadora-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 Coordinadora 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 Clave de licencia).

5. Introduce la clave de API, el código DANE de la ciudad de origen y, si tu moneda predeterminada no es COP, el tipo de cambio a COP. Añade al menos un precio fijo para Colombia como alternativa (ver Configuración). Activa Enable Coordinadora y haz clic en Save.

6. Asegúrate de que tus productos tengan peso y dimensiones.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_coordinadora.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 Coordinadora, 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 a 6 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 Coordinadora y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Coordinadora que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. Los ajustes se aplican a todas las zonas geográficas; puedes limitar el método a una zona geográfica y a determinados países en Conditions. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. Tras guardar verás Settings saved. Cached Coordinadora rates were cleared. Los números se pueden escribir con punto o con coma (9,99 = 9.99). Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

No se guarda nada y la página muestra los errores si Name está vacío o tiene más de 64 caracteres, si un número o un precio de la tabla no es válido o es negativo, si COP per 1 unit of store currency es 0, si Min weight (kg) es mayor que Max weight (kg), o si Sort order no es un número entero.

La página muestra avisos sobre los ajustes cuando las cotizaciones en vivo no pueden funcionar o el método quedaría oculto: Origin city (DANE code) está vacío o no es válido; falta COP per 1 unit of store currency si tu moneda predeterminada no es COP; no hay precio fijo para Colombia (ni para *); no hay clave de API ni precio fijo para Colombia, así que el método nunca se muestra a las direcciones colombianas. También aparece un aviso cuando la tienda no tiene una clase de peso en kg ni una clase de longitud en cm y su unidad predeterminada no la reconoce la extensión; los pesos de los productos se leen entonces como kg y las dimensiones como cm (usa kg, g, lb u oz y cm, mm, m o in en System > Localisation). Los avisos se actualizan después de cada guardado.

General

Enable Coordinadora: muestra u oculta Coordinadora en la finalización de compra. Por defecto: desactivado.

Name: el nombre del método de envío que ve el cliente en la finalización de compra. Por defecto: Coordinadora. Obligatorio, hasta 64 caracteres.

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

Cotizaciones en vivo de Coordinadora

Las cotizaciones en vivo se piden para destinos en Colombia. Deja la clave vacía para usar solo precios fijos.

API key: tu clave de API de WooCommerce de Coordinadora. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla. La clave nunca se escribe en el registro.

Remove the saved API key: aparece solo cuando hay una clave guardada. Actívala y haz clic en Save para eliminar la clave; el método pasa entonces a usar solo precios fijos.

Origin city (DANE code): el código DANE de 8 dígitos de la ciudad desde la que envías, por ejemplo 11001000 Bogotá, 05001000 Medellín, 76001000 Cali u 08001000 Barranquilla. También se acepta un código de municipio de 5 dígitos, que se completa hasta 8 dígitos.

COP per 1 unit of store currency: Coordinadora cotiza en pesos colombianos. Si tu moneda predeterminada no es COP, indica cuántos COP equivalen a 1 unidad de tu moneda, por ejemplo 4300. El tipo también se usa para enviar el valor declarado en COP. Si lo dejas vacío, las cotizaciones en vivo no se usan. El tipo debe ser mayor que 0. Si tu moneda predeterminada es COP, déjalo vacío.

Precios fijos (se usan cuando no hay clave de API, para destinos fuera de Colombia y como alternativa cuando no hay cotización en vivo)

Prices by country: una lista de países con una columna Price y precios opcionales por tamaño de paquete, en tu moneda predeterminada, sin impuestos. El tamaño viene del peso del carrito: XS hasta 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg, XL más de 5 kg. Price se usa cuando la columna de tamaño es 0 o está vacía. Haz clic en Add country para añadir una fila; una fila nueva empieza con Colombia. El país * All other countries se aplica a los países sin fila propia. Un país sin fila (y sin *) no tiene precio fijo. Una fila con Price 0 y sin precio por tamaño da envío gratis.

Fixed price per: Order (por defecto) cobra el precio una vez. Item (price × quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo a los precios fijos; una cotización en vivo de Coordinadora siempre cubre el pedido completo.

Condiciones

Min weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (por defecto).

Max weight (kg): oculta el método por encima de este peso del carrito. Por defecto: 25 (también se usa cuando el campo está vacío). 0 significa sin límite.

Minimum order subtotal: muestra el método solo si el subtotal de los productos que necesitan envío (tras el cupón, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.

Free shipping: activa el envío gratis desde el subtotal de abajo.

Free shipping from: el subtotal (tras el cupón, antes de impuestos) a partir del cual el envío es gratis. Solo se usa cuando Free shipping está activado. En ese caso no se hace ninguna petición a la API.

Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Con una clase de impuesto, OpenCart añade el impuesto del envío sobre la tarifa. Elige No tax si tus precios o la cotización de Coordinadora ya incluyen impuestos.

Geo zone: ofrece Coordinadora solo para 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.

Countries: ofrece Coordinadora solo para estos países de destino. Déjalo vacío para permitir todos los países. Este límite se aplica junto con Geo zone.

Avanzado

Debug log: escribe los cálculos de tarifas en storage/logs/vfd_crd_debug.log.php (en OpenCart 4, system/storage/logs/vfd_crd_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API y los ajustes incompletos siempre se registran, incluso con esta opción desactivada. La clave de API y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_crd_debug.old.log.php y se empieza 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 los ajustes de Coordinadora, las cotizaciones en caché y los registros. Si está desactivado (por defecto), todo se conserva para una reinstalación.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de API no se exporta.

Import: pega un JSON exportado antes 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 mantiene.

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 Coordinadora. Si hay una Geo zone y la dirección está fuera de ella, Coordinadora no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso ni se incluyen en la cotización. El subtotal es el precio de los productos que necesitan envío, tras el 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. La extensión comprueba primero las condiciones: países permitidos, peso del carrito y subtotal mínimo del pedido. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna petición a Coordinadora.

Para una dirección en Colombia con clave de API, la extensión busca el código DANE de la ciudad de destino en este orden: un código DANE en el campo de ciudad (los módulos de finalización de compra colombianos de departamentos y ciudades lo escriben, por ejemplo MEDELLIN (ANT) (05001000)), un código postal de 8 dígitos o la lista integrada de capitales de departamento y unas 40 ciudades más grandes. Si la dirección tiene una región (departamento), una ciudad de la lista se comprueba contra ella. Se ignoran los acentos y las mayúsculas.

Después, la extensión envía a Coordinadora el código DANE de destino y cada producto con la ciudad de origen, su peso (kg), sus dimensiones (cm), su cantidad y su valor declarado (COP). El valor declarado es el total de la línea del producto antes de impuestos, tras el descuento del cupón. Las clases de peso y de longitud de los productos se convierten automáticamente. Coordinadora devuelve el precio en COP, y la extensión lo convierte a tu moneda predeterminada, lo redondea a los decimales de esa moneda y lo muestra en la moneda del cliente con el impuesto de la Tax class seleccionada. Cada cotización se guarda en caché durante 1 hora. Una petición fallida se recuerda durante 10 minutos, para que una caída de Coordinadora nunca ralentice cada actualización de la finalización de compra. El tiempo de espera de la API es de 10 segundos.

Cuando no hay cotización en vivo (error de la API, ciudad desconocida, un producto sin peso o dimensiones, ajustes incompletos), se usa el precio fijo. Si no hay ninguno, el método se oculta para ese carrito. Los detalles de los errores van al registro de depuración, nunca al cliente.

La extensión solo calcula tarifas. No crea envíos ni guías, no imprime etiquetas, no reserva recogidas, no hace seguimiento de paquetes, no cobra el dinero contra entrega (recaudo) ni ofrece puntos de recogida Droop; para ello usa el portal de Coordinadora. No añade nada a los pedidos: el pedido muestra el nombre del método y el coste de envío como cualquier otro método de envío de OpenCart. Los destinos internacionales usan los precios fijos.

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

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Coordinadora es el primer bloque en Extensions > Extensions > Shipping > VibeFox Coordinadora > 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-coordinadora y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso de modificación 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 contactar 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. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Coordinadora 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 admin 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 admin, así que sin una clave activa el método está oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del admin. 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 admin 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 a la semana. No se necesita ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Coordinadora no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Coordinadora esté activado. Revisa los avisos de la parte superior de la página de la extensión, Geo zone, Countries, los límites de peso y Minimum order subtotal. Sin cotización en vivo, debe existir un precio fijo para el país o para *. Comprueba que los productos tengan Requires Shipping en Yes.

La tarifa en vivo no se muestra, solo el precio fijo: activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Motivos habituales: la ciudad de destino no se reconoce, un producto no tiene peso o dimensiones, falta el código DANE de origen o el tipo de cambio a COP, o Coordinadora devolvió un error.

La ciudad de destino no se reconoce: instala un módulo de finalización de compra colombiano de departamentos y ciudades que escriba el código DANE en el campo de ciudad. Los desarrolladores pueden añadir más ciudades o cambiar la dirección de la API con los eventos de OpenCart vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane y vfd_coordinadora/api_url; la dirección de la API también se puede sustituir con el ajuste vfd_crd_api_url (para pruebas), que no tiene campo en la página de ajustes.

¿La tarifa incluye impuestos? La tarifa es la que cotiza Coordinadora. Con una Tax class, OpenCart añade el impuesto del envío sobre la tarifa; elige No tax si la cotización ya lo incluye.

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

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

Desinstalar

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Coordinadora. La clave de licencia y el estado de licencia de esta extensión se eliminan siempre. OpenCart siempre restablece Enable Coordinadora, Sort order, Tax class y Geo zone. Las cotizaciones en caché siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de Coordinadora y el registro también se borran. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensión. Los pedidos existentes conservan 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 después de desinstalarla y haz clic en Uninstall (el botón naranja −) junto a VibeFox Coordinadora en la lista de extensiones instaladas; después, haz clic en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Coordinadora es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Coordinadora.