Skip to main content
GET
/
transactions
/
{id}
Obter transação
curl --request GET \
  --url http://api.gu1.ai/transactions/{id} \
  --header 'Authorization: Bearer <token>'
{
  "transaction": {},
  "persisted": {},
  "baseCurrency": "<string>"
}

​
Visão geral

Retorna uma transação da sua organização. A resposta usa objetos aninhados origin e destination (com dados de entidade resolvidos quando existem). Isso difere de Criar transação, em que o corpo usa originDetails / destinationDetails mais planos. Na leitura o motor de regras não é reexecutado. Por padrão a resposta não inclui rulesExecutionSummary. Envie includeRulesSummary=full para anexar o último resumo persistido ao objeto persisted (mesmo formato de Resumo de execução de regras).

​
Endpoints

MétodoEndpointQuando usar
Por IDGET /transactions/{id}Você tem o UUID da transação no gu1
Por external IDGET /transactions/external/{externalId}Você só tem o externalId usado na criação
Ambos retornam o mesmo formato: { "transaction": { ... }, "persisted": { ... }, "baseCurrency": "..." }.

​
Parâmetros de consulta

​
includeRulesSummary
string
Opcional. Se omitido, o comportamento permanece o mesmo (sem resumo de regras na leitura).
  • full — Carrega a linha mais recente de risk_analysis_audits desta transação e adiciona persisted.rulesExecutionSummary (rulesHit, rulesNoHit, actionsExecuted, scores, etc.). Não reexecuta regras. Indicado para detalhe de uma transação / debugging; omita em polling em volume.

​
Por ID

GET http://api.gu1.ai/transactions/{id}
​
id
string
required
UUID da transação no gu1 (o mesmo que transaction.id ao criar).

​
Por external ID

GET http://api.gu1.ai/transactions/external/{externalId}
​
externalId
string
required
O externalId enviado na criação da transação.

​
Autenticação

Exige API key válida e permissão de leitura de transações (transactions:read): 
Authorization: Bearer YOUR_API_KEY
A transação deve pertencer à organização da chave; caso contrário a API responde 404.

​
Resposta (200 OK)

​
transaction
object
Registro completo da transação.
  • id (string) — UUID no gu1
  • externalId (string) — seu identificador externo
  • type, status — enums (mesma semântica que em criar)
  • amount (number), currency (string)
  • amountInUsd (number | null)
  • currenciesExchange (array) — entradas { currency, exchangeRate, value }
  • paymentMethod (string | null)
  • origin (object) — entityId, externalId, name, country, type (person | company | null), taxId, riskScore, details (objeto; inclui o que você persistiu, ex. payment details)
  • destination (object) — mesma estrutura que origin
  • riskScore (number | null)
  • lastRiskEvaluationAt (string | null) — ISO da última auditoria de análise de risco (presente no GET por UUID; omitido ao buscar por external ID)
  • riskFactors (array)
  • activeMatchesCount, shadowMatchesCount (number, opcional)
  • hitRuleExternalIds (string[], opcional)
  • flagged (boolean)
  • locationDetails, deviceDetails (object)
  • channel (string | null), timeZone (string | null) — fuso IANA se enviado no create
  • description, category, metadata (object)
  • transactedAt, createdAt, updatedAt (ISO)
  • exchangeRate, rateSource, rateTimestamp, convertedAt — metadados de conversão quando aplicável
​
persisted
object
Snapshot plano em camelCase da linha em transactions (mesmos nomes que create / entrada do motor): valores, contrapartes, metadata, riskFactors, etc.Com includeRulesSummary=full, pode incluir também:
  • rulesExecutionSummary (object) — última execução persistida de regras desta transação (não é reavaliação ao vivo). Omitido se não houver auditoria ou se o query param não for enviado.
​
baseCurrency
string
Moeda base da organização (código ISO, ex. USD).

​
Exemplo (por ID, com resumo de regras)

curl -s 'http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000?includeRulesSummary=full' \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "transaction": { "...": "..." },
  "persisted": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "amount": 150.5,
    "currency": "USD",
    "riskFactors": {},
    "metadata": {},
    "rulesExecutionSummary": {
      "rulesHit": [],
      "rulesNoHit": [],
      "totalScore": 0,
      "actionsExecuted": {}
    }
  },
  "baseCurrency": "USD"
}

​
Exemplo (por ID, padrão)

curl -s http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "status": "CREATED",
    "amount": 150.5,
    "currency": "USD",
    "amountInUsd": 150.5,
    "currenciesExchange": [],
    "paymentMethod": "CARD",
    "origin": {
      "entityId": "…",
      "externalId": "customer_001",
      "name": "Jane Doe",
      "country": "US",
      "type": "person",
      "taxId": null,
      "riskScore": 12.5,
      "details": {}
    },
    "destination": {
      "entityId": "…",
      "externalId": "merchant_456",
      "name": "Acme Store",
      "country": "US",
      "type": "company",
      "taxId": null,
      "riskScore": 8,
      "details": {}
    },
    "riskScore": 15,
    "lastRiskEvaluationAt": "2025-01-15T10:00:00.000Z",
    "riskFactors": [],
    "flagged": false,
    "locationDetails": {},
    "deviceDetails": {},
    "channel": "web_browser",
    "description": "Compra online",
    "category": "retail",
    "metadata": {},
    "transactedAt": "2025-01-15T09:55:00.000Z",
    "createdAt": "2025-01-15T09:55:01.000Z",
    "updatedAt": "2025-01-15T09:55:01.000Z",
    "exchangeRate": null,
    "rateSource": null,
    "rateTimestamp": null,
    "convertedAt": null
  },
  "baseCurrency": "USD"
}

​
Erros

​
400 — Query inválido

{
  "error": "Invalid query parameters",
  "details": []
}
Quando includeRulesSummary não é full.

​
404 — Não encontrada

{
  "error": "Transaction not found"
}

​
500 — Erro no servidor

{
  "error": "Failed to fetch transaction",
  "details": "…"
}

​
Veja também