> ## 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 Criar Transação para Monitoramento

> Endpoint POST /transactions para monitoramento: esquema do request, conversão de moedas, métodos de pagamento e exemplos práticos para fraude e AML.

## Referência canónica do endpoint

A **referência oficial** do endpoint `POST /transactions` (estrutura da resposta, erros, campos) está em:

**[Criar transação](/pt/api-reference/transactions/create)** (API Reference → Transações)

Lá você encontra a resposta atual: `transaction` é um **objeto** (a transação criada) e, quando as regras rodam, **`rulesExecutionSummary`** vem na raiz da resposta (ver [Resumo de Execução de Regras](/pt/api-reference/rules-execution-summary)).

Esta página adiciona **contexto de uso** para monitoramento: conversão de moeda, exemplos por método de pagamento (PIX, cartão, multi-moeda) e descrição detalhada dos campos.

***

## Endpoint: Criar Transação

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

Cria uma nova transação. Os valores são convertidos para USD quando a moeda não for USD. Com `executeRules: true` (padrão), o motor de regras é executado e a resposta inclui `rulesExecutionSummary` na raiz quando as regras são executadas.

## Autenticação

Todas as requisições devem incluir uma chave API no cabeçalho `Authorization`:

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

## Cabeçalhos Obrigatórios

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

## Corpo da Requisição

<ParamField body="externalId" type="string" required>
  Seu identificador único para esta transação no seu sistema

  **Tipo**: `string` (comprimento mínimo: 1)
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de transação. Opções:

  * `PAYMENT` - Compra ou pagamento a comerciante
  * `TRANSFER` - Transferência entre contas/usuários
  * `WITHDRAWAL` - Saque ou débito de conta
  * `DEPOSIT` - Depósito ou crédito de conta
  * `REFUND` - Reembolso de transação anterior
  * `CHARGEBACK` - Disputa de estorno
  * `REVERSAL` - Reversão de transação
  * `FEE` - Cobrança de taxa ou comissão
  * `ADJUSTMENT` - Ajuste de saldo
  * `OTHER` - Outro tipo de transação

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

<ParamField body="status" type="string" default="CREATED">
  Status da transação. Segue um modelo de máquina de estados com estados abertos e fechados.

  **Estados Abertos** (podem transitar para outros estados):

  * `CREATED` - Transação criada (padrão)
  * `PROCESSING` - Transação em processamento
  * `SUSPENDED` - Transação temporariamente suspensa

  **Estados Fechados** (finais, não podem voltar a estados abertos):

  * `SENT` - Transação enviada/transmitida
  * `EXPIRED` - Transação expirada
  * `DECLINED` - Transação recusada/declinada
  * `REFUNDED` - Transação reembolsada/revertida
  * `SUCCESSFUL` - Transação concluída com sucesso

  **Tipo**: `enum` - `'CREATED' | 'PROCESSING' | 'SUSPENDED' | 'SENT' | 'EXPIRED' | 'DECLINED' | 'REFUNDED' | 'SUCCESSFUL'` (padrão: 'CREATED')

  **Importante**: Uma vez que uma transação atinge um estado fechado, não pode voltar a um estado aberto. Isso garante a integridade da transação e um rastro de auditoria apropriado.
</ParamField>

<ParamField body="amount" type="number" required>
  Valor da transação (deve ser positivo)

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

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

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

<ParamField body="paymentMethod" type="string">
  Método de pagamento utilizado para a transação

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

  **Valores Possíveis**:

  * `CARD` - Pagamento com cartão de crédito ou débito
  * `ACH` - Automated Clearing House (transferência bancária US)
  * `PIX` - Sistema de pagamentos instantâneos do Brasil
  * `TED` - Transferência bancária brasileira (Transferência Eletrônica Disponível)
  * `BOLETO` - Boleto de pagamento brasileiro
  * `WALLET` - Carteira digital (PayPal, Venmo, etc.)
  * `SWIFT` - Transferência internacional SWIFT
  * `IBAN` - Transferência bancária baseada em IBAN
  * `CBU` - Conta bancária argentina (Clave Bancaria Uniforme)
  * `CVU` - Conta virtual argentina (Clave Virtual Uniforme)
  * `DEBIN` - Sistema de débito instantâneo argentino
  * `GENERIC_BANK_ACCOUNT` - Transferência de conta bancária genérica
  * `MPESA` - M-Pesa mobile money (Quênia)
  * `UPI` - Unified Payments Interface (Índia)
  * `CHECK` - Pagamento com cheque
  * `ECHECK` - Cheque eletrônico
  * `QR_CODE` - Pagamento com código QR
  * `ONLINE_PAYMENT` - Pagamento online genérico
  * `WITHDRAWAL_ORDER` - Ordem de saque

  **Exemplo**: `"PIX"` ou `"CARD"`
