S!NTyC API

Stack Técnico

Configuración Inicial

1. Variables de entorno

Copiar .env.example a .env y completar los datos de Supabase:

DB_CONNECTION=pgsql
DB_HOST=db.XXXXX.supabase.co
DB_PORT=5432
DB_DATABASE=postgres
DB_USERNAME=postgres
DB_PASSWORD=tu_password

2. Instalación

composer install
php artisan key:generate
php artisan migrate --seed

3. Ejecutar tests

php artisan test
# o
php vendor/bin/phpunit --testdox

4. Scheduler (producción)

* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1

Autenticación

Request — Login

POST /api/login
Content-Type: application/json

{
    "email": "admin@sintyc.test",
    "password": "Password1"
}

Response — Login exitoso

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Admin",
        "email": "admin@sintyc.test",
        "role": {
            "id": 1,
            "name": "Super Administrador",
            "slug": "superadmin"
        },
        "active": true
    }
}

Usuarios

Body — Crear usuario

{
    "name": "Juan Pérez",
    "email": "juan@empresa.com",
    "password": "Segur@123",
    "password_confirmation": "Segur@123",
    "role_id": 3
}

Password requiere: mínimo 8 caracteres, mayúsculas, minúsculas, números y símbolos.

Áreas

Body — Crear área

{
    "name": "Gerencia Comercial",
    "description": "Área de ventas y relaciones comerciales"
}

Body — Reclamar trabajador

{
    "user_id": 5
}

El trabajador debe tener rol worker y no pertenecer a otra área activa.

Body — Asignar encargado

{
    "manager_user_id": 2
}

El usuario será asignado como encargado del área.

Query params — Trabajadores disponibles

GET /api/areas/{'{id}'}/available-workers?search=juan

Retorna workers activos sin área activa asignada, paginados (20 por página). El parámetro search filtra por nombre o email.

Query params — Miembros del área

GET /api/areas/{'{id}'}/members?search=juan

Retorna los miembros activos del área, paginados (20 por página). El parámetro search filtra por nombre o email.

Reuniones

Las reuniones son el origen de los compromisos. Las tareas pueden vincularse a una reunión mediante meeting_id.

Query params — Filtrar reuniones

GET /api/meetings?area_id=1&classification=operational

Body — Crear reunión

{
    "title": "Revisión mensual de avances",
    "meeting_date": "2026-03-20",
    "area_id": 1,
    "classification": "follow_up",
    "notes": "Revisar compromisos pendientes del mes anterior"
}

Clasificaciones disponibles

Tareas

Query params — Filtrar tareas

GET /api/tasks?status=pending&priority=high&area_id=1&sort=oldest

Opciones de ordenamiento (?sort=)

Por defecto, las tareas se ordenan por más recientes primero.

Campos computados en respuesta de tareas

Body — Crear tarea

{
    "title": "Preparar informe trimestral",
    "description": "Consolidar datos de ventas Q1 2026",
    "priority": "high",
    "due_date": "2026-04-01",
    "assigned_to_user_id": 4,
    "meeting_id": 1,
    "requires_attachment": true,
    "requires_completion_comment": true,
    "requires_manager_approval": true,
    "requires_progress_report": true,
    "notify_on_due": true,
    "notify_on_overdue": true,
    "notify_on_completion": false,
    "external_email": null,
    "external_name": null
}

Casos de asignación

Body — Delegar

{
    "to_user_id": 5,
    "note": "Necesito que te encargues de esta tarea"
}

Body — Enviar a revisión

{
    "completion_comment": "Trabajo completado, adjunté el informe final"
}

Si requires_attachment = true, la tarea debe tener al menos un adjunto antes de enviar a revisión.

Body — Rechazar

{
    "rejection_note": "Falta el desglose por región, favor completar"
}

Body — Reabrir tarea

{
    "note": "Se requiere ajustar el informe con datos actualizados"
}

El campo note es opcional. Si la tarea estaba completed vuelve a in_progress. Si estaba cancelled vuelve a pending.

Body — Asignar a externo

{
    "title": "Enviar reporte a auditor",
    "external_email": "auditor@externo.com",
    "external_name": "Carlos López",
    "priority": "high",
    "due_date": "2026-04-15"
}

No se puede combinar external_email con assigned_to_user_id o assigned_to_area_id. Se envía correo automático al destinatario externo.

Body — Subir adjunto

POST /api/tasks/{'{id}'}/attachments
Content-Type: multipart/form-data

file: [archivo]
attachment_type: evidence | support | final_delivery

Avances de Tareas

