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

# Atualizar transação

> Atualização parcial de uma transação existente — merge de metadata ou deviceDetails, alterar canal ou motivo — sem substituir o registro completo.

## Visão geral

Use este endpoint para **enriquecer ou corrigir** uma transação após a criação: **metadata**, **deviceDetails**, **channel** ou **reason**. Não altera valor, status, partes ou outros campos centrais (para status use [Alterar status](/pt/use-cases/transaction-monitoring/change-status-api)).

<Note>
  **Merge superficial em `metadata` e `deviceDetails`:** apenas as chaves enviadas são sobrescritas; as demais permanecem. Objetos aninhados (ex.: `metadata.tags`) são substituídos por completo se você enviar essa chave. Para limpar `channel`, envie `"channel": null`.
</Note>

## Endpoints

| Método              | Endpoint                                    | Quando                          |
| ------------------- | ------------------------------------------- | ------------------------------- |
| **Por ID**          | `PATCH /transactions/{id}`                  | Você tem o UUID interno da gu1  |
| **Por external ID** | `PATCH /transactions/external/{externalId}` | Só tem o `externalId` do create |

Mesmo body e mesma resposta nos dois.

```
PATCH https://api.gu1.ai/transactions/{id}
PATCH https://api.gu1.ai/transactions/external/{externalId}
```

## Autenticação

Requer `transactions:edit`:

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

## Parâmetros de consulta

<ParamField query="executeRules" type="boolean" default="false">
  Com `true`, reexecuta regras KYT com trigger `transaction_updated` após o patch. Padrão: `false`.
</ParamField>

## Body

Pelo menos **um** campo é obrigatório.

<ParamField body="metadata" type="object">
  Merge superficial sobre o `metadata` existente. Chaves omitidas não são removidas.
</ParamField>

<ParamField body="deviceDetails" type="object">
  Merge superficial sobre `deviceDetails` existente (coluna `device_details`). Para incluir ou corrigir contexto do dispositivo após o create: `ipAddress`, `deviceId`, `osName`, `manufacturer`, `model`, flags (`isVpn`, `isEmulator`, …). Mesmo esquema de [Criar transação](/pt/api-reference/transactions/create). Regras usam caminhos como `deviceDetails.ipAddress`.
</ParamField>

<ParamField body="channel" type="string | null">
  Canal da transação (máx. 50 caracteres). `null` para limpar.
</ParamField>

<ParamField body="reason" type="string">
  Motivo de resultado/recusa. Ver [Enum reason](/pt/api-reference/transactions/reason-enum).
</ParamField>

### Exemplo

```json theme={null}
{
  "metadata": {
    "clientReference": "INV-2026-0042",
    "tags": { "segment": "retail" }
  },
  "deviceDetails": {
    "ipAddress": "203.0.113.10",
    "deviceId": "dev-abc-123",
    "osName": "iOS",
    "osVersion": "17.0",
    "manufacturer": "Apple",
    "model": "iPhone"
  },
  "channel": "mobile",
  "reason": "FRAUD_SUSPECTED"
}
```

## Resposta (200 OK)

Retorna `success`, o subconjunto atualizado em `transaction` (`id`, `externalId`, `channel`, `reason`, `metadata`, `deviceDetails`, `updatedAt`) e opcionalmente `rulesExecutionSummary` se `executeRules=true`.

## Erros

| Status | Código             | Quando                            |
| ------ | ------------------ | --------------------------------- |
| 400    | `VALIDATION_ERROR` | Body inválido                     |
| 400    | `NO_CHANGES`       | Valores já iguais ao armazenado   |
| 404    | `NOT_FOUND`        | Transação inexistente na org      |
| 403    | —                  | Sem permissão `transactions:edit` |

## Efeitos colaterais

* **Auditoria:** evento `transaction_updated` na linha do tempo (`changes` pode incluir `metadata`, `deviceDetails`, `channel`, `reason`).
* **Webhook:** `transaction.updated` (inclui mapa `changes` e `deviceDetails` atual quando aplicável).
* **Regras:** somente com `executeRules=true`.

## Exemplo

```bash theme={null}
curl -X PATCH "https://api.gu1.ai/transactions/external/tx_12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"note":"Corrigido após callback"},"channel":"api"}'
```

## Relacionado

<CardGroup cols={2}>
  <Card title="Obter transação" icon="receipt" href="/pt/api-reference/transactions/get">
    Ler a transação completa
  </Card>

  <Card title="Alterar status" icon="rotate" href="/pt/use-cases/transaction-monitoring/change-status-api">
    Atualizar status
  </Card>

  <Card title="Criar transação" icon="plus" href="/pt/api-reference/transactions/create">
    Metadata na criação
  </Card>

  <Card title="Enum reason" icon="list" href="/pt/api-reference/transactions/reason-enum">
    Valores de `reason`
  </Card>
</CardGroup>