Referência da API

Endpoint

POST /transaction/analyze

Analisa uma transação financeira em tempo real, executando regras configuradas e retornando uma decisão junto com alertas e ações recomendadas.

Autenticação

Todas as requisições devem incluir uma chave de API no header Authorization:

Authorization: Bearer YOUR_API_KEY

Headers Obrigatórios

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Organization-ID: your-org-id

Corpo da Requisição

Núcleo da Transação

{
  "transaction": {
    "externalId": "string",        // Seu ID único de transação
    "type": "string",               // PAYMENT, TRANSFER, WITHDRAWAL, DEPOSIT, REFUND
    "amount": number,               // Valor da transação
    "currency": "string",           // Código de moeda ISO 4217 (USD, BRL, EUR, etc.)
    "timestamp": "string",          // Timestamp ISO 8601
    "originEntityId": "string",     // ID da entidade de origem (opcional)
    "destinationEntityId": "string", // ID da entidade de destino (opcional)
    "mccCode": "string",            // Código de Categoria do Comerciante (opcional)
    "description": "string",        // Descrição da transação (opcional)
    "tags": ["string"],             // Tags personalizadas (opcional)
    "metadata": {}                  // Metadados personalizados (opcional)
  }
}

Tipos de Transação

Tipo	Descrição
`PAYMENT`	Compra ou pagamento a comerciante
`TRANSFER`	Transferência entre contas/usuários
`WITHDRAWAL`	Saque em dinheiro ou débito de conta
`DEPOSIT`	Depósito ou crédito de conta
`REFUND`	Reembolso de uma 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

Referências de Entidades

{
  "originEntityId": "customer_maria_001",
  "destinationEntityId": "merchant_loja_002"
}

Entidades podem ser:

Pré-existentes na sua conta gu1
Criadas automaticamente durante a análise da transação
Referenciadas pelo seu ID externo

Detalhes do Pagamento

{
  "origin": {
    "paymentMethod": "CARD",
    "accountType": "PERSONAL",
    "accountId": "4532********1234",
    "bankCode": "001",
    "cardBrand": "VISA"
  },
  "destination": {
    "paymentMethod": "BANK_ACCOUNT",
    "accountType": "BUSINESS",
    "accountId": "1234567890",
    "bankCode": "033"
  }
}

Métodos de Pagamento

Cartões:

CARD - Cartão de crédito/débito (genérico)
CREDIT_CARD - Cartão de crédito
DEBIT_CARD - Cartão de débito
PREPAID_CARD - Cartão pré-pago

Transferências Bancárias:

BANK_TRANSFER - Transferência bancária genérica
WIRE - Transferência wire
ACH - Transferência ACH (US)
SEPA - Transferência SEPA (EU)

Carteiras Digitais:

WALLET - Carteira digital genérica
PAYPAL - PayPal
APPLE_PAY - Apple Pay
GOOGLE_PAY - Google Pay
SAMSUNG_PAY - Samsung Pay
VENMO - Venmo
ZELLE - Zelle

América Latina:

PIX - Pagamento instantâneo brasileiro
CBU - Conta bancária argentina
CVU - Carteira virtual argentina
DEBIN - Débito direto argentino
SPEI - Pagamento instantâneo mexicano
PSE - Pagamento online colombiano

Criptomoedas:

CRYPTO - Criptomoeda (genérica)
BITCOIN - Bitcoin
ETHEREUM - Ethereum
STABLECOIN - Stablecoins (USDT, USDC, etc.)

Dinheiro e Outros:

CASH - Pagamento em dinheiro
CHECK - Cheque
MONEY_ORDER - Ordem de pagamento
MOBILE_MONEY - Dinheiro móvel (M-Pesa, etc.)
OTHER - Outro método de pagamento

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 de depósito em garantia
PREPAID - Conta pré-paga
OTHER - Outro tipo de conta

Dados do Dispositivo

{
  "originDeviceData": {
    "deviceId": "device_android_001",
    "ipAddress": "177.20.145.30",
    "userAgent": "Mozilla/5.0...",
    "platform": "android",
    "location": {
      "latitude": -23.550520,
      "longitude": -46.633308,
      "country": "BR",
      "city": "São Paulo",
      "region": "SP"
    }
  }
}

Plataformas de Dispositivo

web - Navegador web
ios - App iOS
android - App Android
mobile_web - Navegador móvel
api - Chamada direta da API
other - Outra plataforma

Códigos MCC

Códigos de Categoria de Comerciante (MCC) classificam tipos de negócio:

{
  "mccCode": "5411"  // Supermercados
}

Exemplos comuns:

5411 - Supermercados
5812 - Restaurantes
5999 - Varejo Diversos
6011 - ATM/Saque em Dinheiro
7995 - Jogos de Azar

Tags e Metadados

{
  "tags": ["high_value", "first_transaction", "promotional"],
  "metadata": {
    "campaignId": "summer_2024",
    "referralCode": "FRIEND10",
    "customField": "any_value"
  }
}

