> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reportar riesgo en una transacción

> Clasifica manualmente una transacción, crea una alerta sin regla y la vincula a una investigación.

## Descripción general

Usá este endpoint cuando un analista confirma que una transacción requiere investigación
bajo una categoría activa como `FRAUD` o `AML`.

La operación:

* marca la transacción como reportada manualmente y establece `flagged=true`;
* crea una alerta sin regla, snapshot de regla ni score de riesgo numérico;
* crea una investigación nueva o vincula la alerta a la investigación activa compatible
  elegida explícitamente por el analista;
* registra eventos de auditoría en la transacción y la investigación.

No cambia el estado de la transacción, no ejecuta reglas ni crea un risk analysis audit.

## Autenticación

Requiere `transactions:edit`.

## Body

<ParamField body="category" type="string" required>
  Código de una categoría de investigación activa, por ejemplo `FRAUD` o `AML`.
</ParamField>

<ParamField body="subjectSide" type="&#x22;origin&#x22; | &#x22;destination&#x22;" required>
  Parte de la transacción que será el sujeto de la investigación. El lado elegido debe
  referenciar una entidad de la misma organización.
</ParamField>

<ParamField body="investigationAction" type="&#x22;create&#x22; | &#x22;consolidate&#x22;" required>
  Indica si se crea una investigación separada o se consolida en una existente.
</ParamField>

<ParamField body="investigationId" type="string">
  Obligatorio solo con `investigationAction="consolidate"`. La investigación debe estar
  activa y corresponder a la organización y al sujeto elegidos. No necesita ser de la
  misma categoría: una investigación acumula varias en `categoriesAffected`. Como la
  alerta es de una transacción, además debe agrupar alertas transaccionales o combinadas:
  las investigaciones limitadas a persona, empresa o dispositivo, y las de alerta única,
  se rechazan con `MANUAL_RISK_INVESTIGATION_INVALID`.
</ParamField>

<ParamField body="isUniqueInvestigation" type="boolean" default="false">
  Solo aplica con `investigationAction="create"`. Si es `true`, la investigación no
  recibirá futuras alertas por consolidación automática.
</ParamField>

<ParamField body="reason" type="string">
  Justificación opcional del analista. Máximo 5.000 caracteres.
</ParamField>

```json theme={null}
{
  "category": "FRAUD",
  "subjectSide": "origin",
  "investigationAction": "create",
  "isUniqueInvestigation": true,
  "reason": "Confirmado por el equipo antifraude luego de revisar el caso con el cliente."
}
```

## Respuesta

Devuelve HTTP `201` al crear el reporte. Repetir la operación devuelve HTTP `200`
con `alreadyReported: true`, sin duplicar la alerta ni la investigación.

```json theme={null}
{
  "success": true,
  "alreadyReported": false,
  "transaction": {
    "id": "0f7231f6-ec63-45b6-b329-d477ba111d2d",
    "status": "SUCCESSFUL",
    "flagged": true,
    "manualRiskCategory": "FRAUD",
    "manualRiskReportedAt": "2026-09-09T18:00:00.000Z",
    "manualRiskAlertId": "b1b85d55-0cfa-4c19-b308-9273152cdf86",
    "manualRiskInvestigationId": "da62d25d-e459-4dbc-b072-02ff89f1cf10"
  },
  "alert": {
    "title": "FRAUD DETECTION - TX-83921",
    "alertType": "FRAUD",
    "triggerRuleId": null,
    "riskScore": null
  },
  "investigation": {
    "investigationType": "FRAUD",
    "riskAnalysisAuditId": null,
    "isUniqueInvestigation": true,
    "reused": false
  }
}
```

La transacción conserva los IDs directos de la alerta y la investigación. Esto evita
reportarla nuevamente y permite abrir el caso vinculado desde el detalle.

El audit de la investigación puede no ser nulo si la alerta se agrega a un caso
existente que ya tenía un análisis de riesgo. La alerta manual continúa sin estar
vinculada a una regla ni a ese audit.

Luego del commit, la operación emite los eventos de automation `investigation_created`
o `investigation_updated`, y `alert_created`. Por lo tanto, las automations activas de
la organización para esos disparadores también procesan el reporte manual.