Comercial: cómo funciona

Comercial pone las reglas de dinero de tu tienda que no son el precio del producto: cuánto cuesta el envío a cada ciudad según el peso y el método de pago (contraentrega, transferencia o mixto), los recargos de la contraentrega y los beneficios, como un descuento de bienvenida o el envío gratis.

Es una calculadora: no guarda pedidos ni datos de clientes. Por API lo usas para cargar la tabla de tu transportadora, cotizar el envío de un pedido y saber qué beneficios aplican antes de crear la orden en Facturación.

También puedes hacerlo desde la consola: en el Estudio de un espacio con el módulo activo, el panel Comercial tiene las reglas de pago, los beneficios con su interruptor, la tabla de tarifas activa y el peso de cada producto.

Antes de empezar

• El espacio tiene que tener el módulo Comercial: comercial sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
• Leer (las rutas GET) vale con cualquier clave. Todo lo demás pide una clave escribe, también cotizar y evaluar beneficios: no cambian nada, pero son POST.
• Las rutas cuelgan de /api/mod/comercial/{espacio}/, con la misma clave y los mismos límites que el resto de la API. Si el módulo no responde en ese momento, la ruta da 502: reintenta.
• No gasta créditos: ninguna ruta del módulo descuenta de tu bolsa.

El recorrido

1. Revisa la configuración y cámbiala si hace falta: reglas de pago, peso de tus productos y beneficios.
2. Sube la tabla de tarifas de tu transportadora. Queda como borrador.
3. Mira sus n_ciudades, n_precios y warnings, y actívala.
4. Con cada pedido: mira qué beneficios aplican y cotiza el envío con la ciudad y el método de pago.
5. Crea la orden en Facturación con el total_envio, la tarifa_version y el descuento de la cotización.

La tabla de tarifas

Un libro de Excel (.xlsx, hasta 10 MB) con dos hojas. Se reconocen por el nombre: la que contiene «ciudad» y la que contiene «precio».

Nombre_Ciudad_origen | Nombre_Ciudad_destino | Codigo_Zona | Zona
MEDELLIN             | BOGOTA D.C.           | 2           | Nac
MEDELLIN             | ENVIGADO              | 1           | Loc
MEDELLIN             | RIONEGRO              | 3           | Zonal

• Obligatorias: Nombre_Ciudad_destino y Zona. La zona puede ir abreviada: Loc, Nac y Reg se leen como Local, Nacional y Regional.
• Opcionales: Codigo_Zona y Nombre_Ciudad_origen (la primera que aparezca es la ciudad_origen).
• Una fila cuyo nombre tiene más de seis dígitos (un teléfono pegado, por ejemplo) se descarta y sale en warnings.

Peso                          | Local | Regional | Nacional | Zonal | Otros
1 y 2 Kg                      | 7960  | 9900     | 12900    | 10900 | 18500
3 a 5 Kg                      | 9900  | 12400    | 14350    | 13200 | 22900
kg adicional entre 30 y 50 kg | 900   | 1100     | 1300     | 1200  | 1900

• El encabezado es la primera fila que tiene «peso», «local» y «nacional». Las columnas de zona que se leen son Local, Regional, Nacional, Zonal, Otros y Especial.
• La primera columna es el rango de peso; su último número es el tope en kilos («3 a 5 Kg» llega hasta 5). Las filas de «kg adicional» se guardan, pero no cuentan como rango.
• Los precios, sin símbolo ni separadores de miles.

draft → (activar) → activa → (activas otra) → retirada

Activar le da a la tabla la siguiente tarifa_version y retira la anterior. Una retirada no vuelve: para recuperarla, súbela otra vez.

Cómo se calcula el envío

1. El destino. Se busca la ciudad en la tabla activa, sin importar tildes ni mayúsculas; vale una dirección que empiece por la ciudad. Un municipio de Colombia que la tabla no lista cae en la zona Otros, si la tabla tiene precio para ella.
2. El peso. El peso_kg que mandes; si no, la suma de peso_sku de las líneas; si no, peso_default_pedido_kg. Si solo algunas líneas tienen peso, las demás se estiman con el peso medio de las conocidas.
3. La base. El primer rango cuyo tope alcanza el peso, en la columna de la zona. Si el peso pasa de todos, el rango mayor (y lo dice en notas).
4. El método de pago, con tus reglas_pago:

El total es subtotal + envío − descuento, nunca negativo. Con envio_gratis, el envío es 0 en cualquier método. Todas las cifras se redondean a unidades enteras.

Si no hay tarifa (la ciudad no está, su zona no tiene precio o no hay tabla activa), la cotización responde igual, con degradado: true y el motivo en notas. Ese envío no está calculado: no lo cobres, confírmalo a mano. Si la ciudad tiene un solo nombre muy parecido en la tabla, sale en ciudad_sugerida para que se lo preguntes al cliente.

Los beneficios

Un beneficio es una regla con condiciones y un efecto. Aplica si cumple todas sus condiciones:

• está activo;
• el método de pago está en metodos_pago (vacío: todos; sin método todavía, no se filtra);
• el subtotal llega a subtotal_min, si lo tiene;
• y, con solo_primera_compra, es la primera compra del cliente.

Su efecto es un descuento en porcentaje (descuento_pct), un descuento fijo (descuento_fijo, sin pasar del subtotal) o el envío gratis (envio_gratis). Comercial no sabe quién es el cliente: si no le dices si es su primera compra, los beneficios de primera compra salen igual y requiere_primera_compra te avisa de que los ofrezcas en condicional.

Con Productos, Ventas y Facturación

• Productos pone los precios: el precio_unitario de las líneas que mandas a cotizar sale de allí. Comercial no cambia precios.
• Ventas usa Comercial en el chat: cuando el cliente da su ciudad y elige cómo pagar, evalúa los beneficios, cotiza el envío, le enseña el desglose y crea la orden.
• Facturación guarda el resultado: la orden lleva envio = total_envio, la tarifa_version con la que se calculó y el descuento. Cambiar después la tabla o las reglas no toca las órdenes ya creadas.

Rutas