5. Incidentes¶

5.1 Descripción general¶

El servicio de Incidentes de Trak.e es una herramienta central diseñada para la gestión integral de alertas y casos. Permite a las organizaciones identificar, analizar y resolver eficientemente situaciones críticas relacionadas con personas físicas o jurídicas. + Este servicio permite centralizar y estandarizar la respuesta operativa ante distintos tipos de riesgo. Estos pueden incluir: hits en listas de sanciones o terrorismo, cálculos de riesgo alto o comportamientos transaccionales inusuales. Al proporcionar un marco robusto para la documentación, colaboración y seguimiento del ciclo de vida de cada situación, Incidentes asegura una gestión transparente y auditable, facilitando la toma de decisiones y la aplicación de las medidas necesarias por parte de los operadores de back-office.

En el ecosistema de Trak.e, el término incidente se utiliza como un concepto abarcador para referirse a dos entidades principales: las alertas y los casos. Una alerta representa una notificación singular que surge de una perspectiva de riesgo específica, ya sea por un "hit" en una lista (como sanciones o terroristas) o un cálculo de riesgo elevado, requiere un análisis y una acción por parte de los operadores de back-office. Por otro lado, un caso es un tipo particular de alerta diseñado para agrupar múltiples alertas que pertenecen a un mismo "legajo", permite una gestión conjunta y hereda estados y comentarios de cierre del caso padre. Esta distinción permite a Trak.e manejar tanto eventos individuales como consolidar investigaciones complejas de manera eficiente.

5.2 Propiedades comunes de los incidentes (casos y alertas)¶

El servicio representa un incidente mediante un conjunto de propiedades. Las más importantes se detallan a continuación:

• dprofile_id: Identificador del legajo que generó la alerta. El término legajo se refiere a la entidad central gestionada por trak.e. Un legajo representa la información consolidada de una persona física o jurídica dentro de Trak.e, incluyendo sus datos personales, información KYC (Know Your Customer) y los resultados de los procesos de monitoreo. En esencia, el legajo es el perfil centralizado sobre el cual se aplican las reglas de monitoreo y se generan las alertas. El dprofile_id es el identificador único de este legajo en el sistema.
• user_id: Identificador del usuario de la plataforma asignado a trabajar en la alerta.
• title: Título de la alerta.
• incident_type: Tipo del alerta (ejemplo: pep_blacklist_hit en el caso de tener un hit en una lista de personas expuestas políticamente). Para los casos, se utiliza el tipo case.
• state: Estado de la alerta (ejemplo: abierto, cerrado, en progreso).
• severity: Severidad de la alerta (ejemplo: alto, medio, bajo). Las alertas se crean con una severidad por defecto que puede ser configurable por tipo de alerta, e incluso por regla para aquellas alertas que sean el resultado de una regla de monitoreo transaccional o de monitoreo de legajos.
• priority: Prioridad de la alerta (ejemplo: alto, medio, bajo). Las alertas se crean con una prioridad por defecto que puede ser configurable por tipo de alerta, e incluso por regla para aquellas alertas que sean el resultado de una regla de monitoreo transaccional o de monitoreo de legajos.
• due_date: Fecha de vencimiento de la alerta. Las alertas se crean con una fecha de vencimiento por defecto que puede ser configurable por tipo de alerta.

5.2.1 Usuario asignado.¶

Se puede asignar una alerta o caso a un usuario de la plataforma mediante el atributo user_id. Para asegurarse de que el usuario puede tratar la alerta, se chequea que dicho usuario posea todos los siguientes permisos:

La lista de usuarios que pueden tomar incidentes o tareas es la misma.

5.2.2 Tareas¶

Un incidente (alerta o caso) puede tener asociada una lista de tareas. Son utilizadas para asignar actividades a diferentes usuarios (o al mismo) para su resolución, y que asiste a la investigación/resolución de la alerta.

5.2.3 Etiquetas¶

