Statistiques (Stats)

Base URL : /api/v1/admin/org/stats (stats org) · /api/v1/stats (stats basiques) · /api/v1/admin/system/stats (stats globales)

Stats d'organisation

`GET /admin/org/stats/dashboard`

Résumé du tableau de bord pour une organisation.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/dashboard
Authorization: Bearer ...

Réponse (200):

{
  "cards": {
    "total": 150,
    "active": 142,
    "unassigned": 5,
    "deactivated": 3,
    "lost": 0
  },
  "transactions_today": {
    "count": 68,
    "amount_cents": 337500,
    "by_type": {}
  },
  "products": { "total": 42, "low_stock": 3 },
  "sites_count": 2,
  "pending_reservations": 5,
  "holders": { "total": 200, "new_this_month": 12 },
  "active_operators_today": 8,
  "currency": "XOF"
}

`GET /admin/org/stats/revenue-by-type`

Revenus groupés par type de transaction.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/revenue-by-type?from=2025-06-01&to=2025-06-30
Authorization: Bearer {token}

Paramètres de query :

Param	Type	Défaut	Description
`from`	date	30 jours	Date de début
`to`	date	today	Date de fin

Réponse (200):

{
  "data": [
    { "type": "credit_cash", "total_cents": 500000, "count": 120 },
    { "type": "debit_purchase", "total_cents": 350000, "count": 450 }
  ]
}

`GET /admin/org/stats/top-products`

Produits les plus vendus.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/top-products?from=2025-06-01&to=2025-06-30&limit=10
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "name": "Café Noir", "count": 320, "total_cents": 320000 }
  ]
}

`GET /admin/org/stats/sites-revenue`

Revenus par site.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/sites-revenue
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "id": "uuid", "name": "Site A", "count": 890, "total_cents": 1250000 }
  ]
}

`GET /admin/org/stats/hourly`

Distribution horaire des transactions.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/hourly?date=2025-06-15
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "hour": 8, "count": 45, "total_cents": 225000 },
    { "hour": 12, "count": 120, "total_cents": 600000 }
  ]
}

`GET /admin/org/stats/holders`

Statistiques des détenteurs de cartes.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/holders
Authorization: Bearer {token}

Réponse (200):

{
  "total_holders": 200,
  "active_holders": 180,
  "new_in_period": 15
}

`GET /admin/org/stats/recharges`

Rechargements par jour (cash vs mobile).

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/recharges?from=2025-06-01&to=2025-06-30
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "date": "2025-06-01", "cash_cents": 200000, "cash_count": 40, "mobile_cents": 50000, "mobile_count": 5 }
  ]
}

`GET /admin/org/stats/sales`

Ventes quotidiennes.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/sales?from=2025-06-01&to=2025-06-30
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "date": "2025-06-01", "tx_count": 45, "total_cents": 225000 }
  ]
}

`GET /admin/org/stats/balances`

Évolution des soldes (crédits/débits nets par jour).

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/balances?from=2025-06-01&to=2025-06-30
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "date": "2025-06-01", "credit_cents": 250000, "debit_cents": 95000, "net_cents": 155000 }
  ]
}

`GET /admin/org/stats/reservations`

Statistiques des réservations par jour.

Permissions requises : analytics.read

GET /api/v1/admin/org/stats/reservations?from=2025-06-01&to=2025-06-30
Authorization: Bearer {token}

Réponse (200):

{
  "data": [
    { "date": "2025-06-01", "total": 10, "pending": 2, "ready": 3, "collected": 4, "cancelled": 1, "refunded": 0, "uncollected": 0 }
  ]
}

`GET /stats/daily`

Stats quotidiennes sur une période (basique).

Permissions requises : analytics.read

GET /api/v1/stats/daily?from=2025-06-01&to=2025-06-30&site_id=...
Authorization: Bearer ...

Paramètres de query :

Param	Type	Défaut	Description
`from`	date	30 jours	Date de début
`to`	date	today	Date de fin
`site_id`	UUID	tous	Filtrer par site

Réponse (200):

{ "data": [ { "day": "2025-06-01", "credits_count": 45, "debits_count": 38, "credits_total_cents": 225000, "debits_total_cents": 95000 } ] }

`GET /stats/export`

Export des stats au format CSV via une URL signée.

