Commit inicial: Sales Bot - Sistema de Automatización de Ventas
- Stack completo con Mattermost, NocoDB y Sales Bot - Procesamiento OCR de tickets con Tesseract - Sistema de comisiones por tubos de tinte - Comandos slash /metas y /ranking - Documentación completa del proyecto Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
329
docs/API.md
Normal file
329
docs/API.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user