L'intégration d'une API de risk scoring dans un système d'information change l'économie de la due diligence : au lieu de vérifier les fournisseurs un par un dans une interface dédiée, le scoring s'exécute automatiquement à chaque création de contact CRM, à chaque ouverture de fournisseur ERP, à chaque inscription marketplace. Ce guide technique présente les use cases, les patterns d'intégration, l'authentification et des exemples concrets en Python et curl.
Pourquoi intégrer plutôt qu'utiliser l'interface web
Volume et automatisation
Une PME qui contractualise avec 200 fournisseurs par an peut se contenter d'une interface web. Une plateforme marketplace qui onboarde 200 vendeurs par jour ne peut pas. L'API permet de traiter le volume sans charge humaine.
Cohérence des données
Quand le scoring s'exécute depuis l'ERP, le résultat est stocké directement dans la fiche fournisseur. Pas de copier-coller, pas de scoring perdu, pas d'incohérence entre l'outil de DD et la base de référence.
Workflows automatisés
Un score < 50 peut déclencher automatiquement : notification au compliance officer, suspension de la fiche fournisseur, blocage des paiements en attente, escalade au management. C'est impossible en mode interface manuelle.
Architecture type d'une intégration
Voici l'architecture standard recommandée pour une intégration robuste :
[ERP/CRM] ───► [Backend client] ───► [API RiskSonnar] ───► [Sources données]
│ │
│ ▼
│ [Webhook /score-changed]
└──────────────────────┘Trois flux principaux :
- Scan synchrone : à la création d'un fournisseur, le backend client appelle l'API et bloque le formulaire jusqu'à réception du score (60s max)
- Scan asynchrone par batch : un cron quotidien envoie les fournisseurs nouveaux ou modifiés en CSV bulk, reçoit les résultats par fichier
- Webhook événementiel : RiskSonnar pousse les changements de score vers le backend client (procédure collective détectée, sanction ajoutée, etc.)
Authentification — Bearer token
L'API RiskSonnar utilise un Bearer token simple, à inclure dans le header HTTP de chaque requête :
Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxxxxxBonnes pratiques :
- Stocker le token dans un secret manager (AWS Secrets Manager, Vault, Doppler) — jamais en dur dans le code
- Utiliser un token de test (rk_test_) en environnement de staging, et un token live (rk_live_) uniquement en production
- Rotation : régénérer le token tous les 90 jours minimum
- Scoping : créer plusieurs tokens si plusieurs équipes utilisent l'API, pour pouvoir révoquer indépendamment
Endpoints essentiels
POST /api/v1/scan — scan synchrone
curl -X POST https://api.risksonnar.com/api/v1/scan \
-H "Authorization: Bearer $RK_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Attijariwafa Bank",
"country": "MA"
}'Réponse type (60 secondes) :
{
"analysis_id": "abc-123-def",
"score_global": 72,
"rating": "B",
"decision": "approve_with_conditions",
"summary": "Etablissement bancaire majeur, regule par BAM...",
"sources_count": 24,
"alerts": [],
"report_pdf_url": "https://www.risksonnar.com/verify/abc-123-def"
}POST /api/v1/scan/bulk — scan par batch CSV
Pour un volume > 50 entités, utiliser le bulk pour éviter le rate limiting :
curl -X POST https://api.risksonnar.com/api/v1/scan/bulk \
-H "Authorization: Bearer $RK_TOKEN" \
-F "file=@suppliers.csv"Le CSV doit avoir les colonnes name et country. La réponse contient un job_id à interroger ensuite via GET /api/v1/scan/bulk/{job_id}.
GET /api/v1/person/{slug} — recherche dirigeant
Pour vérifier un dirigeant et récupérer toutes ses sociétés :
curl https://api.risksonnar.com/api/v1/person/thibaud-assier \
-H "Authorization: Bearer $RK_TOKEN"Permet de détecter les nominees professionnels (ex. dirigeant cumulant 6 536 sociétés).
POST /api/v1/webhooks — créer un abonnement
Pour recevoir les événements en push :
curl -X POST https://api.risksonnar.com/api/v1/webhooks \
-H "Authorization: Bearer $RK_TOKEN" \
-d '{
"url": "https://erp.client.com/risksonnar-webhook",
"events": ["scan.completed", "score.changed", "sanction.detected"]
}'Exemple Python — intégration ERP
import os
import requests
RK_TOKEN = os.environ["RISKSONNAR_TOKEN"]
RK_BASE = "https://api.risksonnar.com/api/v1"
def score_supplier(name: str, country: str = "FR") -> dict:
# Score un fournisseur, retourne le rapport complet.
response = requests.post(
f"{RK_BASE}/scan",
headers={"Authorization": f"Bearer {RK_TOKEN}"},
json={"name": name, "country": country},
timeout=90,
)
response.raise_for_status()
return response.json()
def on_supplier_created(supplier):
# Hook ERP appele a la creation d'un fournisseur.
result = score_supplier(supplier.legal_name, supplier.country)
supplier.risk_score = result["score_global"]
supplier.risk_rating = result["rating"]
supplier.risk_decision = result["decision"]
supplier.risk_report_url = result["report_pdf_url"]
supplier.save()
if result["score_global"] < 50:
notify_compliance(supplier, result)
supplier.status = "blocked_pending_review"
supplier.save()Vérification HMAC des webhooks
Chaque webhook envoyé par RiskSonnar inclut une signature HMAC-SHA256 dans le header X-RiskSonnar-Signature. Il est obligatoire de vérifier cette signature pour rejeter les requêtes forgées :
import hmac, hashlib
def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(), body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
@app.post("/risksonnar-webhook")
async def webhook_handler(request):
body = await request.body()
signature = request.headers.get("X-RiskSonnar-Signature", "")
if not verify_webhook(body, signature, WEBHOOK_SECRET):
return {"status": "invalid_signature"}, 401
payload = json.loads(body)
handle_event(payload)
return {"status": "ok"}Patterns d'intégration par use case
Use case 1 — Marketplace B2B
Onboarding d'un nouveau vendeur. Le scan s'exécute pendant que le vendeur remplit le reste du formulaire (~3 min). Si le score < 50 à la fin du formulaire, le compte est créé en statut "review" et un humain valide. Sinon, validation automatique.
Use case 2 — ERP achats
Tout fournisseur créé dans l'ERP est scoré au moment de la création. Le score est stocké comme attribut. Un cron mensuel re-scane les 100 fournisseurs avec le plus de paiements pour détecter les dégradations.
Use case 3 — CRM commercial
À la qualification d'un prospect (lead → opportunity), le scan vérifie l'absence de sanctions, le statut PEP, et la santé financière. Score affiché dans le pipeline pour aider le commercial à prioriser.
Use case 4 — Plateforme de financement
Avant tout déboursement, scan complet avec rapport PDF archivé pour traçabilité réglementaire. Webhook actif pour être alerté en temps réel si une procédure collective est ouverte sur un emprunteur en cours de remboursement.
Limites et bonnes pratiques
Rate limiting
Le rate limiting standard est de 60 requêtes/minute pour le plan Business. Au-delà, utiliser le bulk endpoint qui n'a pas cette limite. Sur un onboarding viral (par exemple lancement Product Hunt), prévoir un buffer ou un mode "scan reporté + email" pour absorber le pic.
Idempotence
Pour éviter de re-scoper la même entité plusieurs fois (et de consommer de la quota), utiliser le header Idempotency-Key avec un identifiant unique par entité (par exemple le SIRET).
Gestion des erreurs
L'API peut retourner :
- 200 : succès, score retourné
- 202 : accepté, scan en cours (pour bulk async)
- 400 : paramètres invalides (vérifier le format)
- 401 : token invalide ou révoqué
- 402 : quota dépassé (mode overage si activé, sinon blocage)
- 429 : rate limit dépassé (retry après délai indiqué dans header
Retry-After) - 500 : erreur serveur (retry exponentiel recommandé)
FAQ — Questions fréquentes
Quel plan inclut l'accès API ?
L'API publique est disponible sur le plan Business et au-delà. Le plan inclut 250 scans/mois, 10 sièges, webhooks, et audit 5 ans. Au-delà du quota inclus, l'overage est facturé en pay-per-scan.
Comment tester sans payer ?
Le mode test (token rk_test_) renvoie des données fictives sans consommer de quota. Suffisant pour développer l'intégration. Une fois prêt, switcher sur le token live.
Quelle latence en production ?
Scan synchrone : 30-90 secondes selon la complexité de l'entité (médiane 45s). Bulk : ~2 minutes pour 100 entités. Webhook : push en moins de 5 secondes après l'événement.
Y a-t-il un SDK officiel ?
Un client Python officiel est en cours de développement. Pour l'instant, l'intégration se fait directement via requests. Un SDK Node.js et PHP suivront. Si vous avez un besoin urgent, contactez-nous.
RiskSonnar API v1 est disponible sur le plan Business. Documentation complète, exemples de code et SDK : /api/v1/docs. Voir les plans →