Suporte Multi-Moeda

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

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
Taxas em Tempo Real: As taxas de câmbio são obtidas do nosso serviço de moedas em tempo real
Armazenamento de Valores Duplos: Tanto os valores originais quanto os convertidos são armazenados
Avaliação de Regras: As regras podem usar amount (original) ou amountBaseCurrency (convertido)

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 microsserviço de moedas	Fonte primária
`cache-fallback`	Taxas em cache quando o serviço está indisponível	Fallback (< 1h de idade)
`no-conversion`	Nenhuma conversão necessária (mesma moeda)	Igual à base
`client-provided`	Taxa personalizada fornecida pelo cliente	Substituição opcional

Campos de Resposta

Quando ocorre conversão de moeda, a resposta inclui:

{
  "currencyConversion": {
    "originalAmount": 500.00,
    "originalCurrency": "BRL",
    "convertedAmount": 100.00,
    "baseCurrency": "USD",
    "exchangeRate": 0.20,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T14:30:00Z"
  }
}

Usando Valores Convertidos em Regras

As regras podem referenciar ambos os valores:

{
  "conditions": [
    {
      "field": "amount",
      "operator": "GREATER_THAN",
      "value": 1000
    }
  ]
}

Ou usar o valor convertido para limites consistentes:

{
  "conditions": [
    {
      "field": "amountBaseCurrency",
      "operator": "GREATER_THAN",
      "value": 10000
    }
  ]
}

Melhor Prática: Use amountBaseCurrency nas 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
O campo currencyConversion será omitido da resposta
Regras usando amountBaseCurrency usarão o amount original como fallback
O erro é registrado mas não bloqueia a transação

Exemplo: Transação Multi-Moeda

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

A resposta inclui conversão:

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "APPROVE"
  },
  "currencyConversion": {
    "originalAmount": 850.00,
    "originalCurrency": "EUR",
    "convertedAmount": 935.00,
    "baseCurrency": "USD",
    "exchangeRate": 1.10,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T15:00:01Z"
  }
}

Exemplo de Requisição Completa

Transferência PIX (Brasil)

curl -X POST https://api.gu1.ai/transaction/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "transaction": {
      "externalId": "txn_pix_12345",
      "type": "TRANSFER",
      "amount": 500.00,
      "currency": "BRL",
      "timestamp": "2024-10-28T14:30:00Z",
      "originEntityId": "customer_maria_001",
      "destinationEntityId": "merchant_loja_002",
      "description": "Purchase at Online Store",
      "origin": {
        "paymentMethod": "PIX",
        "accountType": "PERSONAL",
        "accountId": "[email protected]"
      },
      "destination": {
        "paymentMethod": "PIX",
        "accountType": "BUSINESS",
        "accountId": "11222333000144"
      },
      "originDeviceData": {
        "deviceId": "device_android_001",
        "ipAddress": "177.20.145.30",
        "platform": "android",
        "location": {
          "latitude": -23.550520,
          "longitude": -46.633308,
          "country": "BR",
          "city": "São Paulo"
        }
      },
      "tags": ["pix", "retail"],
      "metadata": {
        "storeId": "store_002",
        "orderId": "order_789"
      }
    }
  }'

Pagamento com Cartão de Alto Risco

const response = await fetch('https://api.gu1.ai/transaction/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Organization-ID': 'your-org-id'
  },
  body: JSON.stringify({
    transaction: {
      externalId: 'txn_card_67890',
      type: 'PAYMENT',
      amount: 1250.00,
      currency: 'USD',
      timestamp: new Date().toISOString(),
      originEntityId: 'customer_john_003',
      destinationEntityId: 'merchant_electronics_001',
      mccCode: '5732', // Electronics Stores
      description: 'Laptop purchase',
      origin: {
        paymentMethod: 'CARD',
        accountType: 'PERSONAL',
        accountId: '4532********8765',
        cardBrand: 'VISA'
      },
      destination: {
        paymentMethod: 'BANK_ACCOUNT',
        accountType: 'BUSINESS',
        accountId: '9876543210'
      },
      originDeviceData: {
        deviceId: 'device_web_chrome_001',
        ipAddress: '185.220.101.45',
        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)...',
        platform: 'web',
        location: {
          latitude: 55.7558,
          longitude: 37.6173,
          country: 'RU',
          city: 'Moscow'
        }
      },
      tags: ['high_value', 'electronics'],
      metadata: {
        sessionId: 'sess_abc123',
        isFirstTransaction: true
      }
    }
  })
});

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

Exemplo em Python

import requests
from datetime import datetime

url = "https://api.gu1.ai/transaction/analyze"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "X-Organization-ID": "your-org-id"
}

payload = {
    "transaction": {
        "externalId": "txn_python_001",
        "type": "TRANSFER",
        "amount": 750.50,
        "currency": "EUR",
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "originEntityId": "user_alice_001",
        "destinationEntityId": "user_bob_002",
        "origin": {
            "paymentMethod": "SEPA",
            "accountType": "PERSONAL",
            "accountId": "ES1234567890123456789012"
        },
        "destination": {
            "paymentMethod": "SEPA",
            "accountType": "PERSONAL",
            "accountId": "DE89370400440532013000"
        },
        "originDeviceData": {
            "deviceId": "device_ios_001",
            "ipAddress": "89.145.123.45",
            "platform": "ios",
            "location": {
                "country": "ES",
                "city": "Madrid"
            }
        }
    }
}

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