</ParamField>

<ParamField body="originEntityId" type="string">
  UUID da entidade de origem (remetente) no sistema gu1

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

<ParamField body="originExternalId" type="string">
  Seu ID externo para a entidade de origem

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

<ParamField body="originTaxId" type="string">
  Tax / documento de **origem** no **raiz** do corpo. **Terceiro** critério (após `originEntityId` e `originExternalId`); match normalizado a `entity.taxId`. Máx. 50 caracteres. **Tipo**: `string` (opcional)
</ParamField>

<ParamField body="originName" type="string">
  Nome da entidade de origem (remetente)

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

<ParamField body="originCountry" type="string">
  Código de país ISO 3166-1 alpha-2 da entidade de origem

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

<ParamField body="originDetails" type="object">
  Informações contextuais sobre a **origem** da transação (dispositivo, geolocalização, conta, flags de segurança). Estes campos coincidem com o schema da API; também pode enviar campos custom adicionais (ex.: `paymentDetails` aninhado ou outras chaves) e serão armazenados.

  **Tipo**: `object` (opcional, estrutura validada; chaves extras permitidas)

  **Diferença Importante**:

  * `originCountry` (campo direto) = País da entidade
  * `originDetails.country` = País do dispositivo/IP no momento da transação (pode diferir se estiver viajando)

  **Campos Suportados**:

  **Dispositivo/Técnico**:

  * `deviceId` (string) - Identificador do dispositivo
  * `deviceFingerprint` (string) - Hash de impressão digital do dispositivo
  * `deviceType` (enum) - `mobile` | `desktop` | `tablet` | `pos` | `atm`
  * `userAgent` (string) - User agent do navegador
  * `ipAddress` (string) - Endereço IP (formato validado)

  **Geolocalização**:

  * `country` (string) - Código ISO de 2 letras
  * `city` (string) - Nome da cidade
  * `region` (string) - Estado/província
  * `latitude` (number) - Latitude (-90 a 90)
  * `longitude` (number) - Longitude (-180 a 180)
  * `timezone` (string) - Identificador de fuso horário

  **Detalhes de Pagamento** (objeto aninhado):

  * `paymentDetails` (object) - Informações específicas de pagamento para a origem. Você pode enviar qualquer campo relacionado a pagamento:
    * **Detalhes Bancários/Conta**:
      * `accountNumber` (string) - Número da conta
      * `accountType` (enum) - `checking` | `savings` | `business` | `personal`
      * `bankCode` (string) - Código do banco
      * `bankName` (string) - Nome do banco
      * `routingNumber` (string) - Routing number (US)
      * `swiftCode` (string) - Código SWIFT/BIC
      * `iban` (string) - IBAN (International Bank Account Number)
    * **Detalhes PIX** (Brasil):
      * `pixKey` (string) - Chave PIX
      * `pixType` (enum) - Tipo de chave PIX: `email` | `phone` | `cpf` | `cnpj` | `random`
      * `endToEndId` (string) - ID único end-to-end do PIX
    * **Detalhes de Cartão**:
      * `cardLast4` (string) - Últimos 4 dígitos do cartão
      * `cardBrand` (string) - Bandeira do cartão (Visa, Mastercard, Amex, etc.)
      * `cardholderName` (string) - Nome no cartão
      * `cardBin` (string) - Primeiros 6 dígitos do cartão (BIN)
      * `cardType` (enum) - `credit` | `debit` | `prepaid`
      * `cardCountry` (string) - País emissor do cartão (ISO 2 letras)
      * `cardExpiry` (string) - Data de vencimento (MM/AA)
      * `cardFingerprint` (string) - Impressão digital única do cartão para rastreamento
    * **Detalhes Crypto**:
      * `walletAddress` (string) - Endereço de carteira de criptomoeda
      * `walletType` (string) - Tipo de carteira (ex: "metamask", "coinbase")
      * `blockchain` (string) - Rede blockchain (ex: "ethereum", "bitcoin")
      * `tokenSymbol` (string) - Símbolo do token (ex: "ETH", "BTC", "USDT")
      * `txHash` (string) - Hash da transação blockchain
      * `confirmations` (number) - Número de confirmações blockchain
    * **Carteira/Pagamento Digital**:
      * `walletId` (string) - Identificador de carteira digital
      * `walletProvider` (string) - Provedor de carteira (ex: "paypal", "venmo", "mercadopago")
      * `walletEmail` (string) - Email associado à carteira
    * **Campos Argentina** (CBU/CVU):
      * `cbu` (string) - CBU argentino (22 dígitos)
      * `cvu` (string) - CVU argentino (22 dígitos)
      * `alias` (string) - Alias do CBU/CVU
    * **Campos México** (SPEI):
      * `clabe` (string) - Número CLABE (México, 18 dígitos)
      * `trackingKey` (string) - Chave de rastreamento SPEI
    * **Campos Dinheiro/Cheque**:
      * `checkNumber` (string) - Número do cheque
      * `receiptNumber` (string) - Número do recibo
      * `location` (string) - Localização do pagamento (dinheiro)
    * **E quaisquer outros campos relacionados a pagamento que você precisar**

  **Referência:** Para estruturas sugeridas por método de pagamento (cartão, PIX, CBU/CVU, SPEI, PSE, DEBIN, cripto, wallet, dinheiro, cheque, etc.) ver [Payment Details Schema](/pt/api-reference/transactions/payment-details-schema). Nada é exigido; campos custom são permitidos.

  **Flags de Segurança**:

  * `isVpn` (boolean) - VPN detectada
  * `isTor` (boolean) - Rede Tor detectada
  * `isProxy` (boolean) - Proxy detectado
  * `governmentAccount` (boolean) - Flag de conta governamental

  **Exemplo**:

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

  Campos personalizados são permitidos - o sistema validará campos conhecidos e preservará os personalizados.
