gufi-cli 0.1.49 → 0.1.51

package/docs/mcp/06-api.md

@@ -0,0 +1,531 @@
+# API Reference
+
+Endpoints principales del backend de Gufi.
+
+## Autenticacion
+
+### Login
+
+```
+POST /api/auth/login
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+
+Response:
+{
+  "accessToken": "eyJ...",
+  "refreshToken": "abc...",
+  "user": { "id": 16, "email": "...", "name": "..." }
+}
+```
+
+### Refresh token
+
+```
+POST /api/auth/refresh
+Headers:
+  X-Refresh-Token: {refreshToken}
+
+Response:
+{
+  "accessToken": "eyJ...",
+  "refreshToken": "abc..."
+}
+```
+
+### Headers requeridos
+
+```
+Authorization: Bearer {accessToken}
+X-Company-ID: {companyId}
+Content-Type: application/json
+```
+
+## Companies
+
+### Listar companies
+
+```
+GET /api/companies
+
+Response:
+{
+  "items": [
+    { "id": 116, "name": "Mi Empresa", "created_at": "..." }
+  ]
+}
+```
+
+### Schema de company
+
+```
+GET /api/company/schema
+
+Response:
+{
+  "modules": [
+    {
+      "id": 360,
+      "name": "Ventas",
+      "submodules": [...]
+    }
+  ]
+}
+```
+
+## Modules
+
+### Listar modulos
+
+```
+GET /api/company/modules
+
+Response:
+[
+  { "id": 360, "name": "ventas", "displayName": "Ventas", "entity_count": 3 }
+]
+```
+
+### Obtener modulo
+
+```
+GET /api/company/modules/{moduleId}
+
+Response:
+{
+  "id": 360,
+  "name": "ventas",
+  "json_definition": {...}
+}
+```
+
+### Actualizar modulo
+
+```
+PUT /api/company/modules/{moduleId}
+{
+  "json_definition": {...}
+}
+```
+
+### Crear modulo
+
+```
+POST /api/company/modules
+{
+  "json_definition": {...}
+}
+```
+
+## Tables (CRUD generico)
+
+### Listar registros
+
+```
+POST /api/tables/{tableName}/list
+{
+  "page": 1,
+  "perPage": 20,
+  "sorters": [{ "field": "created_at", "order": "desc" }],
+  "filter": [
+    { "field": "estado", "operator": "eq", "value": "pendiente" }
+  ]
+}
+
+Response:
+{
+  "data": [...],
+  "meta": { "page": 1, "perPage": 20, "hasMore": true }
+}
+```
+
+> **IMPORTANTE**: La paginacion usa `page` y `perPage` directamente en el body,
+> NO `pagination: { current, pageSize }`. Usar el formato incorrecto hace que
+> la API ignore la paginacion y siempre devuelva la primera pagina.
+
+### Obtener registro
+
+```
+POST /api/tables/{tableName}/getOne
+{
+  "id": 123
+}
+
+Response:
+{
+  "data": { "id": 123, "nombre": "...", ... }
+}
+```
+
+### Crear registro
+
+```
+POST /api/tables/{tableName}
+{
+  "nombre": "Nuevo",
+  "precio": 150,
+  "estado": "pendiente"
+}
+
+Response (objeto directamente, NO envuelto en data):
+{ "id": 124, "nombre": "Nuevo", "precio": 150, ... }
+```
+
+> **IMPORTANTE**: El endpoint de crear devuelve el objeto directamente,
+> NO envuelto en `{ data: {...} }`. Verificar con `'id' in response`, no `'data' in response`.
+
+### Actualizar registro
+
+```
+PUT /api/tables/{tableName}/{id}
+{
+  "estado": "completado",
+  "estado__display": "Completado"
+}
+```
+
+### Eliminar registro
+
+```
+DELETE /api/tables/{tableName}/{id}
+```
+
+### Eliminar multiples
+
+```
+POST /api/tables/{tableName}/deleteMany
+{
+  "ids": [1, 2, 3]
+}
+```
+
+## Agregaciones (Analytics)
+
+Usar `gufi_data` con `action: 'aggregate'` para métricas y agregaciones.
+
+### Count total
+
+```javascript
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'count',
+  company_id: '146'
+})
+
+// Response: { value: 1250 }
+```
+
+### Sum, Avg, Min, Max
+
+```javascript
+// Suma total de ventas
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  company_id: '146'
+})
+
+// Precio promedio
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.productos',
+  agg: 'avg',
+  field: 'precio',
+  company_id: '146'
+})
+```
+
+### Group By
+
+```javascript
+// Ventas por cliente
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  groupBy: 'cliente_id',
+  limit: 10,
+  company_id: '146'
+})
+
+// Response:
+// { results: [
+//   { group: 'cliente_123', value: 15000 },
+//   { group: 'cliente_456', value: 12500 },
+//   ...
+// ]}
+```
+
+### Con filtros simples
+
+```javascript
+// Filtrar por campo = valor
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  filter: 'estado=completado',
+  company_id: '146'
+})
+```
+
+### Con filtros de fecha
+
+```javascript
+// Ventas del último mes
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  groupBy: 'cliente_id',
+  dateField: 'fecha_venta',
+  dateFrom: '2025-12-26T00:00:00Z',
+  dateTo: '2026-01-26T23:59:59Z',
+  company_id: '146'
+})
+
+// Top 10 máquinas por ventas del mes
+gufi_data({
+  action: 'aggregate',
+  table: 'nayax.machine_sales',
+  agg: 'sum',
+  field: 'settlement_value',
+  groupBy: 'machine_id',
+  dateField: 'settlement_datetime_gmt',
+  dateFrom: '2025-12-26T00:00:00Z',
+  dateTo: '2026-01-26T23:59:59Z',
+  company_id: '116'
+})
+```
+
+**Parámetros de fecha:**
+- `dateField`: Campo de fecha para filtrar (requerido para filtros de fecha)
+- `dateFrom`: Fecha inicio (ISO string, inclusive >=)
+- `dateTo`: Fecha fin (ISO string, inclusive <=)
+
+### Agregaciones disponibles
+
+| agg | Descripcion | Requiere field |
+|-----|-------------|----------------|
+| `count` | Cuenta registros | No (opcional) |
+| `sum` | Suma valores | Sí |
+| `avg` | Promedio | Sí |
+| `min` | Valor mínimo | Sí |
+| `max` | Valor máximo | Sí |
+
+## Automations
+
+### Listar scripts
+
+```
+GET /api/automation-scripts
+
+Response:
+[
+  { "id": 15, "name": "mi_script", "company_id": 116 }
+]
+```
+
+### Obtener script
+
+```
+GET /api/automation-scripts/{name}
+
+Response:
+{
+  "id": 15,
+  "name": "mi_script",
+  "js_code": "async function...",
+  "description": "..."
+}
+```
+
+### Crear/actualizar script
+
+```
+PUT /api/automation-scripts/{name}
+{
+  "js_code": "async function mi_script(gufi) {...}",
+  "description": "Descripcion"
+}
+```
+
+### Trigger click automation
+
+```
+POST /api/automation-scripts/triggerClick
+{
+  "table": "m360_t16192",
+  "row_id": 123,
+  "function_name": "generar_pdf",
+  "input": { "formato": "A4" }
+}
+```
+
+### Ver executions
+
+```
+GET /api/automation-executions?limit=20&script_name=mi_script
+
+Response:
+[
+  {
+    "id": 456,
+    "script_name": "mi_script",
+    "status": "completed",
+    "duration_ms": 234,
+    "created_at": "..."
+  }
+]
+```
+
+## Marketplace
+
+### Mis packages
+
+```
+GET /api/marketplace/developer/packages
+
+Response:
+[
+  { "id": 14, "name": "Mi Package", "version": "1.0.0", "published": true }
+]
+```
+
+### Detalle package
+
+```
+GET /api/marketplace/packages/{packageId}
+
+Response:
+{
+  "id": 14,
+  "name": "Mi Package",
+  "modules": [...],
+  "views": [...]
+}
+```
+
+### Archivos de vista
+
+```
+GET /api/marketplace/views/{viewId}/files
+
+Response:
+{
+  "files": [
+    { "path": "index.tsx", "content": "...", "language": "typescript" }
+  ]
+}
+```
+
+### Actualizar archivos
+
+```
+PUT /api/marketplace/views/{viewId}/files
+{
+  "files": [
+    { "path": "index.tsx", "content": "..." }
+  ]
+}
+```
+
+## Files
+
+### Upload
+
+```
+POST /api/files/upload
+Content-Type: multipart/form-data
+
+FormData:
+  file: (binary)
+
+Response:
+{
+  "url": "company_116/abc123_file.pdf",
+  "name": "documento.pdf",
+  "size": 12345,
+  "mime": "application/pdf"
+}
+```
+
+### Download
+
+```
+GET /api/files/download?path=company_116/abc123_file.pdf
+```
+
+## Environment Variables
+
+### Listar
+
+```
+GET /api/cli/env
+
+Response:
+[
+  { "key": "SLACK_WEBHOOK", "is_secret": true },
+  { "key": "PUBLIC_URL", "is_secret": false, "value": "https://..." }
+]
+```
+
+### Crear/actualizar
+
+```
+POST /api/cli/env
+{
+  "key": "NEW_API_KEY",
+  "value": "sk-..."
+}
+```
+
+### Eliminar
+
+```
+DELETE /api/cli/env/{key}
+```
+
+## Operadores de filtro
+
+Para usar en `/api/tables/{table}/list`:
+
+| Operador | Descripcion | Ejemplo |
+|----------|-------------|---------|
+| `eq` | Igual | `{ "field": "estado", "operator": "eq", "value": "activo" }` |
+| `ne` | No igual | `{ "field": "estado", "operator": "ne", "value": "cancelado" }` |
+| `gt` | Mayor que | `{ "field": "total", "operator": "gt", "value": 100 }` |
+| `gte` | Mayor o igual | `{ "field": "total", "operator": "gte", "value": 100 }` |
+| `lt` | Menor que | `{ "field": "total", "operator": "lt", "value": 1000 }` |
+| `lte` | Menor o igual | `{ "field": "total", "operator": "lte", "value": 1000 }` |
+| `contains` | Contiene texto | `{ "field": "nombre", "operator": "contains", "value": "juan" }` |
+| `in` | En lista | `{ "field": "estado", "operator": "in", "value": ["a", "b"] }` |
+| `null` | Es nulo | `{ "field": "deleted_at", "operator": "null", "value": true }` |
+
+## Codigos de error
+
+| Codigo | Significado |
+|--------|-------------|
+| 400 | Bad Request - Parametros invalidos |
+| 401 | Unauthorized - Token invalido/expirado |
+| 403 | Forbidden - Sin permisos |
+| 404 | Not Found - Recurso no existe |
+| 409 | Conflict - Ya existe |
+| 429 | Too Many Requests - Rate limit |
+| 500 | Internal Server Error |
+
+## Rate limits
+
+Por defecto (configurables):
+- Login: 5 intentos/minuto
+- Uploads: 20/minuto
+- AI: 10/minuto
+- General: 100/minuto