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

# Endpoint Crear Transacción para Monitoreo

> Referencia del endpoint POST /transactions para monitoreo: esquema de request, conversión de moneda, métodos de pago y ejemplos prácticos para fraude y AML.

## Referencia canónica del endpoint

La **referencia oficial** del endpoint `POST /transactions` (estructura de respuesta, errores, campos) está en:

**[Crear transacción](/es/api-reference/transactions/create)** (API Reference → Transacciones)

En esa página encontrarás la respuesta actual: `transaction` es un **objeto** (la transacción creada) y, cuando se ejecutan reglas, **`rulesExecutionSummary`** va en la raíz de la respuesta (ver [Resumen de Ejecución de Reglas](/es/api-reference/rules-execution-summary)).

Esta página añade **contexto de uso** para monitoreo: conversión de moneda, ejemplos por método de pago (PIX, tarjeta, multi-moneda) y campos detallados.

***

## Endpoint: Crear Transacción

```
POST http://api.gu1.ai/transactions
```

Crea una nueva transacción. Los montos se convierten a USD cuando la moneda no es USD. Con `executeRules: true` (por defecto), se ejecuta el motor de reglas y la respuesta incluye `rulesExecutionSummary` en la raíz cuando se ejecutan las reglas.

## Autenticación

Todas las solicitudes deben incluir una clave API en el encabezado `Authorization`:

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

## Encabezados Requeridos

