Skip to main content

API - Notificaciones y Emails

Visión General​

Endpoints para la gestión de notificaciones en tiempo real, emails automatizados y comunicación con usuarios.

Notificaciones​

GET /notifications/all​

Obtener todas las notificaciones del usuario.

Query Parameters​

  • read: Filtrar por leídas/no leídas (true/false)
  • type: Tipo de notificación (payment, contract, maintenance, system)
  • limit: Número de notificaciones (default: 20)

Response Success (200)​

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Pago recibido",
      "message": "Se ha recibido el pago del contrato #123 por $900.000",
      "type": "payment",
      "read": false,
      "priority": "medium",
      "related_entity": {
        "type": "contract",
        "id": 123
      },
      "action_url": "/admin/contracts/123",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "title": "Nueva solicitud de mantenimiento",
      "message": "María García ha enviado una solicitud para Apartamento Moderno",
      "type": "maintenance",
      "read": true,
      "priority": "high",
      "related_entity": {
        "type": "request",
        "id": 45
      },
      "action_url": "/admin/requests/45",
      "created_at": "2024-01-14T15:20:00Z"
    }
  ],
  "count": 12,
  "unread_count": 5
}

POST /notification/create​

Crear nueva notificación.

Request​

{
  "user_id": 124,
  "title": "Contrato próximo a vencer",
  "message": "El contrato del Apartamento Centro vence en 30 días",
  "type": "contract",
  "priority": "medium",
  "related_entity": {
    "type": "contract",
    "id": 156
  },
  "action_url": "/admin/contracts/156",
  "send_email": true,
  "send_push": false
}

Response Success (201)​

{
  "success": true,
  "message": "Notificación creada exitosamente",
  "data": {
    "id": 89,
    "title": "Contrato próximo a vencer",
    "sent_channels": ["app", "email"]
  }
}

PUT /notification/mark-read​

Marcar notificación como leída.

Request​

{
  "notification_id": 89
}

Response Success (200)​

{
  "success": true,
  "message": "Notificación marcada como leída"
}

PUT /notification/mark-all-read​

Marcar todas las notificaciones como leídas.

Response Success (200)​

{
  "success": true,
  "message": "Todas las notificaciones marcadas como leídas",
  "data": {
    "marked_count": 8
  }
}

Emails​

POST /email/contactus​

Enviar email de contacto.

Request​

{
  "name": "Juan Pérez",
  "email": "juan@email.com",
  "subject": "Consulta sobre suscripción",
  "message": "Hola, tengo una pregunta sobre los planes disponibles..."
}

Response Success (200)​

{
  "success": true,
  "message": "Email enviado exitosamente",
  "data": {
    "message_id": "msg_1234567890"
  }
}

POST /email/send-custom​

Enviar email personalizado.

Request​

{
  "to_email": "usuario@email.com",
  "subject": "Recordatorio de pago",
  "template": "payment_reminder",
  "variables": {
    "user_name": "María García",
    "amount": 900000,
    "due_date": "2024-01-20",
    "property_title": "Apartamento Moderno"
  }
}

Response Success (200)​

{
  "success": true,
  "message": "Email enviado exitosamente",
  "data": {
    "message_id": "msg_1234567891",
    "template_used": "payment_reminder",
    "sent_at": "2024-01-15T10:30:00Z"
  }
}

GET /email/templates​

Obtener plantillas de email disponibles.

Response Success (200)​

{
  "success": true,
  "data": [
    {
      "id": "welcome",
      "name": "Email de Bienvenida",
      "description": "Email enviado a nuevos usuarios",
      "variables": ["user_name", "login_url"],
      "category": "authentication"
    },
    {
      "id": "payment_reminder",
      "name": "Recordatorio de Pago",
      "description": "Recordatorio de pago pendiente",
      "variables": ["user_name", "amount", "due_date", "property_title"],
      "category": "payments"
    },
    {
      "id": "contract_signature",
      "name": "Solicitud de Firma de Contrato",
      "description": "Email con enlace para firmar contrato",
      "variables": ["user_name", "contract_id", "sign_url", "expires_in"],
      "category": "contracts"
    }
  ]
}