Permissions requises : analytics.read

GET /api/v1/stats/export?from=2025-06-01&to=2025-06-30
Authorization: Bearer ...

Paramètres de query :

Param	Type	Défaut	Description
`from`	date	30 jours	Date de début
`to`	date	today	Date de fin
`site_id`	UUID	tous	Filtrer par site

Réponse (200):

{
  "url": "https://storage.caffette.app/exports/org-xxx-2025-06.csv?token=...",
  "filename": "export-cours-lumiere-2025-06-01_2025-06-30.csv",
  "rows": 1250
}

Analytics d'organisation (avec comparatif)

Base URL : /api/v1/admin/org/analytics

Ces endpoints acceptent les paramètres optionnels compare_from/compare_to pour la comparaison avec une période précédente.

Permissions requises : analytics.read

Endpoint	Description
`GET /admin/org/analytics/overview`	Vue d'ensemble avec comparaison
`GET /admin/org/analytics/revenue-by-type`	Revenus par type avec évolution
`GET /admin/org/analytics/top-products`	Top produits avec comparatif
`GET /admin/org/analytics/sites-revenue`	Revenus par site avec comparatif
`GET /admin/org/analytics/avg-transaction`	Montant moyen par transaction
`GET /admin/org/analytics/product-categories`	Répartition par catégorie
`GET /admin/org/analytics/growth`	Taux de croissance période
`GET /admin/org/analytics/peak-activity`	Pics d'activité

Stats globales (cross-organisation)

important

Ces endpoints requièrent le rôle Platform (N2) avec la permission stats.exhaustive.read.

Base URL : /api/v1/admin/system/stats

`GET /admin/system/stats/summary`

Vue agrégée de toutes les organisations.

GET /api/v1/admin/system/stats/summary
Authorization: Bearer {platform_token}

Réponse (200):

{
  "organizations_count": 5,
  "total_sites": 12,
  "total_active_cards": 892,
  "transactions_today": 347,
  "revenue_today_cents": 1735000,
  "currency": "XOF"
}

`GET /admin/system/stats/daily`

Stats quotidiennes agrégées sur 90 jours.

GET /api/v1/admin/system/stats/daily
Authorization: Bearer {platform_token}

Réponse (200):

{
  "data": [
    {
      "organization_id": "550e8400-e29b-41d4-a716-446655440001",
      "organization_name": "Cours Lumière",
      "day": "2025-06-10",
      "site_id": "...",
      "type": "credit_cash",
      "tx_count": 45,
      "total_cents": 225000,
      "unique_cards": 38
    }
  ]
}

`GET /admin/system/stats/revenue-by-type`

Revenus cross-org groupés par type de transaction.

GET /api/v1/admin/system/stats/revenue-by-type?from=2025-06-01&to=2025-06-30
Authorization: Bearer {platform_token}

Réponse (200):

{
  "data": [
    {
      "type": "credit_cash",
      "total_cents": 1500000,
      "count": 450
    }
  ]
}

`GET /admin/system/stats/top-products`

Top produits cross-org.

GET /api/v1/admin/system/stats/top-products?from=2025-06-01&to=2025-06-30&limit=10
Authorization: Bearer {platform_token}

Réponse (200):

{
  "data": [
    {
      "product_id": "uuid",
      "product_name": "Café Noir",
      "organization_name": "Cours Lumière",
      "quantity_sold": 1200,
      "total_cents": 1200000
    }
  ]
}

`GET /admin/system/stats/sites-revenue`

Revenus cross-org par site.

GET /api/v1/admin/system/stats/sites-revenue
Authorization: Bearer {platform_token}

Réponse (200):

{
  "data": [
    {
      "site_id": "uuid",
      "site_name": "Site A",
      "organization_name": "Cours Lumière",
      "total_cents": 2500000,
      "transaction_count": 1800
    }
  ]
}

`GET /admin/system/stats/hourly`

Distribution horaire cross-org des transactions.

GET /api/v1/admin/system/stats/hourly?date=2025-06-15
Authorization: Bearer {platform_token}

Réponse (200):

{
  "data": [
    {
      "hour": 8,
      "count": 145,
      "total_cents": 725000
    }
  ]
}

`GET /admin/system/stats/holders`