Se puede marcar una alerta utilizando strings arbitrarios como etiquetas. Una etiqueta tiene una longitud mínima de 2 caracteres y máxima de 20 caracteres.

5.2.4 Gestión de casos¶

Los casos son un tipo de incidente dentro de trak.e que sirven para agrupar diferentes alertas pertenecientes al mismo legajo y tratarlas a todas de forma conjunta, heredando estas los estados y comentarios de cierre del caso al cual pertenecen.

La agrupación de alertas en un caso puede hacerse de forma manual mediante la UI o por API, o bien de forma automática cuando las alertas en cuestión caigan dentro del criterio de agrupación automático configurado.

Solo puede haber un criterio de agrupación automática activo a la vez. Dicho criterio se crea indicando el periodo y una condición de agrupamiento. El periodo se refiere al rango en el que se quiere que estén las alertas a agrupar (puede ser por hora, dia, semana o mes). La condición de agrupamiento puede ser por tipo de incidente, por nombre de regla (es decir la regla que hizo que se active una alerta) o siempre, que agrupa cualquier tipo de alerta.

Es posible agregar nuevas alertas a un caso, así como también desvincular alertas de un caso al que pertenecen.

Es posible eliminar un caso, al hacerlo las alertas que el mismo contenía se desvinculan automáticamente y se borran los documentos cargados.

La fecha de vencimiento de un caso es la fecha de vencimiento de la alerta más próxima a vencer. Al crear un caso se asigna como fecha de vencimiento la fecha de vencimiento de la alerta más cercana. Al agregar una alerta a un caso, la fecha de vencimiento se actualiza para reflejar la fecha de vencimiento de la alerta más cercana, si correspondiese.

5.2.5 Tipos de alerta¶

Trak.e ofrece una amplía lista de tipos de alertas precargados y listo para usar, entre los que se incluyen:

• adverse_news_blacklist_hit: El legajo fue encontrado en una lista de monitoreo de noticias adversas.
• obligated_subject_blacklist_hit: El legajo fue encontrado en una lista de monitoreo de sujetos obligados.
• pep_blacklist_hit: El legajo fue encontrado en una lista de monitoreo de personas expuestas politicamente.
• sanctioned_blacklist_hit: El legajo fue encontrado en una lista de sanciones (ejemplo: OFAC).
• terrorist_blacklist_hit: El legajo fue encontrado en una lista de terrorismo.
• wanted_blacklist_hit: El legajo ha sido encontrado en una lista de buscados, por ejemplo, en las listas publicadas por el FBI o por Interpol.
• other_blacklist_hit: El legajo fue encontrado en una lista de monitoreo - cuando no aplique un tipo más específico.
• trx_aml_alert: El legajo exhibe un comportamiento transaccional inusual, por su número, cantidad o características no se enmarcan dentro del sistema y prácticas normales de un negocio, una industria o de un sector determinado. Estas alertas deben ser revisadas por analistas de prevención de lavado de dinero y financiamiento del terrorismo o por analistas de riesgo para determinar si la misma es sospechosa y tomar las acciones correspondientes si fuera el caso.
• trx_fraud_alert: El legajo exhibe un comportamiento transaccional que lo hace sospechoso de estar involucrado en un uso fraudulento del sistema.
• trx_normative_alert: El legajo exhibe un comportamiento transaccional que, sin ser inusual o sospechoso, debe ser revisado por un analista de backoffice.
• doc_due: Un documento relacionado a este legajo ha alcanzado su fecha de vencimiento.
• doc_missing: Falta en este legajo un documento que fue marcado como requerido siguiendo alguna regla de negocio de monitoreo de legajo.
• doc_notice: Un documento en este legajo esta por expirar.
• due_diligence: Una debida diligencia continua deberia llevarse a cabo en este legajo para asegurar que los documentos, datos e información recopilada dentro del proceso KYC se mantenga actualizada y pertinente.
• high_risk: El legajo tiene riesgo alto, o bien, ha experimentado un aumento en su scoring de riesgo de manera inusual.
• other: Tipo generico para otros tipos de alerta no contemplados.