```bash theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## Cuerpo de la Solicitud

<ParamField body="externalId" type="string" required>
  Tu identificador único para esta transacción en tu sistema

  **Tipo**: `string` (longitud mínima: 1)
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de transacción. Opciones:

  * `PAYMENT` - Compra o pago a comerciante
  * `TRANSFER` - Transferencia entre cuentas/usuarios
  * `WITHDRAWAL` - Retiro de efectivo o débito de cuenta
  * `DEPOSIT` - Depósito o crédito de cuenta
  * `REFUND` - Reembolso de una transacción anterior
  * `CHARGEBACK` - Disputa de contracargo
  * `REVERSAL` - Reversión de transacción
  * `FEE` - Cargo de comisión o tarifa
  * `ADJUSTMENT` - Ajuste de saldo
  * `OTHER` - Otro tipo de transacción

  **Tipo**: `enum` - `'PAYMENT' | 'TRANSFER' | 'WITHDRAWAL' | 'DEPOSIT' | 'REFUND' | 'CHARGEBACK' | 'REVERSAL' | 'FEE' | 'ADJUSTMENT' | 'OTHER'`
</ParamField>

<ParamField body="status" type="string" default="CREATED">
  Estado de la transacción. Sigue un modelo de máquina de estados con estados abiertos y cerrados.

  **Estados Abiertos** (pueden transicionar a otros estados):

  * `CREATED` - Transacción creada (por defecto)
  * `PROCESSING` - Transacción en proceso
  * `SUSPENDED` - Transacción temporalmente suspendida

  **Estados Cerrados** (finales, no pueden volver a estados abiertos):

  * `SENT` - Transacción enviada/transmitida
  * `EXPIRED` - Transacción expirada
  * `DECLINED` - Transacción rechazada/declinada
  * `REFUNDED` - Transacción reembolsada/reversada
  * `SUCCESSFUL` - Transacción completada exitosamente

  **Tipo**: `enum` - `'CREATED' | 'PROCESSING' | 'SUSPENDED' | 'SENT' | 'EXPIRED' | 'DECLINED' | 'REFUNDED' | 'SUCCESSFUL'` (por defecto: 'CREATED')

  **Importante**: Una vez que una transacción alcanza un estado cerrado, no puede volver a un estado abierto. Esto garantiza la integridad de la transacción y un rastro de auditoría apropiado.
</ParamField>

<ParamField body="amount" type="number" required>
  Monto de la transacción (debe ser positivo)

  **Tipo**: `number` (> 0)
</ParamField>

<ParamField body="currency" type="string" required>
  Código ISO 4217 de moneda (ej: "USD", "BRL", "EUR")

  **Tipo**: `string` (longitud: 3)
</ParamField>

<ParamField body="paymentMethod" type="string">
  Método de pago utilizado para la transacción

  **Tipo**: `string` (enum, opcional)

  **Valores Posibles**:

  * `CARD` - Pago con tarjeta de crédito o débito
  * `ACH` - Automated Clearing House (transferencia bancaria US)
  * `PIX` - Sistema de pagos instantáneos de Brasil
  * `TED` - Transferencia bancaria brasileña (Transferência Eletrônica Disponível)
  * `BOLETO` - Boleto de pago brasileño
  * `WALLET` - Billetera digital (PayPal, Venmo, etc.)
  * `SWIFT` - Transferencia internacional SWIFT
  * `IBAN` - Transferencia bancaria basada en IBAN
  * `CBU` - Cuenta bancaria argentina (Clave Bancaria Uniforme)
  * `CVU` - Cuenta virtual argentina (Clave Virtual Uniforme)
  * `DEBIN` - Sistema de débito instantáneo argentino
  * `GENERIC_BANK_ACCOUNT` - Transferencia de cuenta bancaria genérica
  * `MPESA` - M-Pesa mobile money (Kenia)
  * `UPI` - Unified Payments Interface (India)
  * `CHECK` - Pago con cheque
  * `ECHECK` - Cheque electrónico
  * `QR_CODE` - Pago con código QR
  * `ONLINE_PAYMENT` - Pago online genérico
  * `WITHDRAWAL_ORDER` - Orden de retiro

  **Ejemplo**: `"PIX"` o `"CARD"`
</ParamField>

<ParamField body="originEntityId" type="string">
  UUID de la entidad origen (remitente) en el sistema gu1

  **Tipo**: `string` (uuid, opcional)
</ParamField>

<ParamField body="originExternalId" type="string">
  Su ID externo para la entidad origen

  **Tipo**: `string` (opcional)
</ParamField>

<ParamField body="originTaxId" type="string">
  CUIT o documento del **origen** en el **cuerpo raíz**. **Tercer** criterio de vinculación (tras `originEntityId` y `originExternalId`); match normalizado con `entity.taxId`. Si hay coincidencia, se rellenan enlace, nombre y país. Máx. 50 caracteres. **Tipo**: `string` (opcional)
</ParamField>

<ParamField body="originName" type="string">
  Nombre de la entidad origen (remitente)

  **Tipo**: `string` (longitud máxima: 500, opcional)
</ParamField>

<ParamField body="originCountry" type="string">
  Código de país ISO 3166-1 alpha-2 de la entidad origen

  **Tipo**: `string` (longitud: 2, opcional)
</ParamField>

<ParamField body="originDetails" type="object">
  Información contextual sobre el **origen** de la transacción (dispositivo, geolocalización, cuenta, flags de seguridad). Estos campos coinciden con el schema de la API; también puedes enviar campos custom adicionales (ej. `paymentDetails` anidado u otras claves) y se almacenarán.

  **Tipo**: `object` (opcional, estructura validada; claves extra permitidas)

  **Diferencia Clave**:

  * `originCountry` (campo directo) = País de la entidad
  * `originDetails.country` = País del dispositivo/IP al momento de la transacción (puede diferir si está viajando)

  **Campos Soportados**:

  **Dispositivo/Técnico**:

  * `deviceId` (string) - Identificador del dispositivo
  * `deviceFingerprint` (string) - Hash de huella digital del dispositivo
  * `deviceType` (enum) - `mobile` | `desktop` | `tablet` | `pos` | `atm`
  * `userAgent` (string) - User agent del navegador
  * `ipAddress` (string) - Dirección IP (formato validado)

  **Geolocalización**:

  * `country` (string) - Código ISO de 2 letras
  * `city` (string) - Nombre de la ciudad
  * `region` (string) - Estado/provincia
  * `latitude` (number) - Latitud (-90 a 90)
  * `longitude` (number) - Longitud (-180 a 180)
  * `timezone` (string) - Identificador de zona horaria

  **Detalles de Pago** (objeto anidado):

  * `paymentDetails` (object) - Información específica de pago para el origen. Puede enviar cualquier campo relacionado con el pago:
    * **Detalles Bancarios/Cuenta**:
      * `accountNumber` (string) - Número de cuenta
      * `accountType` (enum) - `checking` | `savings` | `business` | `personal`
      * `bankCode` (string) - Código del banco
      * `bankName` (string) - Nombre del banco
      * `routingNumber` (string) - Routing number (US)
      * `swiftCode` (string) - Código SWIFT/BIC
      * `iban` (string) - IBAN (International Bank Account Number)
    * **Detalles PIX** (Brasil):
      * `pixKey` (string) - Clave PIX
      * `pixType` (enum) - Tipo de clave PIX: `email` | `phone` | `cpf` | `cnpj` | `random`
    * **Detalles de Tarjeta**:
      * `cardLast4` (string) - Últimos 4 dígitos de la tarjeta
      * `cardBrand` (string) - Marca de tarjeta (Visa, Mastercard, Amex, etc.)
      * `cardholderName` (string) - Nombre en la tarjeta
      * `cardBin` (string) - Primeros 6 dígitos de la tarjeta (BIN)
      * `cardType` (enum) - `credit` | `debit` | `prepaid`
      * `cardCountry` (string) - País emisor de la tarjeta (ISO 2 letras)
      * `cardExpiry` (string) - Fecha de vencimiento (MM/YY)
      * `cardFingerprint` (string) - Huella digital única de la tarjeta para seguimiento
    * **Detalles Crypto**:
      * `walletAddress` (string) - Dirección de wallet de criptomoneda
      * `walletType` (string) - Tipo de wallet (ej: "metamask", "coinbase")
      * `blockchain` (string) - Red blockchain (ej: "ethereum", "bitcoin")
      * `tokenSymbol` (string) - Símbolo del token (ej: "ETH", "BTC", "USDT")
    * **Wallet/Pago Digital**:
      * `walletId` (string) - Identificador de wallet digital
      * `walletProvider` (string) - Proveedor de wallet (ej: "paypal", "venmo", "cashapp")
      * `walletEmail` (string) - Email asociado con el wallet
    * **Y cualquier otro campo relacionado con el pago que necesite**

  **Referencia:** Para estructuras sugeridas por método de pago (tarjeta, PIX, CBU/CVU, SPEI, PSE, DEBIN, cripto, wallet, efectivo, cheque, etc.) ver [Payment Details Schema](/es/api-reference/transactions/payment-details-schema). Nada se exige; se permiten campos custom.

  **Banderas de Seguridad**:

  * `isVpn` (boolean) - VPN detectado
  * `isTor` (boolean) - Red Tor detectada
  * `isProxy` (boolean) - Proxy detectado
  * `governmentAccount` (boolean) - Bandera de cuenta gubernamental

  **Ejemplo**:

  ```json theme={null}
  {
    "deviceType": "mobile",
    "ipAddress": "189.123.45.67",
    "country": "BR",
    "city": "São Paulo",
    "isVpn": false,
    "paymentDetails": {
      "accountNumber": "12345",
      "accountType": "personal",
      "bankName": "Banco do Brasil",
      "pixKey": "user@email.com",
      "pixType": "email"
    }
  }
  ```

  Se permiten campos personalizados - el sistema validará los campos conocidos y preservará los personalizados.
</ParamField>

<ParamField body="destinationEntityId" type="string">
  UUID de la entidad destino (receptor) en el sistema gu1

  **Tipo**: `string` (uuid, opcional)
</ParamField>

<ParamField body="destinationExternalId" type="string">
  Su ID externo para la entidad destino

  **Tipo**: `string` (opcional)
</ParamField>

<ParamField body="destinationTaxId" type="string">
  Documento / tax del **destino** en la **raíz**; tercer criterio, misma lógica que `originTaxId`. **Tipo**: `string` (opcional)
</ParamField>

<ParamField body="destinationName" type="string">
  Nombre de la entidad destino (receptor)

  **Tipo**: `string` (longitud máxima: 500, opcional)
</ParamField>

<ParamField body="destinationCountry" type="string">
  Código de país ISO 3166-1 alpha-2 de la entidad destino

  **Tipo**: `string` (longitud: 2, opcional)
</ParamField>

<ParamField body="destinationDetails" type="object">
  Información contextual sobre el **destino** de la transacción (comerciante, dispositivo, geolocalización, cuenta, flags de riesgo). Estos campos coinciden con el schema de la API; también puedes enviar campos custom adicionales (ej. `paymentDetails` anidado u otras claves) y se almacenarán.

  **Tipo**: `object` (opcional, estructura validada; claves extra permitidas)

  **Campos Soportados**:

  **Información de Comerciante**:

  * `mcc` (string) - Merchant Category Code (4 dígitos, ISO 18245)
  * `mccDescription` (string) - Descripción del MCC (ej: "Restaurants")
  * `merchantId` (string) - Identificador del comerciante
  * `merchantName` (string) - Nombre del comerciante
  * `merchantType` (string) - Tipo/categoría del comerciante

  **Dispositivo/Técnico**:

  * `deviceId` (string) - Identificador del dispositivo
  * `deviceType` (enum) - `pos` | `online` | `mobile` | `atm`
  * `ipAddress` (string) - Dirección IP (formato validado)

  **Geolocalización**:

  * `country` (string) - Código ISO de 2 letras
  * `city` (string) - Nombre de la ciudad
  * `region` (string) - Estado/provincia

  **Detalles de Pago** (objeto anidado):

  * `paymentDetails` (object) - Información específica de pago para el destino. Puede enviar cualquier campo relacionado con el pago:
    * **Detalles Bancarios/Cuenta**:
      * `accountNumber` (string) - Número de cuenta destino
      * `accountType` (enum) - `checking` | `savings` | `business` | `merchant`
      * `bankCode` (string) - Código del banco
      * `bankName` (string) - Nombre del banco
      * `routingNumber` (string) - Routing number (US)
      * `swiftCode` (string) - Código SWIFT/BIC
      * `iban` (string) - IBAN (International Bank Account Number)
    * **Detalles PIX** (Brasil):
      * `pixKey` (string) - Clave PIX
      * `pixType` (enum) - Tipo de clave PIX: `email` | `phone` | `cpf` | `cnpj` | `random`
    * **Detalles de Tarjeta**:
      * `cardLast4` (string) - Últimos 4 dígitos de la tarjeta
      * `cardBrand` (string) - Marca de tarjeta (Visa, Mastercard, Amex, etc.)
      * `cardholderName` (string) - Nombre en la tarjeta
      * `cardBin` (string) - Primeros 6 dígitos de la tarjeta (BIN)
      * `cardType` (enum) - `credit` | `debit` | `prepaid`
      * `cardCountry` (string) - País emisor de la tarjeta (ISO 2 letras)
      * `cardExpiry` (string) - Fecha de vencimiento (MM/YY)
      * `cardFingerprint` (string) - Huella digital única de la tarjeta para seguimiento
    * **Detalles Crypto**:
      * `walletAddress` (string) - Dirección de wallet de criptomoneda
      * `walletType` (string) - Tipo de wallet (ej: "metamask", "coinbase")
      * `blockchain` (string) - Red blockchain (ej: "ethereum", "bitcoin")
      * `tokenSymbol` (string) - Símbolo del token (ej: "ETH", "BTC", "USDT")
    * **Wallet/Pago Digital**:
      * `walletId` (string) - Identificador de wallet digital
      * `walletProvider` (string) - Proveedor de wallet (ej: "paypal", "venmo", "cashapp")
      * `walletEmail` (string) - Email asociado con el wallet
    * **Y cualquier otro campo relacionado con el pago que necesite**

  **Referencia:** Para estructuras sugeridas por método de pago ver [Payment Details Schema](/es/api-reference/transactions/payment-details-schema). Nada se exige; se permiten campos custom.

  **Banderas de Riesgo**:

  * `cryptoExchange` (boolean) - Es exchange de criptomonedas
  * `highRisk` (boolean) - Bandera de comerciante de alto riesgo
  * `privateSector` (boolean) - Bandera de sector privado

  **Ejemplo**:

  ```json theme={null}
  {
    "mcc": "5812",
    "mccDescription": "Restaurants",
    "merchantName": "Restaurant ABC",
    "country": "US",
    "highRisk": false,
    "paymentDetails": {
      "accountNumber": "98765",
      "accountType": "merchant",
      "bankName": "Bradesco"
    }
  }
  ```

  Se permiten campos personalizados - el sistema validará los campos conocidos y preservará los personalizados.
</ParamField>

<ParamField body="channel" type="string">
  El canal a través del cual se inició la transacción (máximo 50 caracteres).

  **Tipo**: `string` (longitud máxima: 50, opcional)

  **Ejemplos Comunes**:

  * `mobile_app` - Aplicación móvil
  * `web_browser` - Navegador web
  * `pos_terminal` - Terminal punto de venta
  * `api` - Integración API directa
  * `atm` - Cajero automático
  * `phone_banking` - Banca telefónica
  * `branch` - Sucursal física
  * `call_center` - Centro de llamadas
  * `partner_api` - Integración con partner

  **Caso de Uso**: Ayuda a segmentar transacciones por canal de origen para análisis de riesgo, reportes e inteligencia de negocio.

  **Ejemplo**:

  ```json theme={null}
  {
    "channel": "mobile_app"
  }
  ```
</ParamField>

<ParamField body="reason" type="string">
  Razón opcional del resultado de la transacción (ej. rechazo, fallo, límite excedido). El cliente puede enviar cualquier valor del enum `transaction_reason_type`. Si se omite, el sistema usa `WITHOUT_REASON`. No es obligatorio — las integraciones actuales siguen siendo válidas.

  **Tipo**: `string` (enum, opcional, valor por defecto: `WITHOUT_REASON`)

  **Valores comunes** (el enum completo tiene 60+ valores):

  * `WITHOUT_REASON` - Sin razón específica (por defecto si se omite)
  * `INSUFFICIENT_FUNDS` - Fondos insuficientes
  * `LIMIT_EXCEEDED`, `DAILY_LIMIT_EXCEEDED`, `MONTHLY_LIMIT_EXCEEDED`, `TRANSACTION_LIMIT_EXCEEDED`
  * `ACCOUNT_BLOCKED`, `ACCOUNT_FROZEN`, `ACCOUNT_CLOSED`
  * `CARD_EXPIRED`, `CARD_BLOCKED`, `CARD_LOST_OR_STOLEN`, `INVALID_CARD`, `INVALID_ACCOUNT`
  * `FRAUD_SUSPECTED`, `COMPLIANCE_BLOCK`, `SANCTIONS_MATCH`, `AML_ALERT`, `RISK_SCORE_THRESHOLD`
  * `MERCHANT_BLOCKED`, `COUNTRY_RESTRICTION`, `CURRENCY_NOT_SUPPORTED`, `CHANNEL_NOT_ALLOWED`
  * `SYSTEM_ERROR`, `TIMEOUT`, `INVALID_AMOUNT`, `KYC_PENDING`, `KYC_REJECTED`
  * `EXPIRED`, `CANCELLED_BY_USER`, `CANCELLED_BY_MERCHANT`, `REFUSED_BY_ISSUER`, `DO_NOT_HONOR`
  * `INVALID_PIN`, `PIN_TRIES_EXCEEDED`, `INSUFFICIENT_LIQUIDITY`, `VALIDATION_FAILED`, `OTHER`

  **Lista completa:** Ver [Enum Razón de Transacción](/es/api-reference/transactions/reason-enum) para los 60+ valores permitidos.

  **Ejemplo**:

  ```json theme={null}
  {
    "reason": "INSUFFICIENT_FUNDS"
  }
  ```
</ParamField>

<ParamField body="locationDetails" type="object">
  Información de ubicación geográfica donde ocurrió la transacción. Útil para detección de fraude, análisis de riesgo geográfico y reportes de cumplimiento.

  **Tipo**: `object` (opcional)

  **Campos Soportados**:

  **Información de Dirección**:

  * `country` (string) - Código de país ISO 3166-1 alpha-2 (ej: "US", "BR", "AR")
  * `countryName` (string) - Nombre completo del país
  * `city` (string) - Nombre de la ciudad
  * `region` (string) - Estado o provincia
  * `address` (string) - Dirección completa
  * `street` (string) - Nombre de la calle
  * `streetNumber` (string) - Número de calle
  * `postalCode` (string) - Código postal
  * `neighborhood` (string) - Barrio o distrito

  **Coordenadas** (para visualización en mapas):

  * `latitude` (number) - Coordenada de latitud (-90 a 90)
  * `longitude` (number) - Coordenada de longitud (-180 a 180)

  **Información Adicional**:

  * `timezone` (string) - Zona horaria IANA (ej: "America/Sao\_Paulo")
  * `placeId` (string) - ID de Google Places o identificador similar

  **Ejemplo**:

  ```json theme={null}
  {
    "country": "BR",
    "countryName": "Brasil",
    "city": "São Paulo",
    "region": "SP",
    "address": "Av. Paulista, 1578",
    "street": "Av. Paulista",
    "streetNumber": "1578",
    "postalCode": "01310-200",
    "latitude": -23.5505,
    "longitude": -46.6333,
    "timezone": "America/Sao_Paulo"
  }
  ```

  **Casos de Uso**:

  * **Detección de Fraude**: Identificar transacciones desde ubicaciones inusuales o países de alto riesgo
  * **Análisis Geográfico**: Analizar patrones de transacciones por región
  * **Cumplimiento**: Rastrear transacciones transfronterizas para reportes regulatorios
  * **Reglas de Velocidad**: Detectar viajes imposibles (mismo usuario en diferentes ubicaciones en poco tiempo)
</ParamField>

<ParamField body="deviceDetails" type="object">
  Información del dispositivo para la transacción. Crítico para detección de fraude, fingerprinting de dispositivos y análisis de seguridad.

  **Tipo**: `object` (opcional)

  **Campos Soportados**:

  **Identificación de Dispositivo**:

  * `deviceId` (string) - Identificador único del dispositivo
  * `externalId` (string) - Su ID externo del dispositivo

  **Plataforma y Sistema Operativo**:

  * `platform` (enum) - Plataforma del dispositivo: `android`, `ios`, `web`, `desktop`, `mobile`, `tablet`, `pos`, `atm`
  * `osName` (string) - Nombre del sistema operativo (ej: "Android", "iOS", "Windows", "macOS")
  * `osVersion` (string) - Versión del SO (ej: "13.0", "16.4")

  **Información del Dispositivo**:

  * `manufacturer` (string) - Fabricante del dispositivo (ej: "Samsung", "Apple")
  * `model` (string) - Modelo del dispositivo (ej: "Galaxy S22", "iPhone 14")
  * `brand` (string) - Marca del dispositivo
  * `deviceName` (string) - Nombre asignado por el usuario al dispositivo

  **Información del Navegador** (para plataforma web):

  * `browser` (string) - Nombre del navegador (ej: "Chrome", "Safari", "Firefox")
  * `browserVersion` (string) - Versión del navegador
  * `userAgent` (string) - String completo del user agent

  **Banderas de Seguridad**:

  * `isEmulator` (boolean) - Si el dispositivo es un emulador
  * `isRooted` (boolean) - Si el dispositivo está rooteado (Android)
  * `isJailbroken` (boolean) - Si el dispositivo está jailbreakeado (iOS)

  **Información de Red**:

  * `ipAddress` (string) - Dirección IP (formato validado)
  * `isVpn` (boolean) - Si la conexión es a través de VPN
  * `isTor` (boolean) - Si la conexión es a través de Tor
  * `isProxy` (boolean) - Si la conexión es a través de proxy

  **Fingerprinting de Dispositivo**:

  * `deviceFingerprint` (string) - Hash único de huella digital del dispositivo para rastreo

  **Detalles Adicionales**:

  * `screenResolution` (string) - Resolución de pantalla (ej: "1920x1080")
  * `language` (string) - Idioma del dispositivo
  * `timezone` (string) - Zona horaria del dispositivo

  **Ejemplo**:

  ```json theme={null}
  {
    "platform": "mobile",
    "osName": "Android",
    "osVersion": "13",
    "manufacturer": "Samsung",
    "model": "Galaxy S22",
    "brand": "Samsung",
    "ipAddress": "192.168.1.1",
    "isVpn": false,
    "isTor": false,
    "isEmulator": false,
    "isRooted": false,
    "deviceFingerprint": "abc123def456...",
    "screenResolution": "1080x2400",
    "language": "pt-BR",
    "timezone": "America/Sao_Paulo"
  }
  ```

  **Casos de Uso**:

  * **Detección de Fraude**: Identificar dispositivos sospechosos (emuladores, dispositivos rooteados, uso de VPN)
  * **Fingerprinting de Dispositivo**: Rastrear dispositivos únicos a través de transacciones para análisis de comportamiento
  * **Análisis de Seguridad**: Detectar anomalías en patrones de dispositivos (nuevo dispositivo, velocidad de dispositivo imposible)
  * **Cumplimiento**: Documentar información del dispositivo para rastros de auditoría
  * **Experiencia de Usuario**: Personalizar experiencia basada en tipo y capacidades del dispositivo
</ParamField>

<ParamField body="description" type="string">
  Descripción de la transacción

  **Tipo**: `string` (longitud máxima: 1000, opcional)
</ParamField>

<ParamField body="category" type="string">
  Categoría de transacción para agrupación

  **Tipo**: `string` (longitud máxima: 100, opcional)
</ParamField>

<ParamField body="metadata" type="object">
  Metadatos personalizados para almacenar información adicional de la transacción.

  **Tipo**: `object` (opcional, estructura validada)

  **Campos Estándar Soportados**:

  ### `tags` (object) - **Sistema de Categorización Clave-Valor**

  El campo `tags` le permite agregar pares clave-valor personalizados para categorización flexible, filtrado y gestión de flujos de trabajo. Esto es particularmente útil para:

  * Filtrado personalizado en dashboards y reportes
  * Activar lógica de negocio específica
  * Seguimiento del estado de revisión
  * Categorización por nivel de riesgo o fuente
  * Estados de flujo de trabajo personalizados

  **Formato**: `{ "clave1": "valor1", "clave2": "valor2" }`

  **Patrones Comunes de Tags**:

  * `risk_level` (string) - "low", "medium", "high", "critical"
  * `source` (string) - "api", "web", "mobile", "batch", "import"
  * `channel` (string) - "online", "branch", "atm", "call\_center", "partner"
  * `reviewed` (boolean) - false (pendiente de revisión), true (revisado)
  * `category` (string) - "payroll", "supplier", "refund", "investment", "loan", "bill\_payment"
  * `priority` (string) - "low", "normal", "high", "urgent"
  * `team` (string) - "compliance", "fraud", "support", "operations"
  * `campaign` (string) - Identificador de campaña de marketing o negocio
  * `approved_by` (string) - Usuario o sistema que aprobó
  * `requires_approval` (boolean) - Requiere aprobación manual
  * `customer_segment` (string) - "vip", "regular", "new", "dormant"
  * `product_type` (string) - "savings", "investment", "loan", "transfer"
  * `region` (string) - "north", "south", "latam", "emea", "apac"
  * `business_unit` (string) - "retail", "corporate", "wealth", "sme"

  **Ejemplos de Casos de Uso**:

  **Ejemplo 1: Flujo de trabajo basado en riesgo**

  ```json theme={null}
  {
    "tags": {
      "risk_level": "high",
      "reviewed": false,
      "requires_approval": true,
      "assigned_to": "fraud_team"
    }
  }
  ```

  **Ejemplo 2: Categorización de negocio**

  ```json theme={null}
  {
    "tags": {
      "category": "payroll",
      "batch_id": "PAY_2025_01",
      "department": "engineering",
      "cost_center": "R&D"
    }
  }
  ```

  **Ejemplo 3: Seguimiento multi-canal**

  ```json theme={null}
  {
    "tags": {
      "source": "mobile_app",
      "channel": "online",
      "campaign": "winter_2025",
      "referral_code": "FRIEND123",
      "first_transaction": true,
      "customer_segment": "new"
    }
  }
  ```

  **Ejemplo 4: Operaciones bancarias**

  ```json theme={null}
  {
    "tags": {
      "channel": "branch",
      "business_unit": "retail",
      "product_type": "loan",
      "region": "latam",
      "requires_approval": true,
      "approved_by": "manager_john"
    }
  }
  ```

  **Filtrar transacciones por tags**: Posteriormente puede filtrar transacciones usando estos tags en endpoints de listado o dashboards.

  ### Otros Campos de Metadata:

  * `purpose` (string) - Propósito de la transacción (ej: "salary", "invoice\_payment")
  * `frequency` (string) - Frecuencia de la transacción (ej: "monthly", "one-time")
  * `contract_number` (string) - Número de contrato (para pagos empresariales)
  * `enhanced_due_diligence` (boolean) - Bandera de EDD
  * `block_reason` (string) - Razón de bloqueo
  * `compliance_alert` (boolean) - Bandera de alerta de cumplimiento

  **Ejemplo Completo**:

  ```json theme={null}
  {
    "tags": {
      "risk_level": "medium",
      "source": "api",
      "reviewed": false,
      "category": "invoice_payment"
    },
    "purpose": "supplier_payment",
    "frequency": "monthly",
    "contract_number": "CNT-2025-001",
    "enhanced_due_diligence": false
  }
  ```

  Se permiten campos personalizados más allá de los estándar y serán preservados.
</ParamField>

<ParamField body="transactedAt" type="string">
  Cuándo ocurrió la transacción (timestamp ISO 8601). Por defecto es la hora actual si no se proporciona.

  **Tipo**: `string` (datetime ISO 8601, opcional)
</ParamField>

<ParamField body="executeRules" type="boolean" default="true">
  Si ejecutar reglas de riesgo automáticamente después de crear la transacción

  **Tipo**: `boolean` (por defecto: true)
</ParamField>

#### Métodos de Pago

* `CARD` - Pago con tarjeta de crédito/débito
* `ACH` - Transferencia ACH (EE.UU.)
* `PIX` - Pago instantáneo brasileño
* `TED` - Transferencia bancaria brasileña (TED)
* `BOLETO` - Pago con boleto brasileño
* `WALLET` - Pago con billetera digital
* `SWIFT` - Transferencia internacional SWIFT
* `IBAN` - Transferencia basada en IBAN
* `CBU` - Cuenta bancaria argentina (CBU)
* `CVU` - Billetera virtual argentina (CVU)
* `DEBIN` - Débito directo argentino
* `GENERIC_BANK_ACCOUNT` - Transferencia bancaria genérica
* `MPESA` - Dinero móvil M-Pesa
* `UPI` - Pago UPI de India
* `CHECK` - Cheque físico
* `ECHECK` - Cheque electrónico
* `QR_CODE` - Pago con código QR
* `ONLINE_PAYMENT` - Pago en línea genérico
* `WITHDRAWAL_ORDER` - Orden de retiro

#### Tipos de Cuenta

* `PERSONAL` - Cuenta personal
* `BUSINESS` - Cuenta empresarial
* `MERCHANT` - Cuenta de comerciante
* `SAVINGS` - Cuenta de ahorros
* `CHECKING` - Cuenta corriente
* `INVESTMENT` - Cuenta de inversión
* `ESCROW` - Cuenta en garantía
* `PREPAID` - Cuenta prepago
* `OTHER` - Otro tipo de cuenta

### Códigos MCC

Los Merchant Category Codes (MCC) clasifican tipos de negocio:

```json theme={null}
{
  "mccCode": "5411"  // Supermercados
}
```

Ejemplos comunes:

* `5411` - Supermercados
* `5812` - Restaurantes
* `5999` - Venta al por menor diversa
* `6011` - ATM / Retiro de efectivo
* `7995` - Juegos de azar

### Tags y Metadata

```json theme={null}
{
  "tags": ["high_value", "first_transaction", "promotional"],
  "metadata": {
    "campaignId": "summer_2024",
    "referralCode": "FRIEND10",
    "customField": "any_value"
  }
}
```

### Multi-Currency Support

gu1 proporciona conversión automática de moneda para todas las transacciones. Cada organización tiene una **moneda base** configurada (por defecto: USD), y todas las transacciones se convierten automáticamente a esta moneda base para una evaluación de reglas y reportes consistentes.

#### Cómo Funciona

1. **Detección Automática**: Cuando la `currency` de una transacción difiere de la moneda base de tu organización, se activa la conversión automática
2. **Tasas en Tiempo Real**: Las tasas de cambio se obtienen de nuestro servicio de monedas en tiempo real
3. **Almacenamiento Dual de Montos**: Se almacenan tanto los montos originales como los convertidos
4. **Evaluación de Reglas**: Las reglas pueden usar `amount` (original) o `amountInUsd` (convertido a USD)

#### Monedas Soportadas

Más de 150 monedas soportadas incluyendo:

* **Principales**: USD, EUR, GBP, JPY, CHF, CAD, AUD
* **América Latina**: BRL, ARS, MXN, COP, CLP, PEN, UYU
* **Asia**: CNY, INR, KRW, SGD, HKD, THB, MYR
* **Crypto**: BTC, ETH, USDT, USDC
* **Y muchas más** (estándar ISO 4217)

#### Fuentes de Tasa de Cambio

| Fuente            | Descripción                                          | Cuándo se Usa                  |
| ----------------- | ---------------------------------------------------- | ------------------------------ |
| `ms-provider`     | Tasas en tiempo real del microservicio de monedas    | Fuente primaria                |
| `cache-fallback`  | Tasas en caché cuando el servicio no está disponible | Fallback (\< 1h de antigüedad) |
| `no-conversion`   | No se necesita conversión (misma moneda)             | Igual a la base                |
| `client-provided` | Tasa personalizada proporcionada por el cliente      | Override opcional              |

#### Campos de respuesta

Los datos de conversión van en el objeto **transaction**:

* `transaction.amount`, `transaction.currency` – monto y moneda originales
* `transaction.amountInUsd` – monto convertido a USD (null si falló la conversión o no aplica)
* `transaction.exchangeRate`, `transaction.rateSource` – tasa usada y fuente (ej. `ms-provider`)

#### Uso de Montos Convertidos en Reglas

Las reglas pueden referenciar ambos montos:

```json theme={null}
{
  "conditions": [
    {
      "field": "amount",
      "operator": "GREATER_THAN",
      "value": 1000
    }
  ]
}
```

O usar el monto convertido para umbrales consistentes:

```json theme={null}
{
  "conditions": [
    {
      "field": "amountInUsd",
      "operator": "GREATER_THAN",
      "value": 10000
    }
  ]
}
```

**Mejor Práctica**: Usar `amountInUsd` en reglas para asegurar umbrales consistentes independientemente de la moneda de la transacción.

#### Manejo de Errores

Si la conversión de moneda falla:

* El procesamiento de la transacción continúa con el monto original
* `transaction.amountInUsd` y `transaction.exchangeRate` serán null
* Las reglas que usan `amountInUsd` usarán el `amount` original como fallback si la conversión falló
* El error se registra pero no bloquea la transacción

#### Ejemplo: Transacción Multi-Moneda

```json theme={null}
{
  "transaction": {
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": 850.00,
    "currency": "EUR",
    "timestamp": "2024-10-28T15:00:00Z",
    "originEntityId": "customer_france_001",
    "destinationEntityId": "merchant_usa_001"
  }
}
```

**Respuesta** (la conversión va en `transaction`). Ver [Crear transacción](/es/api-reference/transactions/create) para la estructura completa.

```json theme={null}
{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": "850.00",
    "currency": "EUR",
    "amountInUsd": "935.00",
    "exchangeRate": "1.10",
    "rateSource": "ms-provider",
    "status": "CREATED",
    "riskScore": "25",
    "flagged": false,
    "createdAt": "2024-10-28T15:00:01.000Z",
    "updatedAt": "2024-10-28T15:00:01.000Z"
  },
  "rulesExecutionSummary": { "rulesHit": [], "rulesNoHit": [], "actionsExecuted": {}, "totalScore": 25 }
}
```

## Complete Request Examples

### PIX Transfer (Brazil)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/transactions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "externalId": "txn_pix_12345",
      "type": "TRANSFER",
      "status": "CREATED",
      "amount": 500.00,
      "currency": "BRL",
      "originEntityId": "customer_maria_001",
      "originName": "Maria Silva",
      "originCountry": "BR",
      "originDetails": {
        "deviceId": "device_123",
        "ipAddress": "189.123.45.67",
        "country": "BR",
        "city": "São Paulo",
        "paymentDetails": {
          "pixKey": "maria.silva@example.com",
          "pixType": "email",
          "bankName": "Banco do Brasil"
        }
      },
      "destinationEntityId": "merchant_loja_002",
      "destinationName": "Loja Online",
      "destinationCountry": "BR",
      "destinationDetails": {
        "merchantId": "MER_002",
        "mcc": "5411",
        "paymentDetails": {
          "accountNumber": "98765",
          "accountType": "merchant",
          "bankName": "Bradesco"
        }
      },
      "description": "Purchase at Online Store",
      "category": "retail",
      "metadata": {
        "storeId": "store_002",
        "orderId": "order_789"
      },
      "transactedAt": "2024-12-23T14:30:00Z",
      "executeRules": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/transactions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      externalId: 'txn_pix_12345',
      type: 'transfer',
      status: 'CREATED',
      amount: 500.00,
      currency: 'BRL',
      originEntityId: 'customer_maria_001',
      originName: 'Maria Silva',
      originCountry: 'BR',
      originDetails: {
        deviceId: 'device_123',
        ipAddress: '189.123.45.67',
        country: 'BR',
        city: 'São Paulo',
        paymentDetails: {
          pixKey: 'maria.silva@example.com',
          pixType: 'email',
          bankName: 'Banco do Brasil'
        }
      },
      destinationEntityId: 'merchant_loja_002',
      destinationName: 'Loja Online',
      destinationCountry: 'BR',
      destinationDetails: {
        merchantId: 'MER_002',
        mcc: '5411',
        paymentDetails: {
          accountNumber: '98765',
          accountType: 'merchant',
          bankName: 'Bradesco'
        }
      },
      description: 'Purchase at Online Store',
      category: 'retail',
      metadata: {
        storeId: 'store_002',
        orderId: 'order_789'
      },
      transactedAt: new Date().toISOString(),
      executeRules: true
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime

  url = "http://api.gu1.ai/transactions"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "externalId": "txn_pix_12345",
      "type": "TRANSFER",
      "status": "CREATED",
      "amount": 500.00,
      "currency": "BRL",
      "originEntityId": "customer_maria_001",
      "originName": "Maria Silva",
      "originCountry": "BR",
      "originDetails": {
          "deviceId": "device_123",
          "ipAddress": "189.123.45.67",
          "country": "BR",
          "city": "São Paulo",
          "paymentDetails": {
              "pixKey": "maria.silva@example.com",
              "pixType": "email",
              "bankName": "Banco do Brasil"
          }
      },
      "destinationEntityId": "merchant_loja_002",
      "destinationName": "Loja Online",
      "destinationCountry": "BR",
      "destinationDetails": {
          "merchantId": "MER_002",
          "mcc": "5411",
          "paymentDetails": {
              "accountNumber": "98765",
              "accountType": "merchant",
              "bankName": "Bradesco"
          }
      },
      "description": "Purchase at Online Store",
      "category": "retail",
      "metadata": {
          "storeId": "store_002",
          "orderId": "order_789"
      },
      "transactedAt": datetime.utcnow().isoformat() + "Z",
      "executeRules": True
  }

  response = requests.post(url, json=payload, headers=headers)
  result = response.json()

  print(f"Transaction ID: {result['transaction']['id']}")
  print(f"Risk Score: {result['transaction']['riskScore']}")
  ```