GET /email/history​

Obtener historial de emails enviados.

Query Parameters​

  • user_id: Filtrar por usuario
  • template: Filtrar por plantilla
  • start_date: Fecha de inicio
  • end_date: Fecha de fin
  • status: Estado (sent, failed, pending)

Response Success (200)​

{
  "success": true,
  "data": [
    {
      "id": 1,
      "to_email": "maria@email.com",
      "subject": "Recordatorio de pago",
      "template": "payment_reminder",
      "status": "sent",
      "sent_at": "2024-01-15T10:30:00Z",
      "opened_at": "2024-01-15T11:45:00Z",
      "clicked": true,
      "bounced": false
    }
  ],
  "count": 156,
  "stats": {
    "sent": 150,
    "failed": 6,
    "open_rate": 87.3,
    "click_rate": 23.4
  }
}

Configuración de Notificaciones​

GET /user/notification-preferences​

Obtener preferencias de notificación del usuario.

Response Success (200)​

{
  "success": true,
  "data": {
    "email_notifications": {
      "payment_received": true,
      "payment_due": true,
      "contract_expiring": true,
      "maintenance_request": true,
      "system_updates": false
    },
    "push_notifications": {
      "payment_received": true,
      "payment_due": true,
      "contract_expiring": false,
      "maintenance_request": true,
      "system_updates": false
    },
    "sms_notifications": {
      "payment_due": true,
      "emergency_maintenance": true,
      "contract_expiring": false
    },
    "notification_schedule": {
      "quiet_hours_start": "22:00",
      "quiet_hours_end": "08:00",
      "timezone": "America/Bogota"
    }
  }
}

PUT /user/notification-preferences​

Actualizar preferencias de notificación.

Request​

{
  "email_notifications": {
    "payment_received": true,
    "payment_due": true,
    "contract_expiring": false,
    "maintenance_request": true,
    "system_updates": false
  },
  "push_notifications": {
    "payment_received": false,
    "payment_due": true,
    "maintenance_request": true
  },
  "quiet_hours_start": "23:00",
  "quiet_hours_end": "07:00"
}

Response Success (200)​

{
  "success": true,
  "message": "Preferencias actualizadas exitosamente"
}

Tipos de Notificación​

payment​

  • Pagos recibidos
  • Recordatorios de pago
  • Pagos fallidos

contract​

  • Contratos próximos a vencer
  • Nuevos contratos firmados
  • Solicitudes de firma

maintenance​

  • Nuevas solicitudes
  • Actualizaciones de estado
  • Completadas

system​

  • Actualizaciones del sistema
  • Mantenimiento programado
  • Alertas de seguridad

Plantillas de Email​

Autenticación​

  • welcome: Email de bienvenida
  • password_reset: Recuperación de contraseña
  • email_verification: Verificación de email

Pagos​

  • payment_reminder: Recordatorio de pago
  • payment_received: Confirmación de pago
  • payment_failed: Notificación de pago fallido

Contratos​

  • contract_signature: Solicitud de firma
  • contract_signed: Confirmación de firma
  • contract_expiring: Próximo a vencer

Mantenimiento​

  • maintenance_assigned: Técnico asignado
  • maintenance_completed: Trabajo completado
  • maintenance_scheduled: Cita programada

Canales de Envío​

Email (AWS SES)​

  • Entrega garantizada
  • Tracking de apertura
  • Tracking de clicks
  • Gestión de bounces

Push Notifications​

  • Notificaciones móviles
  • Badges y contadores
  • Deep linking

SMS (Opcional)​

  • Para emergencias
  • Recordatorios críticos
  • Verificación 2FA