Score de risque (risk_score)
Un risk_score est une évaluation quantifiée du risque associé à une company. Chaque calcul produit un nouvel enregistrement immuable — la plateforme conserve l'intégralité de l'historique des scores pour chaque entreprise.
Rôle
Le score de risque sert de signal quantitatif dans vos processus de décision : octroi de crédit, plafond de commande, déclenchement de vérifications renforcées. Il est produit par un moteur de scoring externe — votre propre modèle, un provider de risque, ou une règle interne — et enregistré sur la plateforme via l'API.
L'immutabilité de l'objet garantit une traçabilité complète : on peut retrouver quel score était en vigueur au moment d'une décision, comparer les résultats entre versions de modèle, et détecter automatiquement les dégradations ou améliorations du profil d'une entreprise.
Identifiant et structure
Chaque score porte un identifiant stable préfixé par rsk_. Le champ factors est un objet libre dont la structure est définie par votre modèle.
{
"object": "risk_score",
"id": "rsk_4c2e9f8a1b3d5e7f",
"company_id": "cmp_3a8f1d9c2b4e7f6a",
"score": 72,
"model_version": "credit-v2.1",
"factors": {
"payment_history": 88,
"outstanding_balance": 55,
"credit_utilization": 71,
"time_as_customer": 90
},
"source_reference": null,
"metadata": {},
"computed_at": "2026-06-17T08:00:00.000Z",
"created_at": "2026-06-17T08:01:00.000Z"
}Champs
| Champ | Type | Description |
|---|---|---|
id | string | Identifiant du score (préfixe rsk_). |
object | string | Toujours "risk_score". |
merchant_id | string | Marchand propriétaire du score. |
company_id | string | Entreprise noté (cmp_…). |
score | integer | Score de 0 à 100. Plus élevé = meilleur profil de risque. |
model_version | string | Identifiant de la version du modèle ayant calculé ce score. |
factors | object | Détail des contributeurs au score. Structure libre, définie par votre modèle. null si non fourni. |
source_reference | string | Référence dans votre système. Optionnel. |
metadata | object | Map plate de scalaires `string | number | boolean`, selon la convention metadata de l’API. |
computed_at | datetime | Horodatage du calcul par le modèle. |
created_at | datetime | Date d'enregistrement sur la plateforme. |
Score et interprétation
Le score est un entier entre 0 et 100. La convention est : plus le score est élevé, meilleur est le profil de risque — un score de 90 indique une entreprise fiable, un score de 20 indique un risque élevé. Cette convention est reflétée dans les événements : risk_score.degraded se déclenche quand le score baisse, risk_score.improved quand ilmonte.
Le champ model_version identifie la version du modèle ou de la règle qui a produit ce score. Il est libre et défini par votre système. Il permet de :
- comparer les scores d'une même company entre versions de modèle ;
- filtrer l'historique pour n'analyser que les scores d'une version donnée ;
- détecter les régressions lors du passage à un nouveau modèle.
Le champ factors est un objet JSON libre qui décrit les signaux ayant contribué au score. Sa structure est entièrement définie par votre modèle — la plateforme le stocke et le retourne tel quel, sans l'interpréter.
Historique et score courant
Chaque appel à POST /v1/risk-scores crée une nouvelle ligne indépendante. Le score précédent n'est jamais modifié ou remplacé. La liste complète des scores d'une company est accessible via :
GET /v1/risk-scores?company_id=cmp_3a8f
Les résultats sont triés par computed_at décroissant, le plus récent en premier.
Pour récupérer uniquement le score le plus récent d'une company (le score "courant"), utilisez l'endpoint dédié :
GET /v1/risk-scores/latest?company_id=cmp_3a8f&merchant_id=mrc_1a2b
{
"id": "rsk_4c2e",
"score": 72,
"model_version": "credit-v2.1"
}L’API retourne 404 lorsqu’aucun score n’existe pour cette company.
computed_at est l'horodatage du calcul par votre modèle (peut être antérieur à l'enregistrement). created_at est l'horodatage d'insertion sur la plateforme. Pour trier les scores chronologiquement, utilisez computed_at.Dans les processus
Il n'existe pas de node dédié à la création d'un risk_score. L'objet est typiquement alimenté par deux chemins :
- Système externe — votre moteur de scoring appelle directement
POST /v1/risk-scoresaprès chaque recalcul (batch nocturne, événement déclencheur, etc.). - Depuis un processus — un node connecteur appelle le provider de risque et retourne un score entier ; une action HTTP dans le processus appelle ensuite
POST /v1/risk-scorespour le persister.
Une fois persisté, le score courant d'une company est récupérable dans un processus via le node générique fetch_risk_score, qui accepte un identifiant préfixé rsk_ et retourne l'objet platform.risk_score.
Événements
Chaque création de score déclenche jusqu'à deux événements : un événement systématique sur la company, et un événement de direction si un score précédent existait.
| Événement | Déclencheur |
|---|---|
company.risk_score_updated | Emis à chaque création d'un nouveau score, avec un diff score avant/après si un score précédent existait. |
risk_score.degraded | Emis si le nouveau score est strictement inférieur au précédent. |
risk_score.improved | Emis si le nouveau score est strictement supérieur au précédent. |
Les trois événements portent l'objet risk_score complet dans leur payload. Les événements de direction incluent également un diff avec les scores avant et après, utilisable pour déclencher des actions conditionnelles dans vos processus (alerte, revue manuelle, mise à jour d'une limite de crédit) :
{
"id": "rsk_4c2e",
"object": "risk_score",
"company_id": "cmp_3a8f",
"score": 72,
"diff": {
"before": { "score": 68 },
"after": { "score": 72 }
}
}Si aucun score précédent n'existe pour la company (premier calcul), company.risk_score_updated est émis sans diff, et les événements risk_score.degraded / risk_score.improved ne sont pas déclenchés. Si le score est identique au précédent (delta = 0), seul company.risk_score_updated est émis.