Skip to main content
POST
http://api.gu1.ai
/
transactions
Criar transação
curl --request POST \
  --url http://api.gu1.ai/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "<string>",
  "type": "<string>",
  "amount": 123,
  "currency": "<string>",
  "status": "<string>",
  "paymentMethod": "<string>",
  "description": "<string>",
  "category": "<string>",
  "transactedAt": "<string>",
  "executeRules": true,
  "originEntityId": "<string>",
  "originExternalId": "<string>",
  "originName": "<string>",
  "originCountry": "<string>",
  "originDetails": {},
  "destinationEntityId": "<string>",
  "destinationExternalId": "<string>",
  "destinationName": "<string>",
  "destinationCountry": "<string>",
  "destinationDetails": {},
  "locationDetails": {},
  "deviceDetails": {},
  "channel": "<string>",
  "reason": "<string>",
  "metadata": {}
}
'
{
  "transaction": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Visão geral

Cria uma nova transação. Com executeRules: true (padrão), o motor de regras é executado e a resposta inclui rulesResult e rulesExecutionSummary.

​
Endpoint

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

​
Autenticação

Requer uma API key válida no header Authorization: 
Authorization: Bearer YOUR_API_KEY

​
Corpo da requisição

​
Campos obrigatórios

​
externalId
string
required
Seu identificador único para esta transação no seu sistema
​
type
string
required
Tipo da transação. Opções:
  • PAYMENT - Pagamento
  • TRANSFER - Transferência
  • WITHDRAWAL - Saque
  • DEPOSIT - Depósito
  • REFUND - Reembolso
  • CHARGEBACK - Chargeback
  • REVERSAL - Estorno
  • FEE - Taxa
  • ADJUSTMENT - Ajuste
  • OTHER - Outro
​
amount
number
required
Valor (deve ser zero ou positivo)
​
currency
string
required
Código da moeda (3-4 caracteres, ex.: “USD”, “EUR”, “BRL”)

​
Campos opcionais

​
status
string
default:"CREATED"
Status. Opções: CREATED, PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL
​
paymentMethod
string
Método de pagamento. Opções: CARD, ACH, PIX, TED, BOLETO, WALLET, SWIFT, IBAN, CBU, CVU, DEBIN, etc.
​
description
string
Descrição ou notas
​
category
string
Categoria da transação
​
transactedAt
string
Data/hora ISO 8601 do fato (padrão: momento da criação)
​
executeRules
boolean
default:"true"
Se o motor de regras deve ser executado para esta transação

​
Origem (entidade)

​
originEntityId
string
UUID da entidade de origem no gu1
​
originExternalId
string
Seu ID externo da entidade de origem
​
originName
string
Nome da origem
​
originCountry
string
Código de país ISO 2 da origem (ex.: “US”, “BR”, “AR”)
​
originDetails
object
Detalhes da origem (dispositivo, conta, etc.). Ver Schema de payment details. Campos extras permitidos. Se a origem não for uma entidade no gu1, pode enviar opcionalmente taxId e/ou accountNumber em originDetails ou originDetails.paymentDetails para melhorar a visualização em grafos de rede (nós “pseudo” agrupados pelo mesmo identificador).

​
Destino (entidade)

​
destinationEntityId
string
UUID da entidade de destino no gu1
​
destinationExternalId
string
Seu ID externo da entidade de destino
​
destinationName
string
Nome do destino
​
destinationCountry
string
Código de país ISO 2 do destino
​
destinationDetails
object
Detalhes do destino (comerciante, conta, etc.). Campos opcionais; extras permitidos. Se o destino não for uma entidade no gu1, pode enviar opcionalmente taxId e/ou accountNumber em destinationDetails ou destinationDetails.paymentDetails para melhorar a visualização em grafos de rede (nós “pseudo” agrupados).

​
Localização e dispositivo

​
locationDetails
object
Localização: country, city, region, address, latitude, longitude, postalCode, etc.
​
deviceDetails
object
Dispositivo: deviceId, platform, osName, model, ipAddress, isVpn, isTor, etc.
​
channel
string
Canal (máx. 50 caracteres): mobile_app, web_browser, pos_terminal, api, atm, etc.
​
reason
string
Motivo do resultado (opcional). Ver Enum de motivos. Se omitido, usa WITHOUT_REASON.
​
metadata
object
Metadados adicionais: tags, purpose, enhanced_due_diligence, block_reason, compliance_alert, etc.

​
Resposta

​
transaction
object
A transação criada (objeto). Inclui: id, externalId, organizationId, type, amount (string), currency, status, riskScore (string), flagged, channel, reason, originDetails, destinationDetails, locationDetails, deviceDetails, processingTimeMs, processedAt, transactedAt, createdAt, updatedAt.
​
rulesResult
object
Apenas se executeRules foi true. Resultado da execução das regras: success, executed, result (opcional), rulesExecutionSummary, rulesTriggered, executionTimeMs, auditId (opcional), isNewAudit (opcional).
​
rulesExecutionSummary
object
Apenas quando o motor de regras rodou. Mesmo que rulesResult.rulesExecutionSummary. Inclui rulesHit, rulesNoHit, actionsExecuted (opcional), totalScore, scoreResult, riskMatrixName, executionTimeMs, trigger, matchedRulesCount. Ver Resumo de Execução de Regras para a estrutura completa e um exemplo com todos os campos.

​
Exemplo básico

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "amount": 150.50,
    "currency": "USD",
    "originExternalId": "customer_001",
    "destinationExternalId": "merchant_456",
    "description": "Compra online"
  }'

​
Exemplo de resposta

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_67890",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": "1000.00",
    "currency": "BRL",
    "amountInUsd": "1000.00",
    "paymentMethod": "PIX",
    "riskScore": "15",
    "flagged": false,
    "channel": "mobile_app",
    "reason": "WITHOUT_REASON",
    "originDetails": {},
    "destinationDetails": {},
    "processingTimeMs": "120",
    "processedAt": "2024-10-03T14:30:00.000Z",
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 1,
    "executionTimeMs": 162,
    "auditId": "52fa709f-88fe-473a-bc58-6efb5b0307f4",
    "isNewAudit": true,
    "rulesExecutionSummary": {
      "rulesHit": [],
      "rulesNoHit": [],
      "actionsExecuted": {},
      "totalScore": 15
    }
  },
  "rulesExecutionSummary": {
    "rulesHit": [],
    "rulesNoHit": [],
    "actionsExecuted": {},
    "totalScore": 15
  }
}

​
Erros

​
400 - Dados inválidos

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": ["Amount must be zero or a positive number", "Currency must be at least 3 characters"]
  }
}

​
409 - Transação duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TRANSACTION",
    "message": "Transaction with this external_id already exists",
    "details": { "field": "external_id", "value": "txn_12345" }
  }
}

​
429 - Limite de taxa

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 3600
}

​
Próximos passos