Productos: cómo funciona

Productos es el catálogo de tu espacio: qué vendes, a qué precio, con qué promociones y cuánto stock queda. Bentho consulta aquí esas cifras cuando atiende a tus clientes, en vez de inventarlas.

Por API mantienes el catálogo al día desde tu propio sistema, cotizas un carrito con sus descuentos, apartas stock mientras tu cliente paga y confirmas la venta para que las existencias bajen.

También puedes hacerlo desde la consola: en el Estudio de un espacio con el módulo activo, abre Productos. El panel permite crear productos, fijar su precio y su stock, cambiar su estado, importar un catálogo y gestionar listas de precios y promociones.

Antes de empezar

• El espacio tiene que tener el módulo Productos: productos sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
• Leer vale con cualquier clave. Todo lo que no es GET pide una clave escribe, también cotizar, que no cambia nada pero es un POST.
• Las rutas cuelgan de /api/mod/productos/{espacio}/, con la misma clave y los mismos límites que el resto de la API. Si el módulo no está disponible en ese momento, responde 502: reintenta en unos segundos.
• products/, product-types/ y catalog/imports/ llevan la barra final. Sin ella no responden con los datos.
• Productos no gasta créditos: ninguna de sus rutas descuenta de la bolsa.

Del alta a la venta, paso a paso

1. Crea el producto (o importa tu catálogo de un archivo). Nace en borrador, con su variante única.
2. Ponlo a la venta con {"estado": "activo"}: solo los activos salen en la búsqueda.
3. Crea una lista de precios y fija el precio de cada variante en ella.
4. Fija su stock, o súbelo de un archivo.
5. Cuando un cliente compra: cotiza el carrito, reserva lo que lleva mientras paga y, al cobrar, confirma la venta con las promociones que se aplicaron.

POST …/price-quote             → total, adjustments, catalog_version
POST …/inventory/reservations  → id de la reserva (15 min por defecto)
POST …/inventory/sale          { lines: [{ variant_id, cantidad, reservation_id }],
                                 sale_ref, promociones_aplicadas }

Productos, variantes y tipos

• Un producto es lo que ves en la carta: «Café molido La Loma 500 g». Tiene nombre, descripción, imágenes (URL), atributos y un estado.
• Una variante es lo que se vende: tiene su SKU, su precio y su stock. Un producto sin opciones tiene una sola; uno con opciones («Molienda»: en grano o molido) tiene una por combinación, que añades con Crea una variante.
• Un tipo de producto («Café», «Repuesto», «Plan») dice qué atributos llevan sus productos y cuáles son obligatorios. Es opcional: sin tipo, los atributos son libres.

borrador → activo → archivado
(cualquiera se cambia con PATCH products/{producto})

borrador   recién creado; no sale en la búsqueda
activo     a la venta; sale en la búsqueda
archivado  retirado; se conserva, no sale en la búsqueda

Importar desde un archivo

Sube un CSV, un Excel (.xlsx) o un PDF con una tabla a importar. Queda en draft: revisa sus filas en la importación, descarta las que sobren y actívala. Hasta entonces el catálogo no cambia.

• Hace falta una columna de nombre o una de SKU. Los encabezados no distinguen tildes ni mayúsculas, y el CSV puede ir separado por comas o por punto y coma.
• Los precios se leen en formato colombiano: $45.000 es 45000 y 12,5 es 12.5.
• Cada fila activada crea un producto nuevo y activo. Activar dos veces el mismo archivo duplica el catálogo.
• El precio del archivo no se cobra: queda en metadata.precio_sugerido para que lo pases a una lista con Fija un precio.
• Un .xls antiguo no se lee: guárdalo como .xlsx o como CSV. Hasta 25 MB por archivo.

Cómo se elige un precio

Los precios viven en listas. Una variante puede tener precio en varias (la de la tienda, una oferta de temporada, uno puntual) y en varios escalones de cantidad. Al cotizar, entre los precios que valen para esa línea —lista activa y vigente en la fecha, misma moneda, min_qty no mayor que la cantidad— gana:

1. El de la lista con más prioridad.
2. A igual prioridad, por tipo de lista: override, luego oferta, luego base.
3. Luego el escalón más alto que aplica (min_qty 12 antes que 1 si compran 12).
4. Luego el monto más bajo.

• Fijar un precio añade otro; no reemplaza el anterior. Para cambiarlo, borra el viejo: si no, con el mismo escalón y en la misma lista gana el más bajo.
• Una variante sin precio vigente no se cobra a 0: sale en no_cotizados.
• Cada cotización trae catalog_version, una huella de los precios, promociones y catálogo con que se calculó. Guárdala con el pedido.
• Importes y cantidades viajan como texto decimal: «32000», «1.5».

Promociones

Una promoción es una regla: cuándo aplica (predicado) y cuánto descuenta (metodo). Se aplica sola en cada cotización que la cumple; cada descuento sale en el adjustments de su línea.

{
  "nombre": "10 % de bienvenida",
  "codigo": "BIENVENIDA",
  "predicado": {
    "op": "and",
    "clauses": [
      { "field": "codigos_promo", "cmp": "contains", "value": "BIENVENIDA" },
      { "field": "subtotal", "cmp": "gte", "value": 50000 }
    ]
  },
  "metodo": { "metodo": "percentage", "target": "order", "valor": 10 }
}

• El codigo es solo una etiqueta. Para que la promoción pida el código, ponlo en el predicado como arriba, y manda en la cotización los codigos_promo que escribió tu cliente.
• El predicado mira subtotal, cantidad_total, variant_ids, codigos_promo y canal. Vacío, aplica siempre.
• target: "item" rebaja líneas; si el predicado nombra variantes con variant_ids contains, solo esas. target: "order" rebaja el subtotal y se aplica después de las de línea.
• Las de un mismo grupo_exclusividad no se suman: aplica la de mayor prioridad. Las que no tienen grupo se suman todas.
• limite_usos y el presupuesto de una campaña solo avanzan cuando confirmas una venta declarando promociones_aplicadas. Cotizar no gasta usos.
• Una promoción no se edita ni se pausa por la API: para cambiarla o pararla, bórrala y, si hace falta, créala de nuevo.

Stock, reservas y ventas

• El stock es por variante y por bodega (texto vacío: la única). Disponible es stocked − reserved, nunca menos de 0.
• Fijar pone las existencias en absoluto; ajustar suma o resta. Subir un archivo o sincronizar con tu software contable fija, cruzando por SKU. El archivo necesita una columna de cantidad (cantidad, stock, existencias, disponible, inventario, unidades, saldo, qty) y una de SKU; admite también unidad, bodega y umbral (mínimo, reorden).
• Una reserva aparta unidades durante ttl_s segundos (por defecto 15 minutos). Al vencer, vuelven solas.
• Confirmar la venta descuenta todo de una vez. Pasa el reservation_id en la línea si la reservaste y un sale_ref por pedido: repetir la llamada no descuenta dos veces.
• La disponibilidad responde no_rastreado si la variante no tiene stock cargado: no es un «no hay». Si tu negocio no controla stock, apágalo en la configuración.
• Los cambios de precios, promociones y stock los usa Bentho en sus respuestas siguientes.

activa → liberada    (DELETE inventory/reservations/{reserva})
       → consumida   (venta con su reservation_id)
       → expirada    (venció ttl_s; el stock vuelve solo)

Rutas