# Documentación de API REST dlyyn.com (Para Flutter y Aplicaciones Móviles)

Esta documentación describe la API REST completa de **dlyyn.com** para la integración con la aplicación móvil en **Flutter**, iOS y Android.

---

## 1. Configuración Base

- **Base URL:** `https://dlyyn.com/api/v1`
- **Formato de Peticiones y Respuestas:** `application/json`
- **Autenticación:** HTTP Bearer Token en la cabecera `Authorization`.
  ```http
  Authorization: Bearer <TOKEN>
  ```

---

## 2. Endpoints de Autenticación (`/auth`)

### 2.1 Registrar nueva cuenta de correo `@dlyyn.com`
Crea una cuenta en la base de datos de la plataforma y provisiona automáticamente la casilla de correo física en el servidor HestiaCP (Dovecot / Exim).

- **Método:** `POST`
- **Endpoint:** `/auth/register.php`
- **Body JSON:**
  ```json
  {
    "username": "juan",
    "password": "MiPasswordSeguro123!",
    "full_name": "Juan Pérez",
    "recovery_email": "juan.perez@gmail.com"
  }
  ```
- **Respuesta (201 Created):**
  ```json
  {
    "status": "success",
    "message": "Cuenta creada exitosamente en dlyyn.com",
    "data": {
      "user": {
        "id": 1,
        "username": "juan",
        "email": "juan@dlyyn.com",
        "full_name": "Juan Pérez",
        "recovery_email": "juan.perez@gmail.com",
        "avatar": null,
        "quota_mb": 1000,
        "theme_preference": "dark"
      },
      "token": "a1b2c3d4e5f67890...",
      "expires_at": "2026-11-09 20:00:00"
    }
  }
  ```

---

### 2.2 Iniciar Sesión
Autentica al usuario mediante correo o nombre de usuario y su contraseña.

- **Método:** `POST`
- **Endpoint:** `/auth/login.php`
- **Body JSON:**
  ```json
  {
    "email": "juan@dlyyn.com",
    "password": "MiPasswordSeguro123!"
  }
  ```
- **Respuesta (200 OK):**
  ```json
  {
    "status": "success",
    "message": "Inicio de sesión exitoso",
    "data": {
      "user": {
        "id": 1,
        "username": "juan",
        "email": "juan@dlyyn.com",
        "full_name": "Juan Pérez",
        "recovery_email": "juan.perez@gmail.com",
        "theme_preference": "dark"
      },
      "token": "a1b2c3d4e5f67890...",
      "expires_at": "2026-11-09 20:00:00"
    }
  }
  ```

---

### 2.3 Obtener Perfil Actual (`/auth/me.php`)
- **Método:** `GET`
- **Header:** `Authorization: Bearer <TOKEN>`
- **Respuesta (200 OK):**
  ```json
  {
    "status": "success",
    "data": {
      "user": {
        "id": 1,
        "username": "juan",
        "email": "juan@dlyyn.com",
        "full_name": "Juan Pérez"
      }
    }
  }
  ```

---

## 3. Endpoints de Correo Electrónico (`/emails`)

### 3.1 Listar Correos de una Carpeta
- **Método:** `GET`
- **Endpoint:** `/emails/list.php?folder=INBOX&page=1&limit=20&q=`
- **Parámetros URL:**
  - `folder`: `INBOX`, `Sent`, `Starred`, `Drafts`, `Trash`, `Spam` (por defecto `INBOX`)
  - `page`: Número de página (1, 2...)
  - `limit`: Cantidad por página (default 25)
  - `q`: Término de búsqueda opcional.
- **Respuesta (200 OK):**
  ```json
  {
    "status": "success",
    "data": {
      "emails": [
        {
          "uid": 105,
          "folder": "INBOX",
          "from_name": "Soporte Google",
          "from_email": "no-reply@google.com",
          "subject": "Seguridad de la cuenta",
          "preview": "Se ha detectado un nuevo inicio de sesión...",
          "date": "2026-10-10 19:45:00",
          "is_read": false,
          "is_starred": true,
          "has_attachment": false
        }
      ],
      "total": 45,
      "page": 1,
      "pages": 3,
      "unread": 4
    }
  }
  ```

---

### 3.2 Obtener Detalle de un Correo
- **Método:** `GET`
- **Endpoint:** `/emails/detail.php?uid=105&folder=INBOX`
- **Respuesta (200 OK):**
  ```json
  {
    "status": "success",
    "data": {
      "uid": 105,
      "from_name": "Soporte Google",
      "from_email": "no-reply@google.com",
      "to_email": "juan@dlyyn.com",
      "subject": "Seguridad de la cuenta",
      "date": "2026-10-10 19:45:00",
      "body_html": "<p>Hola Juan, se ha detectado...</p>",
      "body_text": "Hola Juan, se ha detectado...",
      "attachments": [
        {
          "part_index": 1,
          "filename": "comprobante.pdf",
          "size": 1048576,
          "mime": "application/pdf"
        }
      ]
    }
  }
  ```

---

### 3.3 Enviar Correo
- **Método:** `POST`
- **Endpoint:** `/emails/send.php`
- **Body JSON:**
  ```json
  {
    "to": "contacto@ejemplo.com",
    "subject": "Hola desde la App Flutter",
    "body": "Este es un mensaje enviado desde el cliente móvil de dlyyn."
  }
  ```

---

### 3.4 Acciones sobre Correos (Marcar Leído, Destacar, Eliminar)
- **Método:** `POST`
- **Endpoint:** `/emails/action.php`
- **Body JSON:**
  ```json
  {
    "uid": 105,
    "action": "star", 
    "folder": "INBOX"
  }
  ```
  *(Valores permitidos para `action`: `read`, `unread`, `star`, `unstar`, `delete`)*

---

## 4. Endpoints de Notificaciones Push (`/push`)

### 4.1 Registrar Token de Notificaciones (Web Push / Flutter FCM)
- **Método:** `POST`
- **Endpoint:** `/push/subscribe.php`
- **Body JSON:**
  ```json
  {
    "endpoint": "https://fcm.googleapis.com/fcm/send/token_movil_flutter_12345",
    "platform": "android"
  }
  ```

---

### 4.2 Verificar Correos Nuevos Sin Leer (`/push/check-new.php`)
- **Método:** `GET`
- **Endpoint:** `/push/check-new.php`
- **Respuesta:**
  ```json
  {
    "status": "success",
    "data": {
      "has_new": true,
      "unread_count": 3,
      "latest_email": {
        "uid": 106,
        "from_name": "Daniel",
        "subject": "Reunión dlyyn"
      }
    }
  }
  ```

---

## 5. Ejemplo de Código en Flutter (Dart)

```dart
import 'package:http/http.dart' as http;
import 'dart:convert';

class DlyynApiService {
  static const String baseUrl = 'https://dlyyn.com/api/v1';

  static Future<Map<String, dynamic>> login(String email, String password) async {
    final response = await http.post(
      Uri.parse('$baseUrl/auth/login.php'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'email': email, 'password': password}),
    );
    return jsonDecode(response.body);
  }

  static Future<Map<String, dynamic>> fetchInbox(String token) async {
    final response = await http.get(
      Uri.parse('$baseUrl/emails/list.php?folder=INBOX'),
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer $token',
      },
    );
    return jsonDecode(response.body);
  }
}
```