# API del dashboard administrativo

## Endpoint

| Método | Ruta | Permiso |
| --- | --- | --- |
| `GET` | `/api/v1/admin/dashboard` | `reports.view_dashboard` |

## Fecha de negocio

El dashboard usa por defecto:

- `invoice_date`

No mezcla silenciosamente:

- `created_at`
- `generated_at`
- `processed_at`

## Filtros

- `promotion_id`
- `date_from`
- `date_to`
- `province`
- `city`
- `pharmacy_id`
- `product_id`

## Respuesta

```json
{
  "filters": {
    "promotion_id": null,
    "date_from": null,
    "date_to": null,
    "province": null,
    "city": null,
    "pharmacy_id": null,
    "product_id": null,
    "date_field": "invoice_date"
  },
  "summary": {
    "active_promotions": 0,
    "participants": 0,
    "pharmacies": 0,
    "physical_invoices": 0,
    "current_applications": 0,
    "valid_tickets": 0,
    "voided_tickets": 0,
    "corrected_invoices": 0,
    "historical_tickets": 0
  },
  "charts": {
    "tickets_over_time": [],
    "promotion_participation": [],
    "top_products": [],
    "geographic_distribution": []
  }
}
```

## Definiciones

- `participants`: dependientes únicos con al menos una aplicación vigente vinculada a la revisión actual.
- `pharmacies`: farmacias únicas con participación vigente.
- `physical_invoices`: facturas físicas únicas, no revisiones.
- `current_applications`: aplicaciones vigentes ligadas a la revisión actual.
- `valid_tickets`: boletos vigentes de aplicaciones actuales.
- `voided_tickets`: boletos anulados históricos dentro del alcance filtrado.
- `corrected_invoices`: facturas físicas con más de una revisión.

## Errores relevantes

- `401 UNAUTHENTICATED`
- `403 FORBIDDEN`
- `419` CSRF expirado
- `429 TOO_MANY_REQUESTS`