Permite al responsable o manager reportar avances con porcentaje de progreso.

Body — Reportar avance

{
    "comment": "Se completó la fase de recolección de datos",
    "update_type": "progress",
    "progress_percent": 65
}

Tipos de actualización

Dashboard

Dashboard General

Dashboard por Área

Tareas por estado del área, vencidas, distribución por responsable, tasa de cierre, tareas sin reportes de avance.

Dashboard Consolidado

Reporte tipo Excel por proceso/área con métricas completas. Cada área incluye: process_identifier, total, conteo por estado, tasa de cierre, vencidas, sin avance, antigüedad máxima del pendiente más viejo, promedio de días sin reportar. Incluye resumen global.

Dashboard Personal

Tareas activas, vencidas, próximas a vencer, completadas, distribución por estado, lista de tareas próximas ordenadas por fecha.

Modelos y Relaciones

User

• belongsTo Role
• belongsToMany Area (via area_members)
• hasMany createdTasks, assignedTasks, responsibleTasks
• Helpers: isSuperAdmin(), isAreaManager(), isWorker(), belongsToArea($id), isManagerOfArea($id)

Area

• belongsTo manager (User)
• belongsToMany users (via area_members)
• hasMany Tasks
• Campos: name, description, process_identifier, manager_user_id, active

Task (SoftDeletes)

• belongsTo creator, assignedUser, assignedArea, delegatedBy, currentResponsible, area, closedBy, cancelledBy, meeting
• hasMany comments, attachments, statusHistory, delegations, updates
• Config: requires_attachment, requires_completion_comment, requires_manager_approval, requires_progress_report
• Notificación: notify_on_due, notify_on_overdue, notify_on_completion
• Seguimiento: progress_percent, meeting_id
• Externo: external_email, external_name (para asignaciones a usuarios fuera del sistema)

Meeting

• belongsTo Area, creator (User)
• hasMany Tasks
• Campos: title, meeting_date, area_id, classification, notes, created_by

TaskUpdate

• belongsTo Task, User
• Campos: task_id, user_id, update_type, comment, progress_percent

Otros modelos

• TaskDelegation — Historial de delegaciones (task_id, from_user, to_user)
• TaskComment — Comentarios (task_id, user_id, comment, type)
• TaskAttachment — Archivos adjuntos (file_name, file_path, mime_type, file_size)
• TaskStatusHistory — Cambios de estado (from_status, to_status, note)
• ActivityLog — Auditoría (module, action, subject_type, description)

Enums

TaskStatusEnum

TaskPriorityEnum

RoleEnum

CommentTypeEnum

AttachmentTypeEnum

UpdateTypeEnum

MeetingClassificationEnum

NotificationChannelEnum

Flujo de Estados

Flujo principal

Transiciones alternativas

Tabla de transiciones

Reglas de Negocio

Creación de tareas

Delegación

• Solo el encargado del área puede delegar tareas de su área
• El trabajador destino debe pertenecer al área
• La tarea no puede estar completada ni cancelada
• Se registra en task_delegations y activity_logs

Validaciones de cierre

• Si requires_attachment = true → debe tener al menos un adjunto
• Si requires_completion_comment = true → debe enviar completion_comment

Aprobación / Rechazo

• Si requires_manager_approval = true → pasa a in_review antes de completed
• Si no requiere aprobación → pasa directamente a completed
• Al rechazar → requiere rejection_note, estado vuelve a in_progress

Reabrir tareas

• Tareas completed vuelven a in_progress
• Tareas cancelled vuelven a pending
• Se limpia completed_at, closed_by, cancelled_by
• Superadmin puede reabrir cualquier tarea, manager las de su área, worker solo las propias

Eliminación de tareas

• Solo superadmin y area_manager pueden eliminar tareas
• Se eliminan en cascada comentarios, adjuntos y registros relacionados

Tareas externas

• Se asignan vía external_email + external_name
• No se pueden combinar con assigned_to_user_id o assigned_to_area_id
• Se envía correo automático al destinatario externo con los detalles de la tarea

Reclamar trabajador

• Solo area_manager puede reclamar
• El usuario debe tener rol worker
• El trabajador no debe tener ya un área activa

Reuniones como origen

• Las tareas pueden tener meeting_id vinculándolas a la reunión origen
• Al ver una reunión se listan todas sus tareas asociadas

Seguimiento y avances

• El responsable puede reportar avances con comentario, porcentaje y tipo
• El progress_percent se sincroniza automáticamente con la tarea
• Si requires_progress_report = true, la tarea exige reportes de avance

