Sales Bot - Sistema de Automatización de Ventas

Sistema integral de automatización de ventas que integra Mattermost, NocoDB y procesamiento OCR para gestionar ventas, comisiones y metas de vendedores.

Descripción General

Sales Bot es una solución completa para equipos de ventas que permite:

• Registro automático de ventas via chat (Mattermost)
• Procesamiento OCR de tickets/facturas
• Gestión de vendedores y metas
• Cálculo automático de comisiones por tubos de tinte
• Reportes y ranking de vendedores

Stack Tecnológico

Componente	Tecnología
Backend	Python 3.12 + Flask + Gunicorn
Chat	Mattermost Team Edition
Base de Datos	NocoDB + PostgreSQL
OCR	Tesseract (inglés/español)
Visión	OpenCV, Pillow, NumPy
Infraestructura	Docker Compose

Estructura del Proyecto

stacks/
├── mattermost/           # Stack de Mattermost (chat empresarial)
│   └── compose.yaml
├── nocodb/               # Stack de NocoDB (base de datos visual)
│   └── compose.yaml
└── sales-bot/            # Aplicación principal del bot
    ├── app.py            # Aplicación Flask principal
    ├── handlers.py       # Manejadores de eventos de ventas
    ├── mattermost_client.py    # Cliente API de Mattermost
    ├── nocodb_client.py        # Cliente API de NocoDB
    ├── ocr_processor.py        # Procesador OCR para tickets
    ├── websocket_listener.py   # Listener WebSocket
    ├── utils.py          # Utilidades
    ├── Dockerfile
    ├── compose.yaml
    ├── requirements.txt
    └── .env

Servicios

Mattermost (Puerto 8065)

Plataforma de mensajería empresarial donde los vendedores reportan sus ventas.

NocoDB (Puerto 8080)

Base de datos visual con interfaz web para gestionar:

• Vendedores
• Ventas
• Detalles de productos
• Metas

Sales Bot (Puerto 5000)

Aplicación principal que orquesta todo el sistema.

Instalación

Requisitos Previos

• Docker y Docker Compose
• Acceso a red local (192.168.10.204)

Despliegue

1. Iniciar Mattermost:

cd mattermost
docker compose up -d

2. Iniciar NocoDB:

cd nocodb
docker compose up -d

3. Iniciar Sales Bot:

cd sales-bot
docker compose up -d

Configuración

Variables de Entorno (.env)

# Mattermost
MATTERMOST_URL=http://192.168.10.204:8065
MATTERMOST_BOT_TOKEN=<tu_token>
MATTERMOST_TEAM_NAME=sales
MATTERMOST_WEBHOOK_SECRET=<tu_secret>
MATTERMOST_WEBHOOK_URL=http://192.168.10.204:8065/hooks/<hook_id>

# NocoDB
NOCODB_URL=http://192.168.10.204:8080
NOCODB_TOKEN=<tu_token>
NOCODB_TABLE_VENDEDORES=<table_id>
NOCODB_TABLE_VENTAS=<table_id>
NOCODB_TABLE_VENTAS_DETALLE=<table_id>
NOCODB_TABLE_METAS=<table_id>

# Flask
FLASK_PORT=5000
FLASK_DEBUG=False
LOG_LEVEL=INFO
TZ_OFFSET=-6

Uso

Registrar una Venta

En Mattermost, envía un mensaje con el formato:

venta @monto 1500 @cliente Juan

Opcionalmente adjunta una foto del ticket para procesamiento OCR automático.

Comandos Slash

Comando	Descripción
/metas	Muestra progreso de meta del vendedor
/ranking	Muestra ranking de vendedores

API Endpoints

Endpoint	Método	Descripción
/health	GET	Health check del servicio
/webhook/mattermost	POST	Webhook para mensajes de Mattermost
/webhook/nocodb	POST	Webhook para eventos de NocoDB
/comando/metas	POST	Comando slash /metas
/comando/ranking	POST	Comando slash /ranking

Sistema de Comisiones

• Meta diaria: 3 tubos de tinte
• Comisión: $10 MXN por cada tubo después del tercero

Ejemplo:

• Vendedor vende 5 tubos → Comisión: (5-3) × $10 = $20

Flujo de Operación

Vendedor envía mensaje + foto
        ↓
Webhook → Sales Bot
        ↓
Extracción de datos (monto, cliente)
        ↓
OCR de imagen (productos, fecha, monto)
        ↓
Validación (tolerancia ±5%)
        ↓
Registro en NocoDB
        ↓
Cálculo de comisiones
        ↓
Respuesta en Mattermost con confirmación

Tablas en NocoDB

Tabla	Descripción
Vendedores	Información de vendedores, metas
Ventas	Registro de ventas (monto, cliente, fecha)
Ventas Detalle	Productos por venta (marca, cantidad, precio)
Metas	Metas mensuales y diarias

Monitoreo

Logs

Los logs se almacenan en sales-bot/logs/sales-bot.log

Health Check

curl http://localhost:5000/health

Desarrollo

Requisitos

pip install -r requirements.txt

Ejecución Local

cd sales-bot
python app.py

Características

• OCR robusto con múltiples configuraciones PSM
• Validación de montos con tolerancia del 5%
• Detección automática de tubos de tinte
• Respuestas con emojis motivacionales
• Health checks en todos los servicios
• Contenedor con usuario no-root
• Persistencia de datos en volúmenes Docker

Licencia

Proyecto privado - Consultoría AS

Contacto

Consultoría AS - https://consultoria-as.com