Además de incluir un tipo generico para alertas manuales, trak.e ofrece la posibilidad de crear nuevos tipos de alertas para cubrir las necesidades de la organización. Estos tipos de alertas pueden ser utilizados tanto en reglas de monitoreo, como bien para altas manuales de incidentes. Aplicaciones externas también pueden crear incidentes en la plataforma via APIs.

5.2.6 Información adicional¶

Cada tipo de alerta contiene una información adicional específica que depende del tipo de alerta con la que estemos tratando. Por ejemplo, para las alertas de monitoreo transaccional para fraude, se incluye la transacción que ocasionó que se dispare la alerta.

Para los tipos de alertas creados por la organización, se puede guardar en la alerta información adicional acerca de la alerta en formato clave-valor. Trak.e permite a cada cliente configurar en un json schema¹ la estructura de esta información adicional. Esta especificación permitirá validar y normalizar la información adicional. A diferencia de los legajos, la información adicional de las alertas difiere una de otra debido al tipo de incidente, por eso se debe definir un json schema para cada tipo.

Por ejemplo si una alerta de tipo custom_trx_alert contiene información adicional acerca de la transacción podemos definir:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Trx fraud alert",
  "description": "Información adicional de alerta",
  "type": "object",
  "properties": {
    "transaction_info": {
      "description": "Información de la transacción",
      "type": "object",
      "properties": {
        "transaction_type": {
          "type": "string"
        },
        "ref": {
          "type": "string"
        },
        "timestamp": {
          "type": "integer"
        }
      }
    }
  }
}

Este JSON Schema se carga como parte de la configuración de tipos de incidentes. Luego, las alertas dadas de alta con ese tipo se validan automaticamente en backend para verificar que la información adicional proporcionada se adecúa al JSON Schema definido. Si las mismas no se adecuan al JSON Schema definido, se devuelve un error 400 Bad Request con el detalle "model is not compliant with schema defined.".

El campo $schema indica la versión del borrador en la que se escribe el esquema JSON, por lo tanto es importante definirlo. Trak.e soporta JSON schemas con una versión de borrador igual o superior a Draft 4.

Luego de definir el schema, podemos guardar y acceder a la información en la alerta utilizando el atributo info.transaction_info. Cabe aclarar que ante la ausencia de un schema, igualmente se puede guardar la información adicional en la alerta, pero no se realizará ninguna validación ni tendrá soporte para el ingreso manual.

5.3 Workflows¶

Las alertas poseen un atributo que especifica en que estado se encuentran. Los estados default de trak.e son:

• Abierta (open): La alerta aún no ha sido tratada.
• En progreso (in_progress): La alerta esta siendo tratada.
• Cerrada (closed): La alerta ha sido cerrada

Adicionalmente, se pueden definir todos los estados que la entidad considere necesarios. Cada entidad puede implementar el flujo de estados que mejor se ajuste a sus necesidades.

Se puede definir para cada estado final si el mismo necesita ser autorizado o no.

5.3.1 Autorización de alertas¶

Una vez que la alerta ha llegado a cierto estado considerado "final" - si dicho estado requiere autorización, se puede llevar el estado de autorización a uno de los siguientes:

• pending (autorización pendiente): Es el estado inicial. La alerta no fue evaluada ni autorizada.
• authorized (autorizada): La alerta queda autorizada. Una vez que la alerta fue autorizada, la misma pasa a modo de solo lectura.
• not_required (autorización no requerida): La autorización no es requerida para esta alerta. También se bloquea la edición de alertas.

Solo aquellos usuarios con el permiso incident_supervisorcheck:add pueden cambiar el estado de autorización de una alerta.

5.3.2 Workflow Default¶

Trak.e tiene un workflow de estado de alertas predeterminado que puede ser ajustado a las necesidades de cada entidad.

graph TD
  open --> in_progress
  in_progress --> open

  open --> closed
  closed --> open

  closed --> in_progress
  open --> in_progress

