VibeFox Coordinadora for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Clave API de Coordinadora (solo para cotizaciones en vivo): las cotizaciones en vivo provienen del Cotizador de Coordinadora a través del servicio Coordinadora WooCommerce, el mismo que usa el plugin oficial de Coordinadora. Coordinadora emite la clave API a los clientes con un acuerdo comercial activo. Consulta a tu gestor de cuenta de Coordinadora o visita 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 transportista funciona solo con precios fijos.

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

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca más tarde VibeFox Coordinadora en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).

4. Introduce la clave 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). Haz clic en Save.

5. Comprueba que Colombia esté activo en tu tienda y que tus productos tengan peso y dimensiones.

Al instalar, el módulo crea el transportista Coordinadora con el texto del plazo de entrega Courier delivery in Colombia. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No definas precios allí: el precio siempre proviene del módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Coordinadora > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las cotizaciones de Coordinadora en caché. Los números se pueden escribir con punto o con coma (9,99 = 9.99).

La página no se guarda y muestra un error cuando un número o un precio de la tabla no es válido o es negativo, cuando COP per 1 unit of store currency es 0, cuando Min weight es mayor que Max weight o cuando Name tiene más de 64 caracteres. No se guarda nada hasta que lo corrijas.

La página muestra avisos en la parte superior cuando las cotizaciones en vivo no pueden funcionar o el transportista quedaría oculto: Origin city (DANE code) está vacío o no es válido, falta COP per 1 unit of store currency mientras tu moneda predeterminada no es COP, o no hay precio fijo para Colombia (o *). Sin clave API y sin ese precio fijo, el transportista nunca se muestra para direcciones colombianas. También aparece un aviso cuando la unidad de peso o de dimensiones de la tienda en International > Localization (Local units) no es conocida por el módulo; en ese caso los pesos de los productos se leen como kg y las dimensiones como cm.

General

Enable Coordinadora: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Name: el nombre del transportista que ve el cliente en la compra. Predeterminado: Coordinadora. Obligatorio.

Tax: la regla de impuesto del transportista, o No tax. Con una regla, PrestaShop añade el impuesto de envío sobre la tarifa. Elige No tax si tus precios o la cotización de Coordinadora ya incluyen impuestos.

Tarifas en vivo de Coordinadora

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

API key: tu clave API de Coordinadora WooCommerce, proporcionada por 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ívalo y haz clic en Save para borrar la clave; el transportista usará entonces 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 de cambio también se usa para enviar el valor declarado en COP. Si lo dejas vacío, no se usan las tarifas en vivo. El tipo de cambio debe ser mayor que 0. Si tu moneda predeterminada es COP, déjalo vacío.

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

Precios por país: una tabla de países con una columna Price y precios opcionales por tamaño de paquete, en tu moneda predeterminada, sin impuestos. El tamaño depende del peso del carrito: XS hasta 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL más de 5 kg. Se usa Price cuando la columna de tamaño es 0 o está vacía. Haz clic en Add country para añadir una fila y en la cruz para eliminar una. El país * All other countries se aplica a los países que no tienen 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.

Precio fijo por: Order cobra el precio una sola 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: oculta el transportista por debajo de este peso del carrito, en kg. 0 significa sin límite.

Max weight: oculta el transportista por encima de este peso del carrito, en kg. Predeterminado: 25 (también se usa cuando el campo está vacío). 0 significa sin límite. No puede ser menor que Min weight.

Minimum order subtotal: muestra el transportista solo si el subtotal del carrito (después de descuentos, 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 indicado abajo.

Free shipping from: el subtotal del carrito (después de descuentos, 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 solicitud a la API.

Countries: ofrece Coordinadora solo para estos países de destino. Solo aparecen los países activos. Déjalo vacío para permitir todos los países de las zonas del transportista.

Avanzado

Debug log: escribe los cálculos de tarifas en logs/vfd_crd_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API y los ajustes incompletos siempre se registran, incluso si esta opción está desactivada. La clave API y las direcciones de los clientes nunca se registran.

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 el módulo se borran los ajustes de Coordinadora, el transportista, las tarifas en caché y los registros. Si está desactivado, se conserva todo para una nueva instalación.

Cómo funciona en la compra

En el paso de envío, PrestaShop pide al módulo el precio de Coordinadora. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en la cotización. El módulo 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 solicitud a Coordinadora.

Para una dirección en Colombia con clave API, el módulo 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 compra de departamentos y ciudades de Colombia lo escriben, por ejemplo MEDELLIN (ANT) (05001000)), un código postal de 8 dígitos o la lista integrada de capitales departamentales y unas 40 de las ciudades más grandes. Si la dirección tiene departamento (estado), la ciudad de la lista se compara con él. Se ignoran los acentos y las mayúsculas.

Después, el módulo 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 y antes de descuentos del carrito. Las unidades de la tienda se convierten automáticamente. Coordinadora devuelve el precio en COP, y el módulo lo convierte a tu moneda predeterminada y después a la moneda del carrito del cliente. Cada cotización se guarda en caché durante 1 hora. Una solicitud fallida se recuerda durante 10 minutos, así que una caída de Coordinadora nunca ralentiza cada actualización de la 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, producto sin peso o dimensiones, ajustes incompletos), se usa el precio fijo. Si no hay ninguno, el transportista se oculta para ese carrito. Los detalles de los errores se envían al registro de depuración, nunca al cliente.

Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue automáticamente la nueva versión.

El módulo solo calcula tarifas. No crea envíos ni guías (guías), no imprime etiquetas, no programa recogidas (recogidas), no rastrea paquetes, no cobra contraentrega (recaudo) ni ofrece puntos de recogida de Droop; para ello usa el portal de Coordinadora. Los destinos internacionales usan los precios fijos.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Coordinadora es el primer bloque de la página Modules > Module Manager > VibeFox Coordinadora > Configure, por encima de los ajustes. Introduce 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 quitar la clave de esta tienda. Debajo están la línea Product: presta-shipping-coordinadora y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. 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 transportista Coordinadora no se muestra a los clientes en la compra y no se calcula ninguna tarifa. El frontal de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Coordinadora no aparece en la compra: comprueba que la licencia esté activa y que Enable Coordinadora esté activado. En Shipping > Carriers, comprueba que el transportista cubre la zona del país del cliente y el grupo del cliente. Revisa 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 *. También se pueden limitar los productos a ciertos transportistas en la página del producto.

No se muestra la tarifa en vivo, solo el precio fijo: activa Debug log, recarga la compra y mira el campo Log en la página del módulo. 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 compra de departamentos y ciudades de Colombia que escriba el código DANE en el campo de ciudad. Los desarrolladores pueden asignar más ciudades con los hooks del módulo actionVfdCrdDaneCities y actionVfdCrdDestinationDane, o cambiar la dirección de la API con actionVfdCrdApiUrl.

¿La tarifa incluye impuestos? La tarifa es lo que cotiza Coordinadora. Con una regla de Tax, PrestaShop añade el impuesto de envío encima; 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 del módulo. Así se borran las cotizaciones en caché.

La página indica que no se encontró el transportista Coordinadora: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Coordinadora y elige Uninstall. La clave de licencia, el estado de la licencia y las cotizaciones en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se borra (los pedidos conservan su historial) y se eliminan los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, o con un Reset, el transportista guardado recupera el estado que tenía antes: un transportista que habías desactivado sigue desactivado.

Coordinadora es una marca comercial de su respectivo propietario. Este módulo no está afiliado ni respaldado por Coordinadora.