> ## 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.

# Obter transação

> Busca uma transação por ID interno ou por externalId — na API de monitoramento de transações gu1 para fraude e AML, com exemplos para get.

## Visão geral

Retorna uma transação da sua organização. A resposta usa objetos aninhados **`origin`** e **`destination`** (com dados de entidade resolvidos quando existem). Isso difere de [Criar transação](/pt/api-reference/transactions/create), em que o corpo usa `originDetails` / `destinationDetails` mais planos.

Na leitura o motor de regras **não** é reexecutado. Por padrão a resposta **não** inclui `rulesExecutionSummary`. Envie **`includeRulesSummary=full`** para anexar o último resumo persistido ao objeto **`persisted`** (mesmo formato de [Resumo de execução de regras](/pt/api-reference/rules-execution-summary)).

## Endpoints

| Método              | Endpoint                                  | Quando usar                                 |
| ------------------- | ----------------------------------------- | ------------------------------------------- |
| **Por ID**          | `GET /transactions/{id}`                  | Você tem o UUID da transação no gu1         |
| **Por external ID** | `GET /transactions/external/{externalId}` | Você só tem o `externalId` usado na criação |

Ambos retornam o mesmo formato: `{ "transaction": { ... }, "persisted": { ... }, "baseCurrency": "..." }`.

## Parâmetros de consulta

<ParamField query="includeRulesSummary" type="string">
  Opcional. Se omitido, o comportamento permanece o mesmo (sem resumo de regras na leitura).

  * **`full`** — Carrega a linha **mais recente** de `risk_analysis_audits` desta transação e adiciona **`persisted.rulesExecutionSummary`** (`rulesHit`, `rulesNoHit`, `actionsExecuted`, scores, etc.). **Não** reexecuta regras. Indicado para detalhe de uma transação / debugging; omita em polling em volume.
</ParamField>

### Por ID

```
GET http://api.gu1.ai/transactions/{id}
```

<ParamField path="id" type="string" required>
  UUID da transação no gu1 (o mesmo que `transaction.id` ao criar).
</ParamField>

### Por external ID

```
GET http://api.gu1.ai/transactions/external/{externalId}
```

<ParamField path="externalId" type="string" required>
  O `externalId` enviado na criação da transação.
</ParamField>

## Autenticação

Exige API key válida e permissão de leitura de transações (`transactions:read`):

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

A transação deve pertencer à organização da chave; caso contrário a API responde **404**.

## Resposta (200 OK)

<ResponseField name="transaction" type="object">
  Registro completo da transação.

  * **id** (string) — UUID no gu1
  * **externalId** (string) — seu identificador externo
  * **type**, **status** — enums (mesma semântica que em criar)
  * **amount** (number), **currency** (string)
  * **amountInUsd** (number | null)
  * **currenciesExchange** (array) — entradas `{ currency, exchangeRate, value }`
  * **paymentMethod** (string | null)
  * **origin** (object) — `entityId`, `externalId`, `name`, `country`, `type` (`person` | `company` | null), `taxId`, `riskScore`, `details` (objeto; inclui o que você persistiu, ex. payment details)
  * **destination** (object) — mesma estrutura que **origin**
  * **riskScore** (number | null)
  * **lastRiskEvaluationAt** (string | null) — ISO da última auditoria de análise de risco (**presente no GET por UUID**; omitido ao buscar por external ID)
  * **riskFactors** (array)
  * **activeMatchesCount**, **shadowMatchesCount** (number, opcional)
  * **hitRuleExternalIds** (string\[], opcional)
  * **flagged** (boolean)
  * **locationDetails**, **deviceDetails** (object)
  * **channel** (string | null), **timeZone** (string | null) — fuso IANA se enviado no create
  * **description**, **category**, **metadata** (object)
  * **transactedAt**, **createdAt**, **updatedAt** (ISO)
  * **exchangeRate**, **rateSource**, **rateTimestamp**, **convertedAt** — metadados de conversão quando aplicável
</ResponseField>

<ResponseField name="persisted" type="object">
  Snapshot plano em camelCase da linha em `transactions` (mesmos nomes que create / entrada do motor): valores, contrapartes, `metadata`, `riskFactors`, etc.

  Com **`includeRulesSummary=full`**, pode incluir também:

  * **rulesExecutionSummary** (object) — última execução persistida de regras desta transação (não é reavaliação ao vivo). Omitido se não houver auditoria ou se o query param não for enviado.
</ResponseField>

<ResponseField name="baseCurrency" type="string">
  Moeda base da organização (código ISO, ex. `USD`).
</ResponseField>

### Exemplo (por ID, com resumo de regras)

```bash theme={null}
curl -s 'http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000?includeRulesSummary=full' \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "transaction": { "...": "..." },
  "persisted": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "amount": 150.5,
    "currency": "USD",
    "riskFactors": {},
    "metadata": {},
    "rulesExecutionSummary": {
      "rulesHit": [],
      "rulesNoHit": [],
      "totalScore": 0,
      "actionsExecuted": {}
    }
  },
  "baseCurrency": "USD"
}
```

### Exemplo (por ID, padrão)

```bash theme={null}
curl -s http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "status": "CREATED",
    "amount": 150.5,
    "currency": "USD",
    "amountInUsd": 150.5,
    "currenciesExchange": [],
    "paymentMethod": "CARD",
    "origin": {
      "entityId": "…",
      "externalId": "customer_001",
      "name": "Jane Doe",
      "country": "US",
      "type": "person",
      "taxId": null,
      "riskScore": 12.5,
      "details": {}
    },
    "destination": {
      "entityId": "…",
      "externalId": "merchant_456",
      "name": "Acme Store",
      "country": "US",
      "type": "company",
      "taxId": null,
      "riskScore": 8,
      "details": {}
    },
    "riskScore": 15,
    "lastRiskEvaluationAt": "2025-01-15T10:00:00.000Z",
    "riskFactors": [],
    "flagged": false,
    "locationDetails": {},
    "deviceDetails": {},
    "channel": "web_browser",
    "description": "Compra online",
    "category": "retail",
    "metadata": {},
    "transactedAt": "2025-01-15T09:55:00.000Z",
    "createdAt": "2025-01-15T09:55:01.000Z",
    "updatedAt": "2025-01-15T09:55:01.000Z",
    "exchangeRate": null,
    "rateSource": null,
    "rateTimestamp": null,
    "convertedAt": null
  },
  "baseCurrency": "USD"
}
```

## Erros

### 400 — Query inválido

```json theme={null}
{
  "error": "Invalid query parameters",
  "details": []
}
```

Quando `includeRulesSummary` não é `full`.

### 404 — Não encontrada

```json theme={null}
{
  "error": "Transaction not found"
}
```

### 500 — Erro no servidor

```json theme={null}
{
  "error": "Failed to fetch transaction",
  "details": "…"
}
```

## Veja também

* [Criar transação](/pt/api-reference/transactions/create)
* [Resumo de execução de regras](/pt/api-reference/rules-execution-summary)
* [Criar transações em lote](/pt/api-reference/transactions/create-batch)
* [Alterar status da transação](/pt/use-cases/transaction-monitoring/change-status-api)