n8n-nodes-minery-core

Community nodes para n8n que integran con Minery Core, permitiendo gestión de modelos de datos, operaciones CRUD sobre filas y recepción de eventos en tiempo real via webhooks.

🚀 Características

• Credenciales Minery API: Autenticación segura con X-API-Key
• Minery Modelos: List: Lista modelos de datos con filtros y paginación
• Minery Filas: CRUD: Operaciones completas sobre filas (Create, Read, Update, List)
• Minery Fila Trigger: Trigger en tiempo real que se subscribe/unsubscribe automáticamente a webhooks

📦 Instalación

Desde npm (Community Nodes UI)

Si tienes n8n self-hosted con acceso a Community Nodes:

1. Ve a Settings → Community Nodes
2. Busca n8n-nodes-minery-core
3. Instala el paquete

Instalación Manual

Para instalaciones self-hosted o en modo queue:

# Navega al directorio de n8n
cd ~/.n8n

# Instala el paquete
npm install n8n-nodes-minery-core

# Reinicia n8n

Desarrollo Local

Para desarrollo y testing:

git clone https://github.com/maromero/n8n-nodes-minery-core.git
cd n8n-nodes-minery-core
npm install
npm run build

⚙️ Configuración

1. Credenciales Minery API

Configura las credenciales con los siguientes campos:

• Base URL: URL de tu instancia Minery (ej: https://api.minery.com)
• API Key: Tu clave de API para autenticación X-API-Key (requerido)
• Webhook Secret: Secret para verificar firmas HMAC de webhooks (opcional)

2. Endpoint Requirements

Tu backend de Minery debe implementar estos endpoints:

Para Modelos:

• GET /api/v1/modelos-de-datos/list/ - Lista modelos con paginación

Para Filas:

• POST /api/v1/fila-de-datos/create/ - Crear fila
• PUT /api/v1/fila-de-datos/update/ - Actualizar fila
• GET /api/v1/fila-de-datos/list/ - Listar filas
• GET /api/v1/fila-de-datos/{id}/ - Obtener fila específica

Para Webhooks (Trigger):

• POST /api/v1/webhooks-n8n/subscribe/ - Suscribir webhook
• DELETE /api/v1/webhooks-n8n/unsubscribe/ - Desuscribir webhook

🧩 Nodos Disponibles

Minery Modelos: List

Lista modelos de datos con opciones de filtrado y paginación.

Parámetros:

• Búsqueda por texto
• Ordenamiento (fecha, nombre, ID)
• Paginación con opción de obtener todas las páginas
• Formato de salida (items individuales o array)

Salida: Lista de modelos con metadatos opcionales

Minery Filas: CRUD

Operaciones completas sobre filas de datos.

Operaciones:

• Crear: Nueva fila con metainformación JSON
• Actualizar: Modificar fila existente
• Listar: Filtrar filas por modelo con paginación
• Obtener: Recuperar fila específica por ID

Parámetros:

• ID del modelo de datos
• Metainformación en formato JSON
• Filtros de búsqueda y ordenamiento
• Opciones de paginación

Minery Fila Trigger

Trigger que recibe eventos en tiempo real cuando se crean/actualizan filas.

Características:

• Auto-suscripción: Se subscribe automáticamente al activar el workflow
• Auto-desuscripción: Se desuscribe al desactivar el workflow
• Verificación HMAC: Opcional para validar la autenticidad de webhooks
• Filtros flexibles: Configura qué eventos recibir (create, update, delete)

Parámetros:

• ID del modelo de datos a monitorear
• Eventos a escuchar (create, update, delete)
• Token de identificación opcional
• Configuración de firma HMAC
• Filtros personalizados en JSON

🔧 Ejemplos de Uso

Workflow Básico: Sincronizar con CRM

1. Minery Fila Trigger (modelo: clientes, eventos: create, update, delete)
   ↓
2. IF Node (separar por tipo de evento)
   ↓
3a. HTTP Request → Crear cliente en CRM (si event = create)
3b. HTTP Request → Actualizar cliente en CRM (si event = update)
3c. HTTP Request → Eliminar cliente en CRM (si event = delete)

Workflow: Reporte Diario

1. Schedule Trigger (diario a las 9:00)
   ↓
2. Minery Modelos: List (obtener todos los modelos)
   ↓
3. Split In Batches
   ↓
4. Minery Filas: CRUD (operation: list, obtener filas del día anterior)
   ↓
5. Aggregate
   ↓
6. Email Node (enviar reporte)

Workflow: Procesamiento en Tiempo Real

1. Minery Fila Trigger (modelo: pedidos, eventos: create)
   ↓
2. IF Node (verificar si pedido > $1000)
   ↓
3. Slack Node (notificar a ventas)
   ↓
4. Minery Filas: CRUD (operation: update, marcar como "revision_requerida")

🛠️ Desarrollo

Estructura del Proyecto

n8n-nodes-minery-core/
├── credentials/
│   └── MineryApi.credentials.ts
├── nodes/
│   ├── MineryModeloList/
│   │   ├── MineryModeloList.node.ts
│   │   └── minery-modelo.svg
│   ├── MineryFilaCrud/
│   │   ├── MineryFilaCrud.node.ts
│   │   └── minery-fila.svg
│   └── MineryFilaTrigger/
│       ├── MineryFilaTrigger.node.ts
│       └── minery-trigger.svg
├── utils/
│   └── MineryApiRequest.ts
├── package.json
├── tsconfig.json
└── index.ts

Scripts Disponibles

npm run build          # Compilar TypeScript
npm run lint           # Ejecutar ESLint
npm run lint:fix       # Corregir errores de ESLint automáticamente
npm run dev            # Compilar en modo watch
npm test               # Ejecutar tests

Contribuir

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -am 'Añadir nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Crea un Pull Request

🔐 Seguridad

Verificación de Webhooks

Para mayor seguridad, configura un webhook secret en las credenciales y activa la verificación HMAC en el trigger:

1. En Credenciales Minery API, establece un Webhook Secret
2. En tu backend, firma los webhooks con HMAC-SHA256
3. En el Trigger, activa Usar Firma HMAC

El header esperado es: X-Minery-Signature: sha256=<hash>

Buenas Prácticas

• Usa HTTPS siempre en producción
• Rota las API Keys regularmente
• Monitorea los logs de webhooks para detectar anomalías
• Implementa rate limiting en tu backend de Minery

📚 API Reference

Estructura de Datos

Modelo de Datos

{
  "id": 123,
  "nombre": "Clientes",
  "descripcion": "Modelo para gestionar clientes",
  "fecha_alta": "2024-01-15T10:30:00Z",
  "activo": true
}

Fila de Datos

{
  "id": 456,
  "modelo_de_datos_id": 123,
  "metainformacion": {
    "nombre": "Juan Pérez",
    "email": "juan@example.com",
    "telefono": "+34 600 123 456"
  },
  "fecha_creacion": "2024-01-15T11:00:00Z",
  "fecha_modificacion": "2024-01-15T11:00:00Z"
}

Evento de Webhook

{
  "event": "create",
  "data": {
    "id": 456,
    "modelo_de_datos_id": 123,
    "metainformacion": { ... },
    "fecha_creacion": "2024-01-15T11:00:00Z"
  },
  "timestamp": "2024-01-15T11:00:00Z",
  "token": "mi-token-identificacion"
}

🐛 Solución de Problemas

Error: "Credenciales inválidas"

• Verifica que la Base URL es correcta (sin barra final)
• Confirma que el API Key es válido
• Comprueba que el endpoint /api/v1/modelos-de-datos/list/ responde

Trigger no recibe webhooks

• Verifica que n8n es accesible desde internet
• Comprueba que los endpoints de subscribe/unsubscribe funcionan
• Revisa los logs del workflow para errores de suscripción

Error de firma HMAC

• Asegúrate de usar la misma clave en credenciales y backend
• Verifica que el header es X-Minery-Signature: sha256=<hash>
• Confirma que el hash se calcula sobre el body raw del webhook

📄 Licencia

MIT © Miguel Romero

🆘 Soporte

• Issues: GitHub Issues
• Documentación: n8n Community Nodes
• Minery Core: Consulta la documentación de tu API

Construido con ❤️ para la comunidad n8n