sales-bot-stacks/docs/API.md

Documentación de API

Sales Bot API

Base URL

http://192.168.10.204:5000

---

Endpoints

Health Check

Verifica el estado del servicio.

GET /health

Respuesta exitosa (200):

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:45.123456",
  "version": "1.0.0",
  "services": {
    "mattermost": "connected",
    "nocodb": "connected"
  }
}

---

Webhook Mattermost

Recibe webhooks salientes de Mattermost cuando se envía un mensaje de venta.

POST /webhook/mattermost
Content-Type: application/x-www-form-urlencoded

Parámetros:

Campo	Tipo	Descripción
token	string	Token de verificación del webhook
team_id	string	ID del team
team_domain	string	Dominio del team
channel_id	string	ID del canal
channel_name	string	Nombre del canal
timestamp	number	Timestamp del mensaje
user_id	string	ID del usuario
user_name	string	Nombre de usuario
post_id	string	ID del post
text	string	Texto del mensaje
file_ids	string	IDs de archivos adjuntos (separados por coma)

Respuesta exitosa (200):

{
  "response_type": "comment",
  "text": "✅ Venta registrada correctamente\n\n**Monto:** $1,500.00\n**Cliente:** Juan Pérez\n**Vendedor:** @vendedor1\n\n📊 **Estadísticas del día:**\n- Tubos vendidos: 5\n- Meta diaria: 3\n- Comisión: $20.00"
}

Error (400):

{
  "error": "Token inválido"
}

---

Webhook NocoDB

Recibe webhooks de NocoDB cuando hay cambios en las tablas.

POST /webhook/nocodb
Content-Type: application/json

Payload:

{
  "type": "records.after.insert",
  "data": {
    "table_name": "Ventas",
    "rows": [...]
  }
}

---

Comando /metas

Muestra el progreso de metas del vendedor.

POST /comando/metas
Content-Type: application/x-www-form-urlencoded

Parámetros:

Campo	Tipo	Descripción
user_name	string	Nombre de usuario que ejecuta el comando
channel_id	string	ID del canal

Respuesta:

{
  "response_type": "ephemeral",
  "text": "📊 **Tus metas - Enero 2024**\n\n**Tubos vendidos hoy:** 5/3 ✅\n**Comisión del día:** $20.00\n\n**Mes actual:**\n- Total tubos: 45\n- Comisión acumulada: $150.00\n- Total vendido: $15,000.00"
}

---

Comando /ranking

Muestra el ranking de vendedores.

POST /comando/ranking
Content-Type: application/x-www-form-urlencoded

Parámetros:

Campo	Tipo	Descripción
channel_id	string	ID del canal

Respuesta:

{
  "response_type": "in_channel",
  "text": "🏆 **Ranking de Vendedores - Enero 2024**\n\n1. 🥇 @vendedor1 - $25,000.00 (75 tubos)\n2. 🥈 @vendedor2 - $20,000.00 (60 tubos)\n3. 🥉 @vendedor3 - $15,000.00 (45 tubos)"
}

---

NocoDB API

Base URL

http://192.168.10.204:8080/api/v2

Autenticación

xc-token: <API_TOKEN>

---

Listar Vendedores

GET /tables/{TABLE_ID}/records
xc-token: <TOKEN>

Respuesta:

{
  "list": [
    {
      "Id": 1,
      "username": "vendedor1",
      "nombre_completo": "Juan Pérez",
      "email": "juan@ejemplo.com",
      "meta_diaria_tubos": 3,
      "activo": true,
      "fecha_registro": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pageInfo": {
    "totalRows": 1,
    "page": 1,
    "pageSize": 25
  }
}

---

Crear Venta

POST /tables/{TABLE_ID}/records
xc-token: <TOKEN>
Content-Type: application/json

Body:

{
  "vendedor_username": "vendedor1",
  "monto": 1500.00,
  "cliente": "Juan Pérez",
  "fecha_venta": "2024-01-15T10:30:00.000Z",
  "estado": "completada",
  "canal": "ventas-general",
  "mensaje_id": "abc123",
  "descripcion": "Venta de tintes"
}

Respuesta:

{
  "Id": 1,
  "vendedor_username": "vendedor1",
  "monto": 1500.00,
  "cliente": "Juan Pérez",
  "fecha_venta": "2024-01-15T10:30:00.000Z",
  "estado": "completada",
  "canal": "ventas-general",
  "mensaje_id": "abc123",
  "descripcion": "Venta de tintes"
}

---

Filtrar Ventas por Fecha

GET /tables/{TABLE_ID}/records?where=(fecha_venta,gte,2024-01-15)~and(fecha_venta,lt,2024-01-16)
xc-token: <TOKEN>

---

Obtener Ranking

GET /tables/{TABLE_ID}/records?sort=-monto&limit=10
xc-token: <TOKEN>

---

Mattermost API

Base URL

http://192.168.10.204:8065/api/v4

Autenticación

Authorization: Bearer <BOT_TOKEN>

---

Enviar Mensaje

POST /posts
Authorization: Bearer <TOKEN>
Content-Type: application/json

Body:

{
  "channel_id": "abc123",
  "message": "Mensaje de texto"
}

---

Agregar Reacción

POST /reactions
Authorization: Bearer <TOKEN>
Content-Type: application/json

Body:

{
  "user_id": "user123",
  "post_id": "post123",
  "emoji_name": "white_check_mark"
}

---

Obtener Archivo

GET /files/{file_id}
Authorization: Bearer <TOKEN>

---

Códigos de Error

Código	Descripción
200	Éxito
400	Solicitud inválida
401	No autorizado
403	Prohibido
404	No encontrado
500	Error interno del servidor

Rate Limiting

• Sales Bot: Sin límite interno
• Mattermost: 10 requests/segundo por usuario
• NocoDB: 100 requests/minuto por token