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.

```http
GET /health
```

**Respuesta exitosa (200):**
```json
{
  "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.

```http
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):**
```json
{
  "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):**
```json
{
  "error": "Token inválido"
}
```

---

### Webhook NocoDB

Recibe webhooks de NocoDB cuando hay cambios en las tablas.

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

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

---

### Comando /metas

Muestra el progreso de metas del vendedor.

```http
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:**
```json
{
  "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.

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

**Parámetros:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| channel_id | string | ID del canal |

**Respuesta:**
```json
{
  "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
```http
xc-token: <API_TOKEN>
```

---

### Listar Vendedores

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

**Respuesta:**
```json
{
  "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

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

**Body:**
```json
{
  "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:**
```json
{
  "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

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

---

### Obtener Ranking

```http
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
```http
Authorization: Bearer <BOT_TOKEN>
```

---

### Enviar Mensaje

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

**Body:**
```json
{
  "channel_id": "abc123",
  "message": "Mensaje de texto"
}
```

---

### Agregar Reacción

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

**Body:**
```json
{
  "user_id": "user123",
  "post_id": "post123",
  "emoji_name": "white_check_mark"
}
```

---

### Obtener Archivo

```http
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