treedevs/novacontent-connect

Módulo de integración con Novacontent Commerce para enriquecimiento asistido de atributos del catálogo Magento 2

1.0.0 2026-05-29 20:42 UTC

Requires

• php: ^8.1 || ^8.2 || ^8.3
• magento/framework: ^103.0

proprietary

• TreeDevs

README

Módulo de integración entre Magento 2 y Novacontent Commerce

Versión: 1.0.0
Autor: TreeDevs
Licencia: Proprietary

Descripción

TreeDevs_NovacontentConnect permite la integración bidireccional entre Magento 2 y la plataforma Novacontent Commerce para el enriquecimiento automático de atributos de productos mediante inteligencia artificial.

Funcionalidades principales

• Envío de productos: Selección individual o masiva de productos desde el catálogo para envío a Novacontent
• Enriquecimiento automático: Generación de atributos (descripciones, meta tags, etc.) mediante IA
• Polling asincrónico: Recuperación automática de resultados mediante cron
• Revisión y aprobación: Interface administrativa para revisar atributos generados antes de aplicarlos
• Aplicación al catálogo: Actualización automática de productos con atributos aprobados
• Trazabilidad completa: Logging estructurado de todas las operaciones
• Gestión de estados: Máquina de estados para tracking del ciclo de vida de requests

Requisitos

• Magento: 2.4.x
• PHP: 8.1 o superior
• Extensiones PHP: curl, json
• Permisos: Acceso a cron, acceso a API externa (Novacontent Commerce)

Instalación

Método 1: Instalación manual

# 1. Copiar el módulo al directorio de código
cp -r TreeDevs/NovacontentConnect app/code/TreeDevs/

# 2. Habilitar el módulo
bin/magento module:enable TreeDevs_NovacontentConnect

# 3. Ejecutar setup
bin/magento setup:upgrade

# 4. Compilar DI (producción)
bin/magento setup:di:compile

# 5. Limpiar caché
bin/magento cache:flush

Método 2: Composer (si está registrado)

composer require treedevs/novacontent-connect
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Configuración

1. Configuración básica

Navega a: Stores > Configuration > TreeDevs > Novacontent Connect

Sección: Connection

