# API de dashboard del dependiente

## Endpoint

| Método | Ruta | Permiso |
| --- | --- | --- |
| GET | `/api/v1/participant/dashboard` | `participant_promotions.view_any` |

## Objetivo

Devuelve las promociones activas y elegibles para la farmacia del dependiente autenticado, junto con un resumen liviano para el dashboard inicial.

No incluye términos completos de todas las promociones. El frontend debe consultar `GET /participant/promotions/{promotion}` cuando abra la aceptación rápida.

## Respuesta

```json
{
  "success": true,
  "message": "Dashboard del dependiente obtenido correctamente.",
  "data": {
    "active_promotions": [
      {
        "id": "uuid-promocion",
        "name": "Rifa de temporada",
        "description": "Promoción vigente",
        "type": "raffle",
        "type_label": "Rifa",
        "prize": "Motor 2026",
        "starts_at": "2026-07-01T00:00:00Z",
        "ends_at": "2026-08-01T23:59:59Z",
        "status": "active",
        "status_label": "Activa",
        "products_count": 2,
        "cover_image": {
          "url": "https://app.test/storage/promotions/covers/uuid.webp",
          "alt": "Arte principal de la promoción"
        },
        "terms": {
          "version": "2.0",
          "accepted": false,
          "accepted_at": null,
          "requires_acceptance": true,
          "status": "pending",
          "status_label": "Términos pendientes",
          "message": "El dependiente debe aceptar los términos vigentes antes de registrar facturas."
        },
        "can_accept_terms": true,
        "current_terms_version": "2.0",
        "accepted_at": null,
        "dashboard_message": "El dependiente debe aceptar los términos vigentes antes de registrar facturas."
      }
    ],
    "summary": {
      "active_promotions": 1,
      "active_participations": 0,
      "valid_tickets": 0
    }
  }
}
```

## Reglas

- solo devuelve promociones `active`
- excluye promociones suspendidas, finalizadas, fuera de fecha o incompletas
- excluye promociones no elegibles para la farmacia del dependiente
- no expone rutas internas de archivos
- `can_accept_terms` evita que el frontend tenga que deducir si debe mostrar la acción principal

## Errores relevantes

- `401` sesión no autenticada
- `403` sin permiso para promociones de participante
- `419` CSRF expirado, el frontend puede reintentar una sola vez mediante su infraestructura central