</CodeGroup>

### Card Payment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/transactions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "externalId": "txn_card_67890",
      "type": "PAYMENT",
      "amount": 1250.00,
      "currency": "USD",
      "originEntityId": "customer_john_003",
      "originName": "John Smith",
      "originCountry": "US",
      "originDetails": {
        "deviceId": "device_456",
        "deviceType": "desktop",
        "ipAddress": "198.51.100.42",
        "country": "US",
        "paymentDetails": {
          "cardLast4": "8765",
          "cardBrand": "Visa",
          "expiryMonth": "12",
          "expiryYear": "2027"
        }
      },
      "destinationEntityId": "merchant_electronics_001",
      "destinationName": "Electronics Store",
      "destinationCountry": "US",
      "destinationDetails": {
        "mcc": "5732",
        "merchantId": "MER_ELEC_001",
        "paymentDetails": {
          "accountNumber": "ACC123456",
          "accountType": "merchant"
        }
      },
      "description": "Laptop purchase",
      "category": "electronics",
      "metadata": {
        "sessionId": "sess_abc123",
        "isFirstTransaction": true
      },
      "executeRules": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/transactions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      externalId: 'txn_card_67890',
      type: 'payment',
      amount: 1250.00,
      currency: 'USD',
      originEntityId: 'customer_john_003',
      originName: 'John Smith',
      originCountry: 'US',
      originDetails: {
        deviceId: 'device_456',
        deviceType: 'desktop',
        ipAddress: '198.51.100.42',
        country: 'US',
        paymentDetails: {
          cardLast4: '8765',
          cardBrand: 'Visa',
          expiryMonth: '12',
          expiryYear: '2027'
        }
      },
      destinationEntityId: 'merchant_electronics_001',
      destinationName: 'Electronics Store',
      destinationCountry: 'US',
      destinationDetails: {
        mcc: '5732',
        merchantId: 'MER_ELEC_001',
        paymentDetails: {
          accountNumber: 'ACC123456',
          accountType: 'merchant'
        }
      },
      description: 'Laptop purchase',
      category: 'electronics',
      metadata: {
        sessionId: 'sess_abc123',
        isFirstTransaction: true
      },
      executeRules: true
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  url = "http://api.gu1.ai/transactions"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "externalId": "txn_card_67890",
      "type": "PAYMENT",
      "amount": 1250.00,
      "currency": "USD",
      "originEntityId": "customer_john_003",
      "originName": "John Smith",
      "originCountry": "US",
      "originDetails": {
          "deviceId": "device_456",
          "deviceType": "desktop",
          "ipAddress": "198.51.100.42",
          "country": "US",
          "paymentDetails": {
              "cardLast4": "8765",
              "cardBrand": "Visa",
              "expiryMonth": "12",
              "expiryYear": "2027"
          }
      },
      "destinationEntityId": "merchant_electronics_001",
      "destinationName": "Electronics Store",
      "destinationCountry": "US",
      "destinationDetails": {
          "mcc": "5732",
          "merchantId": "MER_ELEC_001",
          "paymentDetails": {
              "accountNumber": "ACC123456",
              "accountType": "merchant"
          }
      },
      "description": "Laptop purchase",
      "category": "electronics",
      "metadata": {
          "sessionId": "sess_abc123",
          "isFirstTransaction": True
      },
      "executeRules": True
  }

  response = requests.post(url, json=payload, headers=headers)
  result = response.json()

  print(f"Transaction ID: {result['transaction']['id']}")
  print(f"Status: {result['transaction']['status']}")
  ```
</CodeGroup>

### Multi-Currency Transfer

```bash theme={null}
curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_euro_001",
    "type": "TRANSFER",
    "amount": 750.50,
    "currency": "EUR",
    "originEntityId": "user_alice_001",
    "originName": "Alice Martinez",
    "originCountry": "ES",
    "originDetails": {
      "deviceId": "device_789",
      "ipAddress": "88.22.15.10",
      "country": "ES",
      "city": "Madrid",
      "paymentDetails": {
        "accountNumber": "ES1234567890123456789012",
        "bankName": "Banco Santander",
        "accountType": "personal"
      }
    },
    "destinationEntityId": "user_bob_002",
    "destinationName": "Bob Johnson",
    "destinationCountry": "DE",
    "destinationDetails": {
      "country": "DE",
      "paymentDetails": {
        "accountNumber": "DE89370400440532013000",
        "bankName": "Deutsche Bank",
        "accountType": "personal"
      }
    },
    "description": "International transfer",
    "category": "p2p",
    "executeRules": true
  }'
```

## Response

Detalle completo en [Crear transacción](/es/api-reference/transactions/create). La respuesta devuelve **`transaction` como objeto** (una sola transacción creada).

### Success Response (201 Created)

```json theme={null}
{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_pix_12345",
    "organizationId": "org_uuid",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": "500.00",
    "currency": "BRL",
    "amountInUsd": "100.00",
    "exchangeRate": "0.2000000000",
    "rateSource": "ms-provider",
    "rateTimestamp": "2024-12-23T14:30:00.000Z",
    "convertedAt": "2024-12-23T14:30:01.000Z",
    "originEntityId": "customer_maria_001",
    "originExternalId": null,
    "originName": "Maria Silva",
    "originCountry": "BR",
    "originDetails": { "deviceId": "device_123", "ipAddress": "189.123.45.67", "country": "BR", "city": "São Paulo", "paymentDetails": { "pixKey": "maria.silva@example.com", "pixType": "email", "bankName": "Banco do Brasil" } },
    "destinationEntityId": "merchant_loja_002",
    "destinationExternalId": null,
    "destinationName": "Loja Online",
    "destinationCountry": "BR",
    "destinationDetails": { "merchantId": "MER_002", "mcc": "5411", "paymentDetails": { "accountNumber": "98765", "accountType": "merchant", "bankName": "Bradesco" } },
    "riskScore": "25.50",
    "riskFactors": [],
    "flagged": false,
    "description": "Purchase at Online Store",
    "category": "retail",
    "metadata": { "storeId": "store_002", "orderId": "order_789" },
    "transactedAt": "2024-12-23T14:30:00.000Z",
    "createdAt": "2024-12-23T14:30:01.000Z",
    "updatedAt": "2024-12-23T14:30:01.000Z"
  },
  "rulesExecutionSummary": {
    "rulesHit": [],
    "rulesNoHit": [],
    "actionsExecuted": {},
    "totalScore": 25
  }
}
```

### Response Fields (resumen)

<ResponseField name="transaction" type="object">
  La transacción creada. Incluye **id**, **externalId**, **type**, **status**, **amount** (string), **currency**, **amountInUsd**, **exchangeRate**, **rateSource**, **riskScore** (string), **riskFactors**, **flagged**, **reason**, **originDetails**, **destinationDetails**, **processingTimeMs**, **processedAt**, **createdAt**, **updatedAt**. Ver [Crear transacción](/es/api-reference/transactions/create) para la lista completa.
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  **En la raíz de la respuesta.** **Solo presente cuando executeRules es true y se ejecutó el motor de reglas.** Resumen de qué reglas hicieron match (hit) y cuáles no (no hit), acciones ejecutadas y puntuación total. No se incluye cuando `executeRules` es `false`. Estructura completa y ejemplo: [Resumen de Ejecución de Reglas](/es/api-reference/rules-execution-summary).

  * **rulesHit** (array) - Reglas cuyas condiciones se cumplieron. Cada ítem: **name**, **description**, **score**, **priority**, **category**, **status** (ej. `active`, `shadow`), **conditions** (array de `{ field, value, operator? }`), **actions** (alerts, suggestion, status, assignedUser).
  * **rulesNoHit** (array) - Reglas evaluadas cuyas condiciones no se cumplieron. Misma estructura que rulesHit (incluye acciones configuradas, no ejecutadas).
  * **actionsExecuted** (object) - Acciones ejecutadas agregadas de todas las reglas que hicieron hit: **alerts** (array de `{ name?, type?, severity?, description? }`), **suggestion** (`BLOCK` | `SUSPEND` | `FLAG`, la de mayor peso), **status** (estado de entidad aplicado, si hubo), **assignedUser** (`{ userId }`, si hubo), **customKeys** (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match (ej. `require_kyc`, `flag_for_review`). Presente cuando alguna regla que hizo match tiene una acción personalizada con clave; para integraciones/workflows.
  * **totalScore** (number) - Suma del **score** de todas las reglas que hicieron hit y **no** están en estado `shadow`.
</ResponseField>

### Transaction Status Values

El estado de la transacción sigue un modelo de máquina de estados con estados abiertos y cerrados:

#### Estados Abiertos (Pueden Transicionar)

| Estado       | Descripción                          | Puede Transicionar A                                       |
| ------------ | ------------------------------------ | ---------------------------------------------------------- |
| `CREATED`    | Transacción creada (estado inicial)  | PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, SUCCESSFUL |
| `PROCESSING` | Transacción siendo procesada         | SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL   |
| `SUSPENDED`  | Transacción temporalmente suspendida | PROCESSING, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL  |

#### Estados Cerrados (Finales)

| Estado       | Descripción                         | Nota                               |
| ------------ | ----------------------------------- | ---------------------------------- |
| `SENT`       | Transacción enviada/transmitida     | Estado final - no más transiciones |
| `EXPIRED`    | Transacción expirada                | Estado final - no más transiciones |
| `DECLINED`   | Transacción rechazada/declinada     | Estado final - no más transiciones |
| `REFUNDED`   | Transacción reembolsada/reversada   | Estado final - no más transiciones |
| `SUCCESSFUL` | Transacción completada exitosamente | Estado final - no más transiciones |

**Importante**: Una vez que una transacción alcanza un estado cerrado, no puede volver a un estado abierto. Esto asegura la integridad de la transacción y rastros de auditoría apropiados.

### Risk Score Ranges

Puntuación de riesgo de 0 a 100 (almacenada con precisión de 2 decimales):

* **0-30**: Riesgo bajo (verde)
* **31-60**: Riesgo medio (amarillo)
* **61-80**: Riesgo alto (naranja)
* **81-100**: Riesgo crítico (rojo)

### Currency Conversion Rate Sources

El campo `rateSource` indica cómo se obtuvo la tasa de cambio:

* **ms-provider**: Tasa en tiempo real del microservicio de monedas (fuente primaria)
* **cache-fallback**: Tasa en caché (\< 1h de antigüedad) cuando el servicio no está disponible
* **no-conversion**: No se necesita conversión (la moneda ya es USD)
* **null**: La conversión falló o no aplica

## Error Responses

### 400 Bad Request - Validation Error

**Ejemplo 1: Missing required fields**

```json theme={null}
{
  "error": "Validation failed",
  "details": [
    {
      "path": "externalId",
      "message": "Required",
      "code": "invalid_type"
    },
    {
      "path": "amount",
      "message": "Number must be greater than 0",
      "code": "too_small"
    }
  ]
}
```

**Ejemplo 2: Invalid paymentDetails for card (nested in originDetails)**

```json theme={null}
{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.paymentDetails.cardLast4",
      "message": "Card last 4 digits must be exactly 4 characters",
      "code": "invalid_length"
    },
    {
      "path": "originDetails.paymentDetails.cardBrand",
      "message": "Invalid card brand",
      "code": "invalid_string"
    }
  ]
}
```

**Ejemplo 3: Invalid PIX details (nested in originDetails)**

```json theme={null}
{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.paymentDetails.pixKey",
      "message": "Required",
      "code": "invalid_type"
    },
    {
      "path": "originDetails.paymentDetails.pixType",
      "message": "Invalid PIX type",
      "code": "invalid_enum_value"
    },
    {
      "path": "originDetails.paymentDetails.bankName",
      "message": "String must contain at least 1 character(s)",
      "code": "too_small"
    }
  ]
}
```

**Ejemplo 4: Invalid IP address in originDetails**

```json theme={null}
{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.ipAddress",
      "message": "Invalid IP address format",
      "code": "invalid_string"
    },
    {
      "path": "originDetails.country",
      "message": "Country must be ISO 2 letter code",
      "code": "invalid_length"
    }
  ]
}
```

### 400 Bad Request - Missing Organization

```json theme={null}
{
  "error": "Organization ID and User ID are required"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Failed to create transaction",
  "details": "Database connection error"
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Rules Configuration" icon="sliders" href="/es/use-cases/transaction-monitoring/rules-configuration">
    Learn to create rules
  </Card>

  <Card title="Fraud Detection" icon="shield" href="/es/use-cases/transaction-monitoring/fraud-detection">
    Fraud detection examples
  </Card>

  <Card title="AML Monitoring" icon="building-columns" href="/es/use-cases/transaction-monitoring/aml-monitoring">
    AML compliance rules
  </Card>

  <Card title="Overview" icon="book" href="/es/use-cases/transaction-monitoring/overview">
    Back to overview
  </Card>
</CardGroup>