Notificaciones Automáticas

Los comandos programados generan registros en la tabla task_notifications. Toda la configuración de notificaciones es gestionable desde la API (ver Ajustes del sistema).

Comandos Programados

Los comandos se ejecutan automáticamente según el scheduler, pero sus horarios y estado (activado/desactivado) son configurables desde la API. También pueden ejecutarse manualmente desde los endpoints de automatización.

Ajustes del Sistema

Tabla system_settings — Configuración clave-valor administrable vía API. Solo accesible por superadmin.

GET /api/settings

Lista todos los ajustes agrupados. Filtrar con ?group=notifications o ?group=automation.

// Respuesta
{
    "data": {
        "notifications": [
            { "key": "emails_enabled", "value": true, "type": "boolean", "group": "notifications", "description": "..." },
            { "key": "alert_days_before_due", "value": 3, "type": "integer", "group": "notifications", "description": "..." }
        ],
        "automation": [
            { "key": "detect_overdue_time", "value": "06:00", "type": "string", "group": "automation", "description": "..." }
        ]
    }
}

PUT /api/settings

Actualización masiva de ajustes.

// Request body
{
    "settings": [
        { "key": "emails_enabled", "value": "0" },
        { "key": "alert_days_before_due", "value": "5" },
        { "key": "daily_summary_time", "value": "09:00" }
    ]
}

Ajustes disponibles

Plantillas de Mensajes

Tabla message_templates — Plantillas editables para notificaciones. Solo accesible por superadmin. Las plantillas son precargadas (seeder), no se crean ni eliminan desde la API.

GET /api/message-templates

Lista todas las plantillas.

GET /api/message-templates/{id}

Detalle de una plantilla.

PUT /api/message-templates/{id}

Editar asunto, cuerpo o estado activo.

// Request body (todos los campos son opcionales)
{
    "subject": "Nuevo asunto: {task_title}",
    "body": "Hola {user_name}, nueva tarea asignada...",
    "active": false
}

Plantillas disponibles

Importación CSV

Importa tareas masivamente desde un archivo CSV. Solo accesible por superadmin. Crea áreas automáticamente si no existen.

POST /api/import/tasks

Acepta un archivo CSV (multipart/form-data, campo: file) con las siguientes columnas:

Respuesta exitosa

{
    "message": "Importación completada",
    "imported": 15,
    "errors": []
}

Respuesta con errores parciales

{
    "message": "Importación completada con errores",
    "imported": 12,
    "errors": [
        {"row": 3, "error": "responsable_email es requerido"},
        {"row": 7, "error": "Usuario no encontrado: unknown@mail.com"}
    ]
}

Automatización (Triggers Manuales)

Endpoints para ejecutar manualmente las tareas automatizadas. Solo accesible por superadmin. Cada ejecución se registra en activity_logs.

POST /api/automation/detect-overdue

Ejecuta la detección de tareas vencidas. Equivalente a tasks:detect-overdue.

POST /api/automation/send-summary

Envía el resumen diario de tareas. Falla con 422 si daily_summary_enabled está desactivado.

POST /api/automation/send-reminders

Envía recordatorios de vencimiento. Falla con 422 si emails_enabled está desactivado.

POST /api/automation/detect-inactivity

Ejecuta la detección de tareas inactivas. Falla con 422 si inactivity_alert_enabled está desactivado.

// Respuesta exitosa (200)
{
    "message": "Detección de tareas vencidas ejecutada correctamente",
    "output": "Se marcaron 3 tareas como vencidas."
}

// Respuesta cuando está desactivado (422)
{
    "message": "El resumen diario está desactivado. Actívelo en configuración antes de enviarlo."
}

Formato de Respuestas

Éxito con datos (200)

{
    "data": {
        "id": 1,
        "title": "Tarea ejemplo",
        "status": "pending",
        "priority": "high",
        "progress_percent": 0,
        "is_overdue": false,
        "created_at": "2026-03-16T10:00:00.000000Z"
    }
}

Éxito con mensaje (200)

{
    "message": "Tarea delegada exitosamente"
}

Error de validación (422)

{
    "message": "The title field is required.",
    "errors": {
        "title": ["The title field is required."]
    }
}

Error de autenticación (401)

{
    "message": "Unauthenticated."
}

Error de autorización (403)

{
    "message": "This action is unauthorized."
}

Seguridad

Migraciones

Tests

194 tests organizados por feature — todos pasando con SQLite in-memory.

Ejecutar tests

php artisan test
php vendor/bin/phpunit --testdox