Des décisions nominatives via l’API

Quand votre CRM ou votre outil de suivi clôt une alerte via l’API Smart Oversight, l’appel est authentifié par une clé d’API. La clé prouve que l’appel est autorisé. Elle ne dit pas qui, chez vous, a examiné le résultat et pris la décision.

C’est pourtant ce que demandera un réviseur ou votre autorité de surveillance. Chaque appel à l’API peut désormais nommer le collaborateur pour le compte duquel il est fait, et la décision est enregistrée à son nom.

Nommer le collaborateur

Le collaborateur est désigné dans un en-tête facultatif de la requête, c’est-à-dire une information technique transmise avec l’appel. Votre outil y indique soit son identifiant de membre, usr_…, soit email: suivi de son adresse. Une adresse seule, sans ce préfixe, est refusée. Toutes les opérations de l’API acceptent cet en-tête.

L’API cherche la personne parmi les membres de votre espace de travail, invités compris. Si aucun membre actif ne correspond, elle répond 400 actor_unknown. Une valeur mal formée donne 400 resource_id_invalid.

La décision est alors enregistrée avec le collaborateur comme auteur et la clé comme intermédiaire qui agit pour son compte, selon le modèle de délégation décrit par la RFC 8693. L’historique des statuts de l’alerte renvoie à son compte utilisateur, comme s’il avait traité l’alerte dans l’application.

Le rôle du collaborateur compte aussi

Une validation exige toujours que la clé dispose du droit (scope) alerts:validate. Quand elle est faite au nom d’un collaborateur, l’API vérifie en plus son rôle. La validation n’est enregistrée que s’il est votre responsable LCB/FT (MLRO) dans cet espace de travail. Si vous nommez par exemple un responsable conformité qui n’est pas MLRO, l’API répond 403 actor_not_permitted.

Sans ce contrôle, la piste d’audit pourrait attribuer une validation à quelqu’un qui n’avait pas le droit de la donner. L’API refuse donc l’appel.

Les rôles sont propres à chaque espace de travail. Une même personne peut être MLRO dans l’un et responsable conformité dans un autre, et c’est son rôle dans l’espace de travail de la clé qui est vérifié.

Retrouver les collaborateurs avec GET /v2/users

GET /v2/users liste les membres actifs de l’espace de travail, avec leur identifiant, leur adresse e-mail, leur nom complet et leurs rôles. L’appel demande le droit users:read. Votre outil s’en sert pour relier ses propres utilisateurs à leurs comptes Smart Oversight, et pour savoir lesquels peuvent valider.

GET /v2/users

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "usr_66f1a2b3c4d5e6f708191b2c",
      "email": "<address>",
      "full_name": "John Doe",
      "roles": ["MLRO"]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Enregistrer une décision

La décision passe par POST /v2/alerts/{id}/review, qui demande le droit alerts:write. Le champ status vaut OPEN, DONE ou VALIDATED. Le champ resolution prend l’une des valeurs UNRESOLVED, NOT_RELATED_TO_CLIENT, TRUE_RELEVANT ou TRUE_NOT_RELEVANT.

Vous pouvez y joindre un commentaire, qui s’ajoute à celui qui existe déjà sans jamais le remplacer. Vous pouvez aussi demander des actions (MARK_AS_PEP, REPORT_INTERNATIONAL_SANCTION ou REPORT_ADMINISTRATIVE_SANCTION), qui posent l’indicateur correspondant sur chaque client concerné par l’alerte.

Dans l’exemple suivant, le MLRO confirme qu’un résultat de la liste de PPE concerne bien le client, et marque ce client comme PPE.

# Ajoutez l’en-tête qui nomme le collaborateur (voir la documentation).
curl -X POST "$API_BASE/v2/alerts/alr_66f1a2b3c4d5e6f708194000/review" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "VALIDATED",
    "resolution": "TRUE_RELEVANT",
    "comment": "Correspondance confirmée avec la copie du passeport au dossier.",
    "actions": ["MARK_AS_PEP"]
  }'

Quand plusieurs screenings ont trouvé le même résultat, celui-ci est enregistré une fois pour chacun. La décision s’applique à toutes ces copies, comme dans l’application.

Pour trouver les alertes à traiter, GET /v2/alerts filtre par statut et par source (listes de sanctions, listes de PPE ou recherche internet). GET /v2/clients/{ref}/alerts donne les alertes d’un client, désigné par son identifiant cli_… ou par votre propre référence ext:….

Un seul historique par alerte

Une décision nominative apparaît dans l’historique de l’alerte, attribuée au collaborateur, sous la même forme que les décisions prises dans l’application. Le réviseur consulte donc un seul historique pour chaque alerte, quel que soit l’outil qui a servi à l’examen.

Sans collaborateur nommé

Si l’en-tête est absent, la décision est enregistrée au nom de la clé d’API. L’identifiant de la clé reste une trace, mais il ne désigne personne. La réponse le signale par un en-tête d’avertissement.

L’API n’a alors aucun rôle à vérifier, et seuls les droits de la clé s’appliquent. Nous vous conseillons de nommer le collaborateur à chaque décision.

Pour aller plus loin

Cet article fait suite à la présentation de l’API Smart Oversight et à l’article sur les webhooks pour les screenings et les alertes. La page Intégrations présente ce que couvre l’API, et Connecter votre screening KYC & LCB/FT à votre CRM décrit une intégration complète, de la création du client à l’examen des alertes.