Como se explico en el Workflow de Legajos, cada transicion tiene una fuente (source), un destino destination representando el estado actual y el estado deseado respectivamente. Adicionalmente, se puede tener una condición que debe cumplirse para poder ejecutar la transicion (condition). Los estados disponibles a partir de un estado dado estan dados por las transiciones y las condiciones que son evaluadas en ese momento.

Las condiciones tienen dos argumentos, la alerta actual y el contexto de seguridad del operador actual. La condición debe ser una expresión Python válida.²

Los diccionarios de Python se pueden acceder con la notación dot syntax de Javascript, en caso de que la clave no exista, devuelve None.

La alerta contiene toda la información discutida más arriba.

El contexto de seguridad incluye la propiedad scope, que es una lista de los roles que posee el usuario/aplicación que esta utilizando trak.e. De este modo, se puede definir, por ejemplo, que que solo usuarios con rol "Supervisor de AML" puedan mover alertas desde in_progress a closed.

5.4 Comentarios¶

Cada usuario de Trak.e Web puede agregar a la alerta los comentarios que considere relevantes. Estos comentarios estan en formato HTML, lo que permite tener texto enriquecido en formato. Las opciones de formato disponibles son: negrita, itálicas, subrayado, tachado, diferentes opciones de tamaño de letra. Los comentarios se guardan junto al usuario que lo realizó. Además, también se guarda la fecha y hora del comentario. Un usuario puede editar o borrar comentarios que hizo, pero solo puede ver los comentarios de otras personas.

Además, trak.e ofrece facilidades para guardar comentarios utilizados con frecuencia. El objetivo de dichos comentarios es permitir su utilización para agilizar el análisis y gestión de una alerta o caso. Estos comentarios pueden ser de uso "privado", es decir, solo accesibles para los usuarios que los hayan definido; o bien "publicos", en cuyo caso serán accesibles para todos los usuarios de la plataforma con los permisos asociados.

5.5 Recursos¶

5.6 Permisos asociados¶

5.7 API¶

Para más información técnica sobre el servicio (como por ejemplo, buscar, crear y modificar alertas) se encuentra disponible la documentación de la API.

5.7.1 Caso de uso: Alta de alerta por API¶

Para dar de alta un alerta por API, se debe invocar al servicio POST /incident/case. Se debe enviar un header Authorization: Bearer {token} con un token que sea válido y dentro de sus claims cuente con el permiso incident_case:add. El body de la request se envía en formato JSON. Por ejemplo, la siguiente consulta crea una alerta con titulo y descripción relacionada al legajo 5f8f17b47932b41efd90a8e3.

curl --request POST \
  --url https://api-dev.trake.io/incident/case \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "this is a description ",
    "priority": "high",
    "severity": "high",
    "title": "Titulo de la alerta",
    "dprofile_id": "5f8f17b47932b41efd90a8e3",
    "due_date": 1759995745394,
    "incident_type": "other",
    "info": {
    }
}'

El legajo debe existir previamente para que la request tenga exito.

En caso de respuesta exitosa, se recibe un codigo de estado 201 Created y un body JSON como el siguiente, indicando que la alerta ha sido creada:

{
  "dprofile_is_employee": null,
  "user_id": null,
  "title": "Titulo de la alerta",
  "description": "this is a description ",
  "state": "abierta",
  "severity": "high",
  "priority": "high",
  "due_date": 1759995745394,
  "info": {},
  "closed_at": null,
  "dprofile_id": "5f8f17b47932b41efd90a8e3",
  "dprofile_name": "Leandra Gual-Barón",
  "dprofile_risk": "low",
  "dprofile_tax_payer_id": "14362595630",
  "incident_type": "other",
  "cabinet_id": null,
  "case_hash": "0f73f547-3d03-4e65-8912-e357913f1a83",
  "id": "6835d8208bec087da7436c94",
  "created_at": 1748359200041,
  "modified_at": 1748359200041,
  "created_by": "smart_administrador2",
  "modified_by": "smart_administrador2",
  "version": 1,
  "id_number": null,
  "confirmed": null,
  "tags": [],
  "tasks": null,
  "parent_case": null,
  "related_alerts": [],
  "supervisor_authorization": null
}