Statistiques cross-org des détenteurs de cartes.

GET /api/v1/admin/system/stats/holders
Authorization: Bearer {platform_token}

Réponse (200):

{
  "total_holders": 5000,
  "active_holders": 4200,
  "holders_with_balance": 3800,
  "top_holders": [
    {
      "holder_id": "uuid",
      "name": "Jean Dupont",
      "organization_name": "Cours Lumière",
      "balance_cents": 50000,
      "transaction_count": 120
    }
  ]
}

`GET /admin/system/stats/dashboard`

Tableau de bord cross-org complet.

GET /api/v1/admin/system/stats/dashboard
Authorization: Bearer {platform_token}

Réponse (200):

{
  "summary": {
    "organizations_count": 5,
    "total_sites": 12,
    "total_cards": 5000,
    "active_cards": 4200,
    "total_holders": 5000,
    "revenue_today_cents": 1735000
  },
  "revenue_by_type": [ ... ],
  "top_products": [ ... ],
  "sites_revenue": [ ... ],
  "hourly_distribution": [ ... ]
}

Détection d'anomalies

Les jobs automatisés détectent les anomalies de solde bas :

flowchart TD
    A[Job nocturne 06:00] --> B{card.balance < threshold ?}
    B -->|Oui| C[Créer anomaly_notifications]
    B -->|Non| D[Ignorer]
    C --> E[Envoyer notification]
    E --> F[Email / WhatsApp]
    F --> G[Marquer sent]

Seuil par défaut	Personnalisable
3000 XOF	Par organisation

Le seuil est configurable par organisation dans settings :

{
  "default_anomaly_threshold_cents": 3000
}

Analytics système (cross-organisation avec comparatif)

Base URL : /api/v1/admin/system/analytics

Endpoint	Description
`GET /admin/system/analytics/overview`	Vue d'ensemble globale
`GET /admin/system/analytics/top-products`	Top produits toutes organisations
`GET /admin/system/analytics/sites-revenue`	Revenus par site toutes organisations
`GET /admin/system/analytics/transaction-breakdown`	Répartition des transactions
`GET /admin/system/analytics/growth`	Croissance globale
`GET /admin/system/analytics/inactive-cards`	Cartes inactives

Permissions requises : stats.exhaustive.read

Stats d'organisation​

GET /admin/org/stats/dashboard​

GET /admin/org/stats/revenue-by-type​

GET /admin/org/stats/top-products​

GET /admin/org/stats/sites-revenue​

GET /admin/org/stats/hourly​

GET /admin/org/stats/holders​

GET /admin/org/stats/recharges​

GET /admin/org/stats/sales​

GET /admin/org/stats/balances​

GET /admin/org/stats/reservations​

GET /stats/daily​

GET /stats/export​

Analytics d'organisation (avec comparatif)​

Stats globales (cross-organisation)​

GET /admin/system/stats/summary​

GET /admin/system/stats/daily​

GET /admin/system/stats/revenue-by-type​

GET /admin/system/stats/top-products​

GET /admin/system/stats/sites-revenue​

GET /admin/system/stats/hourly​

GET /admin/system/stats/holders​

GET /admin/system/stats/dashboard​

Détection d'anomalies​

Analytics système (cross-organisation avec comparatif)​

Stats d'organisation

`GET /admin/org/stats/dashboard`

`GET /admin/org/stats/revenue-by-type`

`GET /admin/org/stats/top-products`

`GET /admin/org/stats/sites-revenue`

`GET /admin/org/stats/hourly`

`GET /admin/org/stats/holders`

`GET /admin/org/stats/recharges`

`GET /admin/org/stats/sales`

`GET /admin/org/stats/balances`

`GET /admin/org/stats/reservations`

`GET /stats/daily`

`GET /stats/export`

Analytics d'organisation (avec comparatif)

Stats globales (cross-organisation)

`GET /admin/system/stats/summary`

`GET /admin/system/stats/daily`

`GET /admin/system/stats/revenue-by-type`

`GET /admin/system/stats/top-products`

`GET /admin/system/stats/sites-revenue`

`GET /admin/system/stats/hourly`

`GET /admin/system/stats/holders`

`GET /admin/system/stats/dashboard`

Détection d'anomalies

Analytics système (cross-organisation avec comparatif)