• Enable Module: Yes para activar el módulo
• API Endpoint: URL base de Novacontent Commerce (ej: https://api.novacontent.com)
• API Key: Token de autenticación proporcionado por Novacontent (campo obscured)

Sección: Enrichment

• Attributes to Send: Multiselección de atributos EAV que se enviarán a Novacontent
  • Seleccionar solo atributos necesarios (ej: name, description, short_description, meta_title, meta_description)

Sección: Polling

• Cron Frequency: Frecuencia de polling para recuperar resultados
  • */5 * * * * (cada 5 minutos)
  • */15 * * * * (cada 15 minutos) — recomendado
  • */30 * * * * (cada 30 minutos)
  • 0 * * * * (cada hora)

2. Permisos ACL

Asignar permisos a roles de usuario en: System > Permissions > User Roles

Recursos disponibles:

• TreeDevs_NovacontentConnect::novacontent (acceso general)
• TreeDevs_NovacontentConnect::config (configuración)
• TreeDevs_NovacontentConnect::requests (gestión de requests)
• TreeDevs_NovacontentConnect::logs (visualización de logs)

Uso

Envío de productos a Novacontent

Opción 1: Desde el grid de productos (mass action)

1. Ir a Catalog > Products
2. Seleccionar productos (solo simples y configurables)
3. En Actions, seleccionar Send to Novacontent
4. Confirmar el envío

Opción 2: Desde el detalle de producto

1. Abrir un producto para edición
2. Click en botón Send to Novacontent (arriba a la derecha)
3. El producto se enviará inmediatamente

Revisión y aprobación de atributos generados

1. Ir a TreeDevs > Novacontent > Integration Requests
2. Localizar requests con estado COMPLETED
3. Click en View para ver detalles
4. Click en Revisar y Aprobar
5. Revisar tabs:
   • Información del Request: Datos generales
   • Atributos Generados: Tabla de productos y atributos
   • Cambios Propuestos: Comparación antes/después
6. Click en ✓ Aprobar y Aplicar al Catálogo para aplicar cambios
7. Los atributos se aplicarán automáticamente a los productos

Consulta de logs operativos

1. Ir a TreeDevs > Novacontent > Operational Logs
2. Filtrar por:
   • Request ID
   • Layer (capa: controller, manager, adapter, cron, etc.)
   • Phase (fase del proceso)
   • Result (success, warning, error)
   • Fecha

Arquitectura

Componentes principales

TreeDevs/NovacontentConnect/
├── Api/                            # Interfaces de datos y servicios
│   ├── Data/                       # Interfaces de entidades
│   └── Adapter/                    # Interface del adapter HTTP
├── Model/
│   ├── Manager/                    # Orquestadores de flujo
│   │   ├── IntegrationRequestManager.php
│   │   └── ResultPollingManager.php
│   ├── Service/                    # Servicios de negocio
│   │   ├── RequestPreparationService.php
│   │   └── ApplicationService.php
│   ├── Adapter/                    # Adapter HTTP a Novacontent
│   │   └── NovacontentCommerceAdapter.php
│   └── Repository/                 # Repositorios de datos
├── Controller/Adminhtml/           # Controllers admin
│   ├── Request/                    # Gestión de requests
│   └── Product/                    # Envío de productos
├── Cron/                          # Jobs programados
├── Logger/                        # Logger operativo
└── view/adminhtml/                # UI administrativa

Flujo de datos

1. Envío (Manual o automático):

   • User selecciona productos
   • IntegrationRequestManager::createAndSendRequest()
   • RequestPreparationService::buildRequestPayload()
   • NovacontentCommerceAdapter::createRequest() → API Novacontent
   • Estado: PENDING_SEND → PENDING

2. Polling (Cron cada 15 min):

   • PollRemoteResults (cron job)
   • ResultPollingManager::run()
   • Para cada request PENDING/PROCESSING:
     • Adapter::getRequestStatus() → verifica estado
     • Si COMPLETED: Adapter::getRequestResult() → obtiene atributos
     • Persiste IntegrationResponse con JSON íntegro
   • Estado: PENDING → PROCESSING → COMPLETED

3. Revisión y Aplicación (Manual):

   • Admin revisa atributos en UI
   • Click "Aprobar"
   • ApplicationService::applyAttributesToCatalog()
   • Validación allowlist de atributos (seguridad)
   • Actualización productos vía ProductRepository
   • Persistencia IntegrationApplicationEvidence
   • Estado: COMPLETED → APPLIED

Persistencia

Tablas creadas:

• novacontent_integration_request — Requests de enriquecimiento
• novacontent_integration_request_item — Items por request (productos)
• novacontent_integration_response — Respuestas de Novacontent
• novacontent_integration_application_evidence — Evidencia de aplicación
• novacontent_integration_operational_log — Logs operativos

Estados de Integration Request

Estado	Descripción
PENDING_SEND	Creado localmente, aún no enviado a Novacontent
PENDING	Enviado a Novacontent, esperando procesamiento
PROCESSING	En procesamiento por Novacontent
COMPLETED	Procesamiento completado, atributos disponibles
FAILED	Error en Novacontent
CANCELLED	Cancelado por Novacontent
APPLIED	Atributos aplicados al catálogo exitosamente
APPLICATION_FAILED	Fallo al aplicar atributos al catálogo
REJECTED	Rechazado manualmente por admin
PERMANENTLY_FAILED	Falló después de máximo de reintentos (3)

Seguridad

Reglas implementadas

• SEC-NCC-01: API Key nunca se expone en logs, UI ni excepciones
• SEC-NCC-03: Contexto de logs sanitizado (sin secrets)
• SEC-NCC-05: ACL en todos los controllers administrativos
• SEC-NCC-06: Solo atributos en allowlist se aplican al catálogo

Recomendaciones

• Usar HTTPS para endpoint de Novacontent
• Rotar API Key periódicamente
• Limitar permisos ACL al mínimo necesario
• Revisar logs operativos regularmente

Troubleshooting

El módulo no aparece en configuración

# Verificar que el módulo está habilitado
bin/magento module:status TreeDevs_NovacontentConnect

# Si está deshabilitado:
bin/magento module:enable TreeDevs_NovacontentConnect
bin/magento setup:upgrade
bin/magento cache:flush

Cron no ejecuta polling

# Verificar configuración de cron
bin/magento cron:run --group default

# Ver logs de cron
tail -f var/log/system.log | grep novacontent

Error al enviar productos

1. Verificar que el módulo está enabled en configuración
2. Verificar API Endpoint y API Key correctos
3. Verificar conectividad: curl -I https://api.novacontent.com
4. Revisar logs: TreeDevs > Novacontent > Operational Logs

Atributos no se aplican al catálogo

1. Verificar que los atributos están en la allowlist (Config > Attributes to Send)
2. Verificar que el request está en estado COMPLETED
3. Revisar logs de layer catalog_apply
4. Verificar permisos de escritura en base de datos

Soporte

Para soporte técnico, contactar:

• Email: [e-mail]
• Documentación: [Internal Wiki]

Changelog

v1.0.0 (2026-04-23)

• Release inicial
• Funcionalidades core completas:
  • Envío manual/masivo de productos
  • Polling asincrónico de resultados
  • Revisión y aprobación de atributos
  • Aplicación al catálogo con validaciones
  • Logging operativo completo
  • UI administrativa completa

Licencia

Proprietary - TreeDevs © 2026