Version: 1.0.0

API Argus — Détection de fraude

API publique d'Argus, le service de détection de fraude temps réel pour le mobile money.

Le backend du client appelle Argus avant d'exécuter une transaction : Argus renvoie une décision (ALLOW / VERIFY / QUARANTINE / BLOCK) accompagnée d'un score de risque et des principaux facteurs explicatifs.

Démarrage rapide

1. Récupérer une clé de licence

L'API n'a pas d'inscription en libre-service : un administrateur de votre instance crée la clé, soit depuis l'écran Paramètres de la console, soit directement via POST /v1/licenses (jeton Bearer d'un compte admin). La clé est renvoyée en clair une seule fois à la création — copiez-la immédiatement dans la configuration de votre backend, elle n'est plus jamais affichable ensuite (GET /v1/licenses ne renvoie que sa forme masquée).

2. L'en-tête d'authentification

Les appels serveur → serveur (/v1/transactions/score, /v1/auth-events) s'authentifient avec cette clé, dans l'en-tête X-License-Key — pas un jeton Bearer :

X-License-Key: <votre clé de licence>

Le Bearer (Authorization: Bearer <jeton>) est réservé aux opérateurs du dashboard (analystes/admins humains), obtenu via POST /v1/auth/login — un autre public, un autre mécanisme, à ne pas mélanger.

3. Premier appel — POST /v1/transactions/score

À appeler avant d'exécuter la transaction chez vous :

curl -X POST https://votre-instance.example/v1/transactions/score \
  -H "Content-Type: application/json" \
  -H "X-License-Key: <votre clé de licence>" \
  -d '{
    "transaction_id": "TXN-2026-0001",
    "sender_account_id": "2250700000000",
    "beneficiary_account_id": "2250711111111",
    "amount": 150000,
    "currency": "XOF",
    "timestamp": "2026-09-03T10:11:59.000Z",
    "transaction_channel": "app",
    "transaction_type": "transfer",
    "device_id": "device-abc-123"
  }'

transaction_id est la clé d'idempotence : un rejeu du même identifiant renvoie 409 DUPLICATE_TRANSACTION plutôt que de recalculer.

4. Codes d'erreur réellement renvoyés par /score

Relevés dans le code (common/errors), pas supposés :

Code	HTTP	Sens
LICENSE_MISSING	401	En-tête X-License-Key absent.
LICENSE_INVALID / LICENSE_EXPIRED / LICENSE_SUSPENDED	403	Clé inconnue, expirée, ou licence suspendue.
VALIDATION_ERROR	422	Corps de requête invalide — le détail champ par champ est dans error.details.
DUPLICATE_TRANSACTION	409	transaction_id déjà reçu (rejeu).
INTERNAL_ERROR	500	Erreur interne inattendue.

Sur l'indisponibilité du moteur ML, précisément : contrairement à ce qu'on pourrait attendre, une panne du moteur ML ne renvoie pas d'erreur 503. TransactionsService#score intercepte l'échec (timeout, indisponibilité, réponse inexploitable) et répond 200 avec une décision de repli fail-closed — jamais en dessous de QUARANTINE, ml_score: null, model_version: "fail-closed". Le code applicatif FAIL_CLOSED (503) existe dans le catalogue d'erreurs mais n'est actuellement jamais émis par cette route : votre intégration doit lire la decision de la réponse 200, pas seulement le statut HTTP, pour détecter ce repli.

Conventions

• Préfixe de version : toutes les routes sont servies sous /v1.
• Format des dates : ISO 8601 avec fuseau (2026-09-03T10:12:00.000Z).
• Devise par défaut : XOF (franc CFA), code ISO 4217 sur 3 lettres.
• Idempotence : le scoring est idempotent sur transaction_id ; un rejeu renvoie 409 DUPLICATE_TRANSACTION.
• Pagination : les listes acceptent page, limit (max 100), sortOrder, et renvoient { data, total, page, limit }.

Enveloppe d'erreur

Toute réponse non 2xx a la même structure :

{
  "error": {
    "code": "DUPLICATE_TRANSACTION",
    "message": "Transaction « TXN-2026-0001 » déjà reçue et scorée.",
    "status": 409,
    "details": [],
    "path": "/v1/transactions/score",
    "method": "POST",
    "request_id": "01JBR9X2K7Q0YV3M8N4P5T6R7S",
    "timestamp": "2026-09-03T10:12:00.000Z"
  }
}

Le champ code est stable et contractuel : branchez votre logique dessus, jamais sur le message (susceptible d'évoluer ou d'être traduit).

Authentification

• Licence (intégration serveur → serveur) : en-tête X-License-Key — voir « Démarrage rapide » ci-dessus.
• Opérateur dashboard : jeton Bearer obtenu via POST /v1/auth/login.

Authentication

API Key: license

Clé de licence pour les intégrations serveur → serveur.

Security Scheme Type:	apiKey
Header parameter name:	X-License-Key

HTTP: Bearer Auth

Jeton d’accès opérateur (dashboard).

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

Contact

Équipe Argus: support@argus.local

URL: https://argus.local

License