5.7.2 Caso de uso: Asignación de usuario a alerta por API¶

Para asignar un usuario a una alerta dada, se debe relacionar el id del usuario al id de la alerta. Por ejemplo, si queremos asignar el usuario con id 6000962c2971e130790dd435 a la alerta con id 6835d8208bec087da7436c94, podemos lograrlo mediante el uso de una operación PATCH:

curl --request PATCH \
  --url https://api-dev.trake.io/incident/case/6835d8208bec087da7436c94 \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '[
    {"op": "add", "path": "/user_id", "value": "6000962c2971e130790dd435" }
]'

En caso de exito, se devuelve un status 204 No Content.

Utilizando un request GET se puede verificar que efectivamente el user_id a sido asignado en la alerta, por ejemplo:

curl --request GET \
  --url https://api-dev.trake.io/incident/case/6835d8208bec087da7436c94 \
  --header 'Authorization: Bearer {token}'

En caso de exito, esta solicitud responde 200 Ok con un body json como el siguiente:

{
  "dprofile_is_employee": null,
  "user_id": "6000962c2971e130790dd435",
  "title": "Titulo de la alerta",
  "description": "this is a description ",
  "state": "abierta",
  "severity": "high",
  "priority": "high",
  "due_date": 1759995745394,
  "info": {},
  "closed_at": null,
  "dprofile_id": "5f8f17b47932b41efd90a8e3",
  "dprofile_name": "Leandra Gual-Barón",
  "dprofile_risk": "low",
  "dprofile_tax_payer_id": "14362595630",
  "incident_type": "other",
  "cabinet_id": null,
  "case_hash": "0f73f547-3d03-4e65-8912-e357913f1a83",
  "id": "6835d8208bec087da7436c94",
  "created_at": 1748359200041,
  "modified_at": 1748359986037,
  "created_by": "smart_administrador2",
  "modified_by": "smart_administrador2",
  "version": 2,
  "id_number": null,
  "confirmed": null,
  "tags": [],
  "tasks": null,
  "parent_case": null,
  "related_alerts": [],
  "supervisor_authorization": null
}

5.7.3 Caso de uso: Cierre de un caso vía API¶

A continuación se expone un ejemplo de como lograr un cierre de caso vía API. En general, el cierre de un caso involucra dos pasos separados que se pueden realizan en cualquier orden: un comentario de cierre, y el cambio de estado del caso.

5.7.3.1 Cambio de estado del caso¶

El cambio de estado se logra a través del endpoint PUT /incident/case/{case_id}/state/{state}. Por ejemplo con la siguiente request se cambia el estado a closed:

curl 'https://api-dev.trake.io/incident/case/6835e8e68bec087da7436c96/state/no_aplica' \
  -X 'PUT' \
  -H 'authorization: Bearer {token}'

curl 'https://api-dev.trake.io/incident/case/683777df8bec087da7436c9e/state/no_aplica' \ -X 'PUT' \ -H 'authorization: Bearer ${token}'

En caso de exito se devuelve un estado 204 "No Content". Se puede verificar utilizando un GET que se actualizo el estado y la fecha de cierre, por ejemplo:

curl 'https://api-dev.trake.io/incident/case/6835e8e68bec087da7436c96' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json;charset=UTF-8'

en caso de exito, esta request devuelve un json como el siguiente:

{
  "dprofile_is_employee": null,
  "user_id": null,
  "title": "27214497412 - HERNANDEZ, GABRIELA",
  "description": "\n27214497412 - HERNANDEZ, GABRIELA\n27214497412 - HERNANDEZ, GABRIELA",
  "state": "no_aplica",
  "severity": "high",
  "priority": "high",
  "due_date": 1748363482571,
  "info": {},
  "closed_at": null,
  "dprofile_id": "6835e8da484bff735e4216ba",
  "dprofile_name": "HERNANDEZ, GABRIELA",
  "dprofile_risk": "low",
  "dprofile_tax_payer_id": "27214497412",
  "incident_type": "case",
  "cabinet_id": null,
  "case_hash": "0116dd3f-41ac-483c-8221-7510233f318b",
  "id": "6835e8e68bec087da7436c96",
  "created_at": 1748363494920,
  "modified_at": 1748363581344,
  "created_by": "smart_administrador2",
  "modified_by": "smart_administrador2",
  "version": 2,
  "id_number": null,
  "confirmed": null,
  "tags": [],
  "tasks": null,
  "parent_case": null,
  "related_alerts": ["6835e8da73af83380c163476", "6835e8da73af83380c163477"],
  "supervisor_authorization": null
}

Se puede verificar que las alertas relacionadas también han cambiado su estado con el mismo endpoint, por ejemplo:

curl 'https://api-dev.trake.io/incident/case/6835e8da73af83380c163477' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json;charset=UTF-8'

Esta consulta, si tiene exito, devuelve un json como el siguiente:

{
  "user_id": null,
  "title": "27214497412 - HERNANDEZ, GABRIELA",
  "description": "",
  "state": "no_aplica",
  "severity": "low",
  "priority": "medium",
  "due_date": 1748363482597,
  "info": {},
  "confirmed": false,
  "tags": [],
  "tasks": null,
  "parent_case": "6835e8e68bec087da7436c96",
  "related_alerts": [],
}

5.7.3.2 Agregar comentario de cierre¶

A continuación se muestra un ejemplo de como agregar un comentario de cierre.

curl --request POST \
  --url https://api-dev.trake.io/incident/case/6835e8e68bec087da7436c96/comments \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '  {
        "comment":"esto es un comentario",
        "closing_comment": true
    }'

Es importante marcar closing_comment como true para que quede reflejado correctamente como comentario de cierre. El comentario queda a nombre del usuario o aplicación identificado por el token. El comentario de cierre se propaga a las alertas relacionadas.

5.8 Diagrama de componentes¶

El servicio de incidentes se encuentra dividido en dos componentes principales:

• Service: expone una API RESTful que puede ser consumida por aplicaciones externas o usuarios a través de Trak.e Web. Es responsable de gestionar operaciones sincrónicas como la creación, consulta y actualización de incidentes, comentarios y tareas.

• Processor: procesa eventos provenientes del resto del ecosistema Trak.e (por ejemplo, nuevos hits en listas, cambios en el scoring de riesgo, etc.). Funciona de forma asíncrona, reaccionando a estos eventos para generar o actualizar incidentes, o publicar eventos derivados.

Esta separación permite desacoplar la lógica reactiva y asincrónica del consumo directo vía API, facilitando escalabilidad y resiliencia.

A continuación se presenta un diagrama de alto nivel de la arquitectura de trak.e con foco en el servicio de incidentes y su interacción con los otros componentes del sistema:

graph TB
  subgraph Infrastructure
    direction LR
    MongoDB[(MongoDB)]
    Kafka[(Kafka)]
  end

  subgraph Incident
    direction LR
    Service[Service]
    Processor[Processor]
  end

  subgraph Other Services
    direction LR
    Blacklists[Blacklists]
    Doc[Doc]
    Dprofile[Dprofile]
    Risk[Risk]
    Transactions[Transactions]
    Middleware[Middleware]
  end

  DocService

  %% Comunicaciones síncronas (REST - líneas continuas)
  Service <--> DocService

  %% Comunicaciones offline (líneas punteadas)
  Blacklists -.-> Processor
  Doc -.-> Processor
  Dprofile -.-> Processor
  Risk -.-> Processor
  Transactions -.-> Processor
  Middleware -.-> Processor

  %% Acceso a base de datos
  Incident <--> Infrastructure
  Processor -.->| publish | Kafka
  Service -.->| publish | Kafka