API Event Stats - Guide Flutter

Authentification

Toutes les routes nécessitent un Bearer Token (session) et un rôle Admin (2) ou Super-admin (1).

headers: {
'Authorization': 'Bearer $sessionToken',
'Content-Type': 'application/json',
}

---

1. Résumé du jour

GET /api/events/stats/summary?date=2025-12-22

| Param | Type   | Requis | Description                           |
| ----- | ------ | ------ | ------------------------------------- |
| date  | string | Non    | Date YYYY-MM-DD (défaut: aujourd'hui) |

Réponse (~1 KB) :
{
"status": "success",
"data": {
"date": "2025-12-22",
"stats": {
"auth": { "success": 45, "failed": 3, "logout": 12 },
"passages": { "created": 128, "updated": 5, "deleted": 2, "amount": 2450.00 },
"users": { "created": 2, "updated": 5, "deleted": 0 },
"sectors": { "created": 1, "updated": 3, "deleted": 0 },
"stripe": { "created": 15, "success": 12, "failed": 1, "cancelled": 2, "amount": 890.00 }
},
"totals": { "events": 245, "unique_users": 18 }
}
}

---

2. Stats journalières (graphiques)

GET /api/events/stats/daily?from=2025-12-01&to=2025-12-22&events=passage_created,login_success

| Param  | Type   | Requis | Description                     |
| ------ | ------ | ------ | ------------------------------- |
| from   | string | Oui    | Date début YYYY-MM-DD           |
| to     | string | Oui    | Date fin YYYY-MM-DD             |
| events | string | Non    | Types filtrés (comma-separated) |

Limite : 90 jours max

Réponse (~5 KB) :
{
"status": "success",
"data": {
"from": "2025-12-01",
"to": "2025-12-22",
"days": [
{
"date": "2025-12-01",
"events": {
"passage_created": { "count": 45, "sum_amount": 850.00, "unique_users": 8 },
"login_success": { "count": 12, "sum_amount": 0, "unique_users": 12 }
},
"totals": { "count": 57, "sum_amount": 850.00 }
},
...
]
}
}

---

3. Stats hebdomadaires

GET /api/events/stats/weekly?from=2025-10-01&to=2025-12-22

| Param  | Type   | Requis | Description   |
| ------ | ------ | ------ | ------------- |
| from   | string | Oui    | Date début    |
| to     | string | Oui    | Date fin      |
| events | string | Non    | Types filtrés |

Limite : 365 jours max

Réponse (~2 KB) :
{
"status": "success",
"data": {
"from": "2025-10-01",
"to": "2025-12-22",
"weeks": [
{
"week_start": "2025-12-16",
"week_number": 51,
"year": 2025,
"events": {
"passage_created": { "count": 320, "sum_amount": 5200.00, "unique_users": 15 }
},
"totals": { "count": 450, "sum_amount": 5200.00 }
},
...
]
}
}

---

4. Stats mensuelles

GET /api/events/stats/monthly?year=2025&events=passage_created,stripe_payment_success

| Param  | Type   | Requis | Description                    |
| ------ | ------ | ------ | ------------------------------ |
| year   | int    | Non    | Année (défaut: année courante) |
| events | string | Non    | Types filtrés                  |

Réponse (~1 KB) :
{
"status": "success",
"data": {
"year": 2025,
"months": [
{
"month": "2025-01",
"year": 2025,
"month_number": 1,
"events": {
"passage_created": { "count": 1250, "sum_amount": 18500.00, "unique_users": 25 }
},
"totals": { "count": 1800, "sum_amount": 18500.00 }
},
...
]
}
}

---

5. Détail des événements (drill-down)

GET /api/events/stats/details?date=2025-12-22&event=login_failed&limit=50&offset=0

| Param  | Type   | Requis | Description                          |
| ------ | ------ | ------ | ------------------------------------ |
| date   | string | Oui    | Date YYYY-MM-DD                      |
| event  | string | Non    | Filtrer par type                     |
| limit  | int    | Non    | Max résultats (défaut: 50, max: 100) |
| offset | int    | Non    | Pagination (défaut: 0)               |

Réponse (~10 KB) :
{
"status": "success",
"data": {
"date": "2025-12-22",
"events": [
{
"timestamp": "2025-12-22T08:15:32Z",
"event": "login_failed",
"username": "jean.dupont",
"reason": "invalid_password",
"attempt": 2,
"ip": "192.168.x.x",
"platform": "ios",
"app_version": "3.5.2"
},
...
],
"pagination": {
"total": 3,
"limit": 50,
"offset": 0,
"has_more": false
}
}
}

---

6. Types d'événements disponibles

GET /api/events/stats/types

Réponse :
{
"status": "success",
"data": {
"auth": ["login_success", "login_failed", "logout"],
"passages": ["passage_created", "passage_updated", "passage_deleted"],
"sectors": ["sector_created", "sector_updated", "sector_deleted"],
"users": ["user_created", "user_updated", "user_deleted"],
"entities": ["entity_created", "entity_updated", "entity_deleted"],
"operations": ["operation_created", "operation_updated", "operation_deleted"],
"stripe": ["stripe_payment_created", "stripe_payment_success", "stripe_payment_failed", "stripe_payment_cancelled", "stripe_terminal_error"]
}
}

---

Codes d'erreur

| Code | Signification                                |
| ---- | -------------------------------------------- |
| 200  | Succès                                       |
| 400  | Paramètre invalide (date, plage trop grande) |
| 403  | Accès refusé (rôle insuffisant)              |
| 500  | Erreur serveur                               |

---

Super-admin uniquement

Le super-admin peut ajouter ?entity_id=X pour filtrer par entité :
GET /api/events/stats/summary?date=2025-12-22&entity_id=5

Sans ce paramètre, il voit les stats globales de toutes les entités.