analiticaNucleo/METABASE_API_ENDPOINTS.md

🔌 REPORTE DE ENDPOINTS API DE METABASE

Fecha: 2025-10-14 Instancia: metabase.nucleoriofrio.com Autenticación: X-API-KEY header Formato: JSON

---

📋 ENDPOINTS PRINCIPALES

🎯 CARDS (Questions/Queries)

Estos son los endpoints MÁS IMPORTANTES para nuestro caso, ya que trabajaremos con las 9 queries documentadas.

Método	Endpoint	Descripción
GET	/api/card	Listar todas las cards/preguntas
GET	/api/card/:id	Obtener detalles de una card específica
POST	/api/card	Crear una nueva card
PUT	/api/card/:id	Actualizar una card existente
DELETE	/api/card/:id	Eliminar una card
POST	/api/card/:id/query	⭐ EJECUTAR una query y obtener resultados
GET	/api/card/:id/query	Ejecutar query con caché
GET	/api/card/:id/query/:export-format	Exportar resultados (csv, json, xlsx)

💡 Endpoint clave: /api/card/:id/query - Este lo usaremos para ejecutar las 9 queries con parámetros.

---

🗄️ DATABASE

Método	Endpoint	Descripción
GET	/api/database	Listar todas las bases de datos
GET	/api/database/:id	Obtener detalles de una BD
POST	/api/database	Crear conexión a BD
PUT	/api/database/:id	Actualizar conexión
POST	/api/database/:id/sync_schema	Sincronizar esquema
GET	/api/database/:id/metadata	Obtener metadata de tablas/campos
POST	/api/database/validate	Validar conexión antes de guardar

---

📊 DATASET (Queries Ad-hoc)

Endpoints para ejecutar queries SQL nativas sin crear cards.

Método	Endpoint	Descripción
POST	/api/dataset	⭐ Ejecutar query SQL nativa directamente
POST	/api/dataset/:export-format	Ejecutar y exportar (csv, json, xlsx)

💡 Uso importante: Podemos usar /api/dataset para probar queries SQL antes de crearlas como cards.

Ejemplo de payload:

{
  "database": 2,
  "type": "native",
  "native": {
    "query": "SELECT * FROM vista_detalle_ingresos LIMIT 10",
    "template-tags": {}
  }
}

---

📁 COLLECTION

Método	Endpoint	Descripción
GET	/api/collection	Listar colecciones
GET	/api/collection/:id	Detalles de colección
GET	/api/collection/:id/items	Items dentro de colección
POST	/api/collection	Crear colección
PUT	/api/collection/:id	Actualizar colección

---

📈 DASHBOARD

Método	Endpoint	Descripción
GET	/api/dashboard	Listar dashboards
GET	/api/dashboard/:id	Detalles de dashboard
POST	/api/dashboard	Crear dashboard
PUT	/api/dashboard/:id	Actualizar dashboard
POST	/api/dashboard/:id/cards	Agregar card a dashboard
GET	/api/dashboard/:id/params/:param-key/values	Valores para parámetro

---

🔍 TABLE & FIELD

Método	Endpoint	Descripción
GET	/api/table/:id	Detalles de tabla
GET	/api/table/:id/query_metadata	Metadata completa de tabla
GET	/api/field/:id	Detalles de campo
POST	/api/field/:id/values	Valores únicos de un campo

---

👤 USER & SESSION

Método	Endpoint	Descripción
GET	/api/user/current	Usuario autenticado actual
GET	/api/user	Listar usuarios
POST	/api/session	Login (crear sesión)
DELETE	/api/session	Logout

---

⚙️ SETTINGS

Método	Endpoint	Descripción
GET	/api/setting	Obtener configuraciones
PUT	/api/setting/:key	Actualizar configuración

---

🔐 PERMISSIONS

Método	Endpoint	Descripción
GET	/api/permissions/graph	Ver árbol de permisos
PUT	/api/permissions/graph	Actualizar permisos
GET	/api/permissions/group	Listar grupos

---

📤 UPLOAD (Anteriormente CSV)

Método	Endpoint	Descripción
POST	/api/upload/csv	Subir CSV como tabla

---

📧 NOTIFICATION (Reemplaza Pulse/Alert)

Método	Endpoint	Descripción
GET	/api/notification	Listar notificaciones
POST	/api/notification	Crear notificación
PUT	/api/notification/:id	Actualizar notificación

---

🔧 UTIL & ANALYTICS

Método	Endpoint	Descripción
GET	/api/analytics/anonymous-stats	Estadísticas de uso (antes /util/stats)
GET	/api/util/logs	Logs del sistema
POST	/api/util/password_check	Validar contraseña

---

🎯 ENDPOINTS CRÍTICOS PARA NUESTRO PROYECTO

1. Ejecutar queries con parámetros

POST /api/card/:id/query
Content-Type: application/json
X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=

{
  "parameters": [
    {"type": "date/single", "target": ["variable", ["template-tag", "fecha_desde"]], "value": "2025-01-01"},
    {"type": "date/single", "target": ["variable", ["template-tag", "fecha_hasta"]], "value": "2025-12-31"},
    {"type": "category", "target": ["variable", ["template-tag", "incluir_anulados"]], "value": false}
  ]
}

2. Ejecutar SQL nativa directamente

POST /api/dataset
Content-Type: application/json
X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=

{
  "database": 2,
  "type": "native",
  "native": {
    "query": "SELECT COALESCE(SUM(...), 0) as total FROM vista_detalle_ingresos WHERE ...",
    "template-tags": {
      "incluir_anulados": {
        "type": "boolean",
        "default": false
      }
    }
  }
}

3. Listar todas las cards para encontrar IDs

GET /api/card?f=all
X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=

4. Obtener metadata de una card

GET /api/card/:id
X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=

---

📝 NOTAS IMPORTANTES

1. Autenticación: Todos los requests requieren header X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=

2. Estructura de respuesta de queries:

{
  "data": {
    "rows": [...],           // Array de arrays con los valores
    "cols": [...],           // Metadata de columnas (nombre, tipo, etc)
    "rows_truncated": 1000,  // Límite de filas
    "native_form": {...}     // Query SQL ejecutada
  },
  "database_id": 2,
  "started_at": "...",
  "json_query": {...},
  "average_execution_time": null,
  "status": "completed",
  "context": "ad-hoc",
  "row_count": 1,
  "running_time": 45
}

3. IDs de las 9 queries del Panorama:

   • Query 1: /api/card/38/query (panorama_totales_financieros_principales)
   • Query 2-9: Por determinar

4. Parámetros template-tags:

   • fecha_desde: tipo date/single, opcional
   • fecha_hasta: tipo date/single, opcional
   • incluir_anulados: tipo boolean, default false

5. Testing de queries:

   • Usar /api/dataset para probar SQL antes de crear/editar cards
   • Usar /api/card/:id/query para probar cards existentes con diferentes parámetros

---

🚀 PRÓXIMOS PASOS

1. ✅ Listar todas las cards con GET /api/card?f=all para identificar las 9 queries
2. ✅ Para cada query (1-9):
   • Obtener metadata con GET /api/card/:id
   • Ejecutar con parámetros default usando POST /api/card/:id/query
   • Verificar estructura de respuesta
   • Validar que coincida con la especificación en METABASE_QUERIES_PANORAMA.md
3. ✅ Ajustar queries que no devuelvan la estructura correcta

---

Documento creado: 2025-10-14 Autor: Claude Code Proyecto: Analítica Núcleo - Exploración API Metabase