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

# Actualizar transacción

> Actualización parcial de una transacción — merge de metadata o deviceDetails, canal o motivo — sin reemplazar el registro completo.

## Resumen

Usá este endpoint para **enriquecer o corregir** una transacción después del alta: **metadata**, **deviceDetails**, **channel** o **reason**. No modifica monto, estado, contrapartes u otros campos núcleo (para estado usá [Cambiar estado](/es/use-cases/transaction-monitoring/change-status-api)).

<Note>
  **Merge superficial en `metadata` y `deviceDetails`:** solo se pisan las claves que enviés; el resto se conserva. Los objetos anidados (p. ej. `metadata.tags`) se reemplazan enteros si mandás esa clave. Para limpiar `channel`, mandá `"channel": null`.
</Note>

## Endpoints

| Método              | Endpoint                                    | Cuándo                                |
| ------------------- | ------------------------------------------- | ------------------------------------- |
| **Por ID**          | `PATCH /transactions/{id}`                  | Tenés el UUID interno de gu1          |
| **Por external ID** | `PATCH /transactions/external/{externalId}` | Solo tenés tu `externalId` del create |

Mismo body y misma respuesta en ambos.

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

## Autenticación

Requiere `transactions:edit`:

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

## Parámetros de consulta

<ParamField query="executeRules" type="boolean" default="false">
  Con `true`, re-ejecuta reglas KYT con trigger `transaction_updated` después del patch. Default: `false`.
</ParamField>

## Body

Al menos **un** campo es obligatorio.

<ParamField body="metadata" type="object">
  Merge superficial sobre el `metadata` existente. Las claves omitidas no se borran.
</ParamField>

<ParamField body="deviceDetails" type="object">
  Merge superficial sobre `deviceDetails` existente (columna `device_details`). Para agregar o corregir contexto de dispositivo post-alta: `ipAddress`, `deviceId`, `osName`, `manufacturer`, `model`, flags (`isVpn`, `isEmulator`, …). Mismo esquema que [Crear transacción](/es/api-reference/transactions/create). Las reglas usan rutas como `deviceDetails.ipAddress`.
</ParamField>

<ParamField body="channel" type="string | null">
  Canal de la transacción (máx. 50 caracteres). `null` para limpiar.
</ParamField>

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

### Ejemplo

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

## Respuesta (200 OK)

Devuelve `success`, el subconjunto actualizado en `transaction` (`id`, `externalId`, `channel`, `reason`, `metadata`, `deviceDetails`, `updatedAt`) y opcionalmente `rulesExecutionSummary` si `executeRules=true`.

## Errores

| Estado | Código             | Cuándo                                   |
| ------ | ------------------ | ---------------------------------------- |
| 400    | `VALIDATION_ERROR` | Body inválido                            |
| 400    | `NO_CHANGES`       | Los valores ya coinciden con lo guardado |
| 404    | `NOT_FOUND`        | Transacción inexistente en tu org        |
| 403    | —                  | Sin permiso `transactions:edit`          |

## Efectos secundarios

* **Auditoría:** evento `transaction_updated` en la línea de tiempo (`changes` puede incluir `metadata`, `deviceDetails`, `channel`, `reason`).
* **Webhook:** `transaction.updated` (incluye mapa `changes` y `deviceDetails` actual cuando aplica).
* **Reglas:** solo con `executeRules=true`.

## Ejemplo

```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":"Corregido post callback"},"channel":"api"}'
```

## Relacionado

<CardGroup cols={2}>
  <Card title="Obtener transacción" icon="receipt" href="/es/api-reference/transactions/get">
    Leer la transacción completa
  </Card>

  <Card title="Cambiar estado" icon="rotate" href="/es/use-cases/transaction-monitoring/change-status-api">
    Actualizar status
  </Card>

  <Card title="Crear transacción" icon="plus" href="/es/api-reference/transactions/create">
    Metadata en el alta
  </Card>

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