Aller au contenu principal

Intelligence

Ikawaari expose une surface Intelligence dédiée pour les vues analytiques marchandes orientées :

  • KPIs
  • trust scoring
  • lifecycle marchand
  • décisions et recommandations
  • snapshot insight le plus récent
  • matérialisation explicite d’un snapshot journalier

Cette surface est actuellement servie par le module Ikawaari.Intelligence, avec compatibilité maintenue côté merchant/reporting pour les flux historiques.

Routes actuellement disponibles​

  • GET /api/v1/intelligence/summary
  • GET /api/v1/intelligence/kpis
  • GET /api/v1/intelligence/trust
  • GET /api/v1/intelligence/signals
  • GET /api/v1/intelligence/lifecycle
  • GET /api/v1/intelligence/decisions
  • GET /api/v1/intelligence/recommendations
  • GET /api/v1/intelligence/snapshots/latest
  • POST /api/v1/intelligence/snapshots/materialize

Authentification​

Les endpoints Intelligence sont protégés et acceptent actuellement :

  • clé API (Bearer ik_test_... / ik_live_...)
  • JWT marchand

Exemple :

Authorization: Bearer ik_test_123

Paramètres communs de lecture​

La plupart des endpoints de lecture utilisent MerchantInsightsQueryDto avec les champs suivants :

ParamètreTypeDescription
merchantIdguidMerchant ciblé ; peut être implicite si le contexte marchand est déjà résolu
fromstringBorne basse ISO 8601 optionnelle
tostringBorne haute ISO 8601 optionnelle
currencystringDevise de lecture, par ex. XOF
maxResultCountintegerNombre max de résultats pour les vues de signaux

Endpoints​

Summary​

GET /api/v1/intelligence/summary?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne une vue agrégée avec :

  • kpis
  • trust
  • topSignals
  • insights

KPIs​

GET /api/v1/intelligence/kpis?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne un MerchantKpiSnapshotDto.

Trust​

GET /api/v1/intelligence/trust?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne un MerchantTrustProfileDto explicable.

Signals​

GET /api/v1/intelligence/signals?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF&maxResultCount=10

Retourne les signaux business principaux déjà agrégés.

Lifecycle​

GET /api/v1/intelligence/lifecycle?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne le MerchantLifecycleProfileDto courant.

Decisions​

GET /api/v1/intelligence/decisions?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne des LifecycleDecisionEnvelopeDto avec :

  • stage lifecycle
  • score de confiance
  • code de décision
  • actions recommandées / bloquées
  • facteurs d’explication

Recommendations​

GET /api/v1/intelligence/recommendations?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne une vue plus compacte orientée recommandations (LifecycleRecommendationDto).

Latest snapshot​

GET /api/v1/intelligence/snapshots/latest?merchantId={merchantId}&to=2026-05-01T00:00:00Z&currency=XOF

Retourne le dernier MerchantInsightDailySnapshotDto disponible.

Materialize snapshot​

POST /api/v1/intelligence/snapshots/materialize
Content-Type: application/json

{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "snapshotDateUtc": "2026-05-01T00:00:00Z",
  "currency": "XOF",
  "maxResultCount": 50
}

Force la matérialisation d’un snapshot journalier, puis retourne le snapshot produit.

Notes d’implémentation actuelles​

Store prioritaire​

À date :

  • lifecycle est lu prioritairement depuis le state store Intelligence
  • recommendations sont lues prioritairement depuis le state store Intelligence
  • le snapshot insight complet reste compatible avec ReportingFact

Hypothèse de déploiement retenue​

La livraison actuelle suppose :

  • nouvelle base
  • pas de backfill historique

Le state store Intelligence est donc rempli à partir des nouvelles matérialisations / nouvelles lectures, sans reprise de l’historique existant.

Compatibilité avec merchant/reporting​

La surface merchant/reporting reste présente pour compatibilité. En pratique :

  • merchant/reporting agit encore comme façade legacy pour les reads intelligence
  • la nouvelle surface canonique pour les capacités trust/lifecycle/recommendations est api/v1/intelligence/*

Pages liées​