> ## 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 risco em uma transação

> Classifica manualmente uma transação, cria um alerta sem regra e o vincula a uma investigação.

## Visão geral

Use este endpoint quando um analista confirmar que uma transação requer investigação
em uma categoria ativa, como `FRAUD` ou `AML`.

A operação:

* marca a transação como reportada manualmente e define `flagged=true`;
* cria um alerta sem regra, snapshot de regra ou score numérico de risco;
* cria uma nova investigação ou vincula o alerta à investigação ativa compatível
  escolhida explicitamente pelo analista;
* registra eventos de auditoria na transação e na investigação.

Ela não altera o status da transação, não executa regras e não cria um risk analysis audit.

## Autenticação

Requer `transactions:edit`.

## Body

<ParamField body="category" type="string" required>
  Código de uma categoria de investigação ativa, por exemplo `FRAUD` ou `AML`.
</ParamField>

<ParamField body="subjectSide" type="&#x22;origin&#x22; | &#x22;destination&#x22;" required>
  Parte da transação que será o sujeito da investigação. O lado escolhido deve
  referenciar uma entidade da mesma organização.
</ParamField>

<ParamField body="investigationAction" type="&#x22;create&#x22; | &#x22;consolidate&#x22;" required>
  Define se uma investigação separada será criada ou se o alerta será consolidado em uma existente.
</ParamField>

<ParamField body="investigationId" type="string">
  Obrigatório somente com `investigationAction="consolidate"`. A investigação deve estar
  ativa e corresponder à organização e ao sujeito escolhidos. Não precisa ser da mesma
  categoria: uma investigação acumula várias em `categoriesAffected`. Como o alerta é de
  uma transação, a investigação também precisa agrupar alertas transacionais ou
  combinados: investigações limitadas a pessoa, empresa ou dispositivo, e as de alerta
  único, são rejeitadas com `MANUAL_RISK_INVESTIGATION_INVALID`.
</ParamField>

<ParamField body="isUniqueInvestigation" type="boolean" default="false">
  Aplica-se somente com `investigationAction="create"`. Quando `true`, alertas futuros
  não serão consolidados automaticamente nesta investigação.
</ParamField>

<ParamField body="reason" type="string">
  Justificativa opcional do analista. Máximo de 5.000 caracteres.
</ParamField>

```json theme={null}
{
  "category": "FRAUD",
  "subjectSide": "origin",
  "investigationAction": "create",
  "isUniqueInvestigation": true,
  "reason": "Confirmado pela equipe antifraude após a revisão do caso com o cliente."
}
```

## Resposta

Retorna HTTP `201` ao criar o reporte. Repetir a operação retorna HTTP `200`
com `alreadyReported: true`, sem duplicar o alerta ou a investigação.

```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
  }
}
```

A transação mantém os IDs diretos do alerta e da investigação. Isso impede um
segundo reporte e permite abrir o caso vinculado pelo detalhe da transação.

O audit da investigação pode não ser nulo quando o alerta é adicionado a um caso
existente que já tinha uma análise de risco. O alerta manual continua sem vínculo
com uma regra ou com esse audit.

Após o commit, a operação emite o evento de automation `investigation_created` ou
`investigation_updated`, além de `alert_created`. Assim, as automations ativas da
organização com esses disparadores também processam os reportes manuais.