print(f"Decision: {result['decision']}")
print(f"Risk Score: {result['riskScore']}")

Resposta

Resposta de Sucesso (200 OK)

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "APPROVE",
  "riskScore": 25,
  "alerts": [
    {
      "id": "alert_001",
      "severity": "low",
      "type": "velocity_check",
      "message": "User has 3 transactions in the last hour",
      "ruleId": "rule_velocity_001",
      "ruleName": "Transaction Velocity Monitor"
    }
  ],
  "actions": [
    {
      "type": "log_transaction",
      "priority": "normal"
    }
  ],
  "executionMetadata": {
    "syncRulesExecuted": 5,
    "asyncRulesExecuted": 12,
    "executionTimeMs": 234,
    "rulesMatched": 1
  },
  "currencyConversion": {
    "originalCurrency": "BRL",
    "baseCurrency": "USD",
    "originalAmount": 500.00,
    "convertedAmount": 100.00,
    "exchangeRate": 0.20,
    "conversionTimestamp": "2024-10-28T14:30:00Z"
  },
  "entitiesResolved": {
    "origin": {
      "id": "customer_maria_001",
      "type": "customer",
      "isNew": false
    },
    "destination": {
      "id": "merchant_loja_002",
      "type": "merchant",
      "isNew": false
    }
  }
}

Tipos de Decisão

Decisão	Descrição	Ação Recomendada
`APPROVE`	Transação aprovada	Processar normalmente
`REJECT`	Transação rejeitada	Bloquear transação
`HOLD`	Transação em espera	Revisão manual necessária
`REVIEW_REQUIRED`	Precisa de revisão	Colocar na fila para analista
`ADDITIONAL_AUTH_REQUIRED`	Precisa de mais verificação	Solicitar 2FA/3DS

Pontuação de Risco

Pontuação de risco de 0 a 100:

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

Níveis de Severidade de Alerta

low - Informativo, nenhuma ação imediata
medium - Monitorar, pode precisar de atenção
high - Requer revisão em horas
critical - Ação imediata necessária

Respostas de Erro

400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid transaction payload",
  "details": [
    {
      "field": "transaction.amount",
      "message": "Amount must be a positive number"
    },
    {
      "field": "transaction.currency",
      "message": "Currency must be a valid ISO 4217 code"
    }
  ]
}

401 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

429 Too Many Requests

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 60
}

500 Internal Server Error

{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred",
  "requestId": "req_abc123"
}

Limitação de Taxa

Plano Standard: 1.000 requisições por minuto
Plano Profissional: 5.000 requisições por minuto
Plano Enterprise: Limites personalizados

Headers de limitação de taxa:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1635780000

Idempotência

Use o header Idempotency-Key para prevenir processamento duplicado:

curl -X POST https://api.gu1.ai/transaction/analyze \
  -H "Idempotency-Key: txn_unique_key_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  ...

Chaves de idempotência são armazenadas por 24 horas.

Melhores Práticas

Sempre inclua dados do dispositivo - Melhora a precisão da detecção de fraude
Use IDs externos consistentemente - Permite resolução adequada de entidades
Inclua metadados relevantes - Útil para regras personalizadas e análise
Trate todos os tipos de decisão - Não verifique apenas APPROVE/REJECT
Implemente lógica de retry - Com backoff exponencial para falhas
Monitore limites de taxa - Acompanhe os headers e controle adequadamente
Use chaves de idempotência - Para transações críticas para prevenir duplicatas

Próximos Passos

Configuração de Regras

Aprenda a criar regras

Detecção de Fraudes

Exemplos de detecção de fraudes

Monitoramento AML

Regras de conformidade AML

Visão Geral

Voltar para visão geral

Começando

Referência API

Ingestão de Dados

Entidades

Conheça Seu Negócio (KYB)

Conheça Seu Cliente (KYC)

Monitoramento de Transações

Tutoriais Interativos

​Endpoint

​Autenticação

​Headers Obrigatórios

​Corpo da Requisição

​Núcleo da Transação

​Tipos de Transação

​Referências de Entidades

​Detalhes do Pagamento

​Métodos de Pagamento

​Tipos de Conta

​Dados do Dispositivo

​Plataformas de Dispositivo

​Códigos MCC

​Tags e Metadados

​Suporte Multi-Moeda

​Como Funciona

​Moedas Suportadas

​Fontes de Taxa de Câmbio

​Campos de Resposta

​Usando Valores Convertidos em Regras

​Tratamento de Erros

​Exemplo: Transação Multi-Moeda

​Exemplo de Requisição Completa

​Transferência PIX (Brasil)

​Pagamento com Cartão de Alto Risco

​Exemplo em Python

​Resposta

​Resposta de Sucesso (200 OK)

​Tipos de Decisão

​Pontuação de Risco

​Níveis de Severidade de Alerta

​Respostas de Erro

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Limitação de Taxa

​Idempotência

​Melhores Práticas

​Próximos Passos