</ParamField>

<ParamField body="destinationEntityId" type="string">
  UUID da entidade de destino (destinatário) no sistema gu1

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

<ParamField body="destinationExternalId" type="string">
  Seu ID externo para a entidade de destino

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

<ParamField body="destinationTaxId" type="string">
  Documento de **destino** no **raiz**; terceiro critério, mesma regra de `originTaxId`. **Tipo**: `string` (opcional)
</ParamField>

<ParamField body="destinationName" type="string">
  Nome da entidade de destino (destinatário)

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

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

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

<ParamField body="destinationDetails" type="object">
  Informações contextuais sobre o **destino** da transação (comerciante, dispositivo, geolocalização, conta, flags de risco). Estes campos coincidem com o schema da API; também pode enviar campos custom adicionais (ex.: `paymentDetails` aninhado ou outras chaves) e serão armazenados.

  **Tipo**: `object` (opcional, estrutura validada; chaves extras permitidas)

  **Campos Suportados**:

  **Informações de Comerciante**:

  * `mcc` (string) - Merchant Category Code (4 dígitos, ISO 18245)
  * `mccDescription` (string) - Descrição do MCC (ex: "Restaurants")
  * `merchantId` (string) - Identificador do comerciante
  * `merchantName` (string) - Nome do comerciante
  * `merchantType` (string) - Tipo/categoria do comerciante

  **Dispositivo/Técnico**:

  * `deviceId` (string) - Identificador do dispositivo
  * `deviceType` (enum) - `pos` | `online` | `mobile` | `atm`
  * `ipAddress` (string) - Endereço IP (formato validado)

  **Geolocalização**:

  * `country` (string) - Código ISO de 2 letras
  * `city` (string) - Nome da cidade
  * `region` (string) - Estado/província

  **Detalhes de Pagamento** (objeto aninhado):

  * `paymentDetails` (object) - Informações específicas de pagamento para o destino. Você pode enviar qualquer campo relacionado a pagamento:
    * **Detalhes Bancários/Conta**:
      * `accountNumber` (string) - Número da conta de destino
      * `accountType` (enum) - `checking` | `savings` | `business` | `merchant`
      * `bankCode` (string) - Código do banco
      * `bankName` (string) - Nome do banco
      * `routingNumber` (string) - Routing number (US)
      * `swiftCode` (string) - Código SWIFT/BIC
      * `iban` (string) - IBAN (International Bank Account Number)
    * **Detalhes PIX** (Brasil):
      * `pixKey` (string) - Chave PIX
      * `pixType` (enum) - Tipo de chave PIX: `email` | `phone` | `cpf` | `cnpj` | `random`
      * `endToEndId` (string) - ID único end-to-end do PIX
    * **Detalhes de Cartão**:
      * `cardLast4` (string) - Últimos 4 dígitos do cartão
      * `cardBrand` (string) - Bandeira do cartão (Visa, Mastercard, Amex, etc.)
      * `cardholderName` (string) - Nome no cartão
      * `cardBin` (string) - Primeiros 6 dígitos do cartão (BIN)
      * `cardType` (enum) - `credit` | `debit` | `prepaid`
      * `cardCountry` (string) - País emissor do cartão (ISO 2 letras)
      * `cardExpiry` (string) - Data de vencimento (MM/AA)
      * `cardFingerprint` (string) - Impressão digital única do cartão para rastreamento
    * **Detalhes Crypto**:
      * `walletAddress` (string) - Endereço de carteira de criptomoeda
      * `walletType` (string) - Tipo de carteira (ex: "metamask", "coinbase")
      * `blockchain` (string) - Rede blockchain (ex: "ethereum", "bitcoin")
      * `tokenSymbol` (string) - Símbolo do token (ex: "ETH", "BTC", "USDT")
      * `txHash` (string) - Hash da transação blockchain
      * `confirmations` (number) - Número de confirmações blockchain
    * **Carteira/Pagamento Digital**:
      * `walletId` (string) - Identificador de carteira digital
      * `walletProvider` (string) - Provedor de carteira (ex: "paypal", "venmo", "mercadopago")
      * `walletEmail` (string) - Email associado à carteira
    * **Campos Argentina** (CBU/CVU):
      * `cbu` (string) - CBU argentino (22 dígitos)
      * `cvu` (string) - CVU argentino (22 dígitos)
      * `alias` (string) - Alias do CBU/CVU
    * **Campos México** (SPEI):
      * `clabe` (string) - Número CLABE (México, 18 dígitos)
      * `trackingKey` (string) - Chave de rastreamento SPEI
    * **Campos Dinheiro/Cheque**:
      * `checkNumber` (string) - Número do cheque
      * `receiptNumber` (string) - Número do recibo
      * `location` (string) - Localização do pagamento (dinheiro)
    * **E quaisquer outros campos relacionados a pagamento que você precisar**

  **Referência:** Para estruturas sugeridas por método de pagamento ver [Payment Details Schema](/pt/api-reference/transactions/payment-details-schema). Nada é exigido; campos custom são permitidos.

  **Flags de Risco**:

  * `cryptoExchange` (boolean) - É uma exchange de criptomoedas
  * `highRisk` (boolean) - Flag de comerciante de alto risco
  * `privateSector` (boolean) - Flag de setor privado

  **Exemplo**:

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

  Campos personalizados são permitidos - o sistema validará campos conhecidos e preservará os personalizados.
</ParamField>

<ParamField body="channel" type="string">
  O canal através do qual a transação foi iniciada (máximo 50 caracteres).

  **Tipo**: `string` (comprimento máximo: 50, opcional)

  **Exemplos Comuns**:

  * `mobile_app` - Aplicativo móvel
  * `web_browser` - Navegador web
  * `pos_terminal` - Terminal ponto de venda
  * `api` - Integração API direta
  * `atm` - Caixa eletrônico
  * `phone_banking` - Banking telefônico
  * `branch` - Agência física
  * `call_center` - Central de atendimento
  * `partner_api` - Integração com parceiro

  **Caso de Uso**: Ajuda a segmentar transações por canal de origem para análise de risco, relatórios e inteligência de negócios.

  **Exemplo**:

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

<ParamField body="reason" type="string">
  Motivo opcional do resultado da transação (ex.: recusa, falha, limite excedido). O cliente pode enviar qualquer valor do enum `transaction_reason_type`. Se omitido, o sistema usa `WITHOUT_REASON`. Não é obrigatório — integrações atuais continuam válidas.

  **Tipo**: `string` (enum, opcional, padrão: `WITHOUT_REASON`)

  **Valores comuns** (o enum completo tem 60+ valores):

  * `WITHOUT_REASON` - Sem motivo específico (padrão quando omitido)
  * `INSUFFICIENT_FUNDS` - Fundos 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 Motivo da Transação](/pt/api-reference/transactions/reason-enum) para os 60+ valores permitidos.

  **Exemplo**:

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

<ParamField body="locationDetails" type="object">
  Informações de localização geográfica onde a transação ocorreu. Útil para detecção de fraude, análise de risco geográfico e relatórios de conformidade.

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

  **Campos Suportados**:

  **Informações de Endereço**:

  * `country` (string) - Código de país ISO 3166-1 alpha-2 (ex: "US", "BR", "AR")
  * `countryName` (string) - Nome completo do país
  * `city` (string) - Nome da cidade
  * `region` (string) - Estado ou província
  * `address` (string) - Endereço completo
  * `street` (string) - Nome da rua
  * `streetNumber` (string) - Número da rua
  * `postalCode` (string) - Código postal/CEP
  * `neighborhood` (string) - Bairro ou distrito

  **Coordenadas** (para visualização em mapas):

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

  **Informações Adicionais**:

  * `timezone` (string) - Fuso horário IANA (ex: "America/Sao\_Paulo")
  * `placeId` (string) - ID do Google Places ou identificador similar

  **Exemplo**:

  ```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**:

  * **Detecção de Fraude**: Identificar transações de localizações incomuns ou países de alto risco
  * **Análise Geográfica**: Analisar padrões de transações por região
  * **Conformidade**: Rastrear transações transfronteiriças para relatórios regulatórios
  * **Regras de Velocidade**: Detectar viagens impossíveis (mesmo usuário em diferentes localizações em pouco tempo)
</ParamField>

<ParamField body="deviceDetails" type="object">
  Informações do dispositivo para a transação. Crítico para detecção de fraude, fingerprinting de dispositivos e análise de segurança.

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

  **Campos Suportados**:

  **Identificação do Dispositivo**:

  * `deviceId` (string) - Identificador único do dispositivo
  * `externalId` (string) - Seu ID externo do dispositivo

  **Plataforma e Sistema Operacional**:

  * `platform` (enum) - Plataforma do dispositivo: `android`, `ios`, `web`, `desktop`, `mobile`, `tablet`, `pos`, `atm`
  * `osName` (string) - Nome do sistema operacional (ex: "Android", "iOS", "Windows", "macOS")
  * `osVersion` (string) - Versão do SO (ex: "13.0", "16.4")

  **Informações do Dispositivo**:

  * `manufacturer` (string) - Fabricante do dispositivo (ex: "Samsung", "Apple")
  * `model` (string) - Modelo do dispositivo (ex: "Galaxy S22", "iPhone 14")
  * `brand` (string) - Marca do dispositivo
  * `deviceName` (string) - Nome atribuído pelo usuário ao dispositivo

  **Informações do Navegador** (para plataforma web):

  * `browser` (string) - Nome do navegador (ex: "Chrome", "Safari", "Firefox")
  * `browserVersion` (string) - Versão do navegador
  * `userAgent` (string) - String completa do user agent

  **Flags de Segurança**:

  * `isEmulator` (boolean) - Se o dispositivo é um emulador
  * `isRooted` (boolean) - Se o dispositivo está com root (Android)
  * `isJailbroken` (boolean) - Se o dispositivo está com jailbreak (iOS)

  **Informações de Rede**:

  * `ipAddress` (string) - Endereço IP (formato validado)
  * `isVpn` (boolean) - Se a conexão é através de VPN
  * `isTor` (boolean) - Se a conexão é através de Tor
  * `isProxy` (boolean) - Se a conexão é através de proxy

  **Fingerprinting de Dispositivo**:

  * `deviceFingerprint` (string) - Hash único de impressão digital do dispositivo para rastreamento

  **Detalhes Adicionais**:

  * `screenResolution` (string) - Resolução da tela (ex: "1920x1080")
  * `language` (string) - Idioma do dispositivo
  * `timezone` (string) - Fuso horário do dispositivo

  **Exemplo**:

  ```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**:

  * **Detecção de Fraude**: Identificar dispositivos suspeitos (emuladores, dispositivos com root, uso de VPN)
  * **Fingerprinting de Dispositivo**: Rastrear dispositivos únicos através de transações para análise comportamental
  * **Análise de Segurança**: Detectar anomalias em padrões de dispositivos (novo dispositivo, velocidade de dispositivo impossível)
  * **Conformidade**: Documentar informações do dispositivo para rastros de auditoria
  * **Experiência do Usuário**: Personalizar experiência baseada em tipo e capacidades do dispositivo
</ParamField>

<ParamField body="description" type="string">
  Descrição da transação

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

<ParamField body="category" type="string">
  Categoria da transação para agrupamento

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

<ParamField body="metadata" type="object">
  Metadados personalizados para armazenar informações adicionais da transação.

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

  **Campos Padrão Suportados**:

  ### `tags` (object) - **Sistema de Categorização Chave-Valor**

  O campo `tags` permite adicionar pares chave-valor personalizados para categorização flexível, filtragem e gerenciamento de fluxos de trabalho. Isso é particularmente útil para:

  * Filtragem personalizada em dashboards e relatórios
  * Ativar lógica de negócio específica
  * Acompanhamento do status de revisão
  * Categorização por nível de risco ou fonte
  * Estados de fluxo de trabalho personalizados

  **Formato**: `{ "chave1": "valor1", "chave2": "valor2" }`

  **Padrões Comuns 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 (pendente de revisão), 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 campanha de marketing ou negócio
  * `approved_by` (string) - Usuário ou sistema que aprovou
  * `requires_approval` (boolean) - Requer aprovação 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"

  **Exemplos de Casos de Uso**:

  **Exemplo 1: Fluxo de trabalho baseado em risco**

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

  **Exemplo 2: Categorização de negócio**

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

  **Exemplo 3: Rastreamento multi-canal**

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

  **Exemplo 4: Operações bancárias**

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

  **Filtrar transações por tags**: Posteriormente você pode filtrar transações usando essas tags em endpoints de listagem ou dashboards.

  ### Outros Campos de Metadata:

  * `purpose` (string) - Propósito da transação (ex: "salary", "invoice\_payment")
  * `frequency` (string) - Frequência da transação (ex: "monthly", "one-time")
  * `contract_number` (string) - Número de contrato (para pagamentos empresariais)
  * `enhanced_due_diligence` (boolean) - Flag de EDD
  * `block_reason` (string) - Razão do bloqueio
  * `compliance_alert` (boolean) - Flag de alerta de compliance

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

  Campos personalizados além dos padrão são permitidos e serão preservados.
</ParamField>

<ParamField body="transactedAt" type="string">
  Quando a transação ocorreu (timestamp ISO 8601). Padrão para o horário atual se não for fornecido.

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

<ParamField body="executeRules" type="boolean" default="true">
  Se deve executar regras de risco automaticamente após criar a transação

  **Tipo**: `boolean` (padrão: true)
</ParamField>

#### Métodos de Pagamento

* `CARD` - Pagamento com cartão de crédito/débito
* `ACH` - Transferência ACH (EUA)
* `PIX` - Pagamento instantâneo brasileiro
* `TED` - Transferência bancária brasileira (TED)
* `BOLETO` - Pagamento com boleto brasileiro
* `WALLET` - Pagamento com carteira digital
* `SWIFT` - Transferência internacional SWIFT
* `IBAN` - Transferência baseada em IBAN
* `CBU` - Conta bancária argentina (CBU)
* `CVU` - Carteira virtual argentina (CVU)
* `DEBIN` - Débito direto argentino
* `GENERIC_BANK_ACCOUNT` - Transferência bancária genérica
* `MPESA` - Dinheiro móvel M-Pesa
* `UPI` - Pagamento UPI da Índia
* `CHECK` - Cheque físico
* `ECHECK` - Cheque eletrônico
* `QR_CODE` - Pagamento com código QR
* `ONLINE_PAYMENT` - Pagamento online genérico
* `WITHDRAWAL_ORDER` - Ordem de saque

#### Tipos de Conta

* `PERSONAL` - Conta pessoal
* `BUSINESS` - Conta empresarial
* `MERCHANT` - Conta de comerciante
* `SAVINGS` - Conta poupança
* `CHECKING` - Conta corrente
* `INVESTMENT` - Conta de investimento
* `ESCROW` - Conta escrow
* `PREPAID` - Conta pré-paga
* `OTHER` - Outro tipo de conta

### Códigos MCC

Merchant Category Codes (MCC) classificam tipos de negócios:

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

Exemplos comuns:

* `5411` - Supermercados
* `5812` - Restaurantes
* `5999` - Varejo Diversos
* `6011` - Caixa Eletrônico/Saque
* `7995` - Jogos de Azar

### Tags e Metadata

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

### Suporte Multi-Moeda

O gu1 oferece conversão automática de moeda para todas as transações. Cada organização tem uma **moeda base** configurada (padrão: USD), e todas as transações são automaticamente convertidas para esta moeda base para avaliação consistente de regras e relatórios.

#### Como Funciona

1. **Detecção Automática**: Quando a `currency` de uma transação difere da moeda base da sua organização, a conversão automática é acionada
2. **Taxas em Tempo Real**: Taxas de câmbio são obtidas do nosso serviço de moeda em tempo real
3. **Armazenamento de Valor Duplo**: Ambos os valores original e convertido são armazenados
4. **Avaliação de Regras**: Regras podem usar tanto `amount` (original) quanto `amountInUsd` (convertido em USD)

#### Moedas Suportadas

Mais de 150 moedas suportadas incluindo:

* **Principais**: USD, EUR, GBP, JPY, CHF, CAD, AUD
* **América Latina**: BRL, ARS, MXN, COP, CLP, PEN, UYU
* **Ásia**: CNY, INR, KRW, SGD, HKD, THB, MYR
* **Cripto**: BTC, ETH, USDT, USDC
* **E muitas mais** (padrão ISO 4217)

#### Fontes de Taxa de Câmbio

| Fonte             | Descrição                                    | Quando Usado      |
| ----------------- | -------------------------------------------- | ----------------- |
| `ms-provider`     | Taxas em tempo real do microserviço de moeda | Fonte primária    |
| `cache-fallback`  | Taxas em cache quando serviço indisponível   | Fallback (\< 1h)  |
| `no-conversion`   | Conversão não necessária (mesma moeda)       | Igual à base      |
| `client-provided` | Taxa personalizada fornecida pelo cliente    | Override opcional |

#### Campos de resposta

Os dados de conversão vêm no objeto **transaction**, não em um bloco separado:

* `transaction.amount`, `transaction.currency` – valor e moeda originais
* `transaction.amountInUsd` – valor convertido em USD (null se a conversão falhar ou não se aplicar)
* `transaction.exchangeRate`, `transaction.rateSource` – taxa usada e fonte (ex.: `ms-provider`)

#### Usando Valores Convertidos em Regras

Regras podem referenciar ambos os valores:

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

Ou use o valor convertido para limites consistentes:

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

**Melhor Prática**: Use `amountInUsd` em regras para garantir limites consistentes independentemente da moeda da transação.

#### Tratamento de Erros

Se a conversão de moeda falhar:

* O processamento da transação continua com o valor original
* `transaction.amountInUsd` e `transaction.exchangeRate` serão null
* Regras usando `amountInUsd` usarão o `amount` original como fallback se a conversão falhar
* O erro é registrado mas não bloqueia a transação

#### Exemplo: Transação Multi-Moeda

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

**Resposta** (a conversão fica no transaction):

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

## Exemplos Completos de Requisição

### Transferência PIX (Brasil)

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

### Pagamento com Cartão

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

### Transferência Multi-Moeda

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

## Resposta

Especificação completa: [Criar transação](/pt/api-reference/transactions/create). A API retorna **`transaction` como objeto** (transação criada).

### Resposta de Sucesso (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": [
      {
        "factor": "velocity_check",
        "score": 15,
        "description": "3 transactions in the last hour"
      }
    ],
    "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
  }
}
```

### Campos de Resposta

<ResponseField name="transaction" type="object">
  A transação criada com todos os seus dados incluindo:

  * **id** (string) - UUID interno do gu1
  * **externalId** (string) - Seu ID externo
  * **type** (enum) - Tipo de transação
  * **status** (enum) - Status da transação
  * **amount** (string) - Valor original (string numérica)
  * **currency** (string) - Código de moeda original (ISO 4217)
  * **amountInUsd** (string | null) - Valor convertido em USD
  * **exchangeRate** (string | null) - Taxa de câmbio usada (precisão: 10 decimais)
  * **rateSource** (string | null) - Fonte da taxa de câmbio
  * **riskScore** (string | null) - Pontuação de risco 0-100 (precisão: 2 decimais) se regras foram executadas
  * **riskFactors** (array) - Array de fatores de risco identificados
  * **flagged** (boolean) - Se a transação foi sinalizada para revisão
  * **reason** (string | null) - Motivo opcional do resultado (ex.: WITHOUT\_REASON, INSUFFICIENT\_FUNDS); padrão WITHOUT\_REASON quando omitido
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  **Na raiz da resposta.** **Presente apenas quando executeRules é true e o motor de regras foi executado.** Resumo de quais regras deram match (hit) e quais não (no hit), ações executadas e pontuação total. Omitido quando `executeRules` é `false`. Estrutura completa e exemplo: [Resumo de Execução de Regras](/pt/api-reference/rules-execution-summary).

  * **rulesHit** (array) - Regras cujas condições foram atendidas. Cada item: **name**, **description**, **score**, **priority**, **category**, **status** (ex. `active`, `shadow`), **conditions** (array de `{ field, value, operator? }`), **actions** (alerts, suggestion, status, assignedUser).
  * **rulesNoHit** (array) - Regras avaliadas cujas condições não foram atendidas. Mesma estrutura que rulesHit (inclui ações configuradas, não executadas).
  * **actionsExecuted** (object) - Ações executadas agregadas de todas as regras que deram hit: **alerts** (array de `{ name?, type?, severity?, description? }`), **suggestion** (`BLOCK` | `SUSPEND` | `FLAG`, maior peso), **status** (status da entidade aplicado, se houver), **assignedUser** (`{ userId }`, se houver), **customKeys** (array de strings, opcional) — chaves de ações personalizadas das regras que deram match (ex. `require_kyc`, `flag_for_review`). Presente quando alguma regra que deu match tem uma ação personalizada com chave; para integrações/workflows.
  * **totalScore** (number) - Soma do **score** de todas as regras que deram hit e **não** estão em status `shadow`.
</ResponseField>

### Valores de Status da Transação

O status da transação segue um modelo de máquina de estados com estados abertos e fechados:

#### Estados Abertos (Podem Transitar)

| Status       | Descrição                          | Pode Transitar Para                                        |
| ------------ | ---------------------------------- | ---------------------------------------------------------- |
| `CREATED`    | Transação criada (estado inicial)  | PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, SUCCESSFUL |
| `PROCESSING` | Transação em processamento         | SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL   |
| `SUSPENDED`  | Transação temporariamente suspensa | PROCESSING, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL  |

#### Estados Fechados (Finais)

| Status       | Descrição                       | Nota                               |
| ------------ | ------------------------------- | ---------------------------------- |
| `SENT`       | Transação enviada/transmitida   | Estado final - sem mais transições |
| `EXPIRED`    | Transação expirada              | Estado final - sem mais transições |
| `DECLINED`   | Transação recusada/declinada    | Estado final - sem mais transições |
| `REFUNDED`   | Transação reembolsada/revertida | Estado final - sem mais transições |
| `SUCCESSFUL` | Transação concluída com sucesso | Estado final - sem mais transições |

**Importante**: Uma vez que uma transação atinge um estado fechado, não pode transitar de volta para um estado aberto. Isso garante a integridade da transação e trilhas de auditoria adequadas.

### Faixas de Pontuação de Risco

Pontuação de risco de 0 a 100 (armazenada com 2 decimais de precisão):

* **0-30**: Risco baixo (verde)
* **31-60**: Risco médio (amarelo)
* **61-80**: Risco alto (laranja)
* **81-100**: Risco crítico (vermelho)

### Fontes de Taxa de Conversão de Moeda

O campo `rateSource` indica como a taxa de câmbio foi obtida:

* **ms-provider**: Taxa em tempo real do microserviço de moeda (fonte primária)
* **cache-fallback**: Taxa em cache (\< 1h) quando serviço indisponível
* **no-conversion**: Conversão não necessária (moeda já é USD)
* **null**: Conversão falhou ou não é aplicável

## Respostas de Erro

### 400 Bad Request - Erro de Validação

**Exemplo 1: Campos obrigatórios faltando**

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

**Exemplo 2: paymentDetails inválidos para cartão (aninhado em 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"
    }
  ]
}
```

**Exemplo 3: Detalhes PIX inválidos (aninhado em 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"
    }
  ]
}
```

**Exemplo 4: Endereço IP inválido em 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 - Organização Faltando

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

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Configuração de Regras" icon="sliders" href="/pt/use-cases/transaction-monitoring/rules-configuration">
    Aprenda a criar regras
  </Card>

  <Card title="Detecção de Fraude" icon="shield" href="/pt/use-cases/transaction-monitoring/fraud-detection">
    Exemplos de detecção de fraude
  </Card>

  <Card title="Monitoramento AML" icon="building-columns" href="/pt/use-cases/transaction-monitoring/aml-monitoring">
    Regras de conformidade AML
  </Card>

  <Card title="Visão Geral" icon="book" href="/pt/use-cases/transaction-monitoring/overview">
    Voltar para visão geral
  </Card>
</CardGroup>