Skip to main content
POST
/
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,
  "validateExistingEntity": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "originEntityId": "<string>",
  "originExternalId": "<string>",
  "originTaxId": "<string>",
  "originName": "<string>",
  "originCountry": "<string>",
  "originDetails": {},
  "destinationEntityId": "<string>",
  "destinationExternalId": "<string>",
  "destinationTaxId": "<string>",
  "destinationName": "<string>",
  "destinationCountry": "<string>",
  "destinationDetails": {},
  "locationDetails": {},
  "deviceDetails": {},
  "channel": "<string>",
  "reason": "<string>",
  "timeZone": "<string>",
  "metadata": {}
}
'
{
  "transaction": {},
  "rulesExecutionSummary": {}
}

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.

​
Visão geral

Cria uma nova transação. Com executeRules: true (padrão), o motor de regras é executado e a resposta inclui rulesExecutionSummary na raiz quando as regras são executadas.

​
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
​
validateExistingEntity
boolean
default:"false"
Com false (padrão): se você enviar originExternalId / destinationExternalId (ou tax na raiz) e não houver entidade, a transação ainda é criada (sem vínculo), como antes.Com true: cada lado (origem / destino) só é validado se você enviar pelo menos um identificador daquele lado (originEntityId, originExternalId ou originTaxId; o mesmo para destino). Cada campo enviado deve resolver para uma pessoa/empresa existente na organização; caso contrário a API retorna 400 com INVALID_ENTITY_REFERENCES e não cria a transação. Se não enviar identificadores de origem (ou destino), esse lado não é validado.

​
Matrizes de risco (opcional)

​
riskMatrixId
string | string[]
Compatível com clientes antigos: um UUID ou um array de UUIDs de matrizes da organização. Se enviar lista não vazia, apenas regras ativas ligadas a essas matrizes são avaliadas (sem misturar com regras “soltas” só por triggers). Omita riskMatrixId e riskMatrixIds para manter o comportamento histórico por triggers.
​
riskMatrixIds
string[]
Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre riskMatrixId quando informado e não vazio.

​
Origem (entidade)

Como a origem é vinculada no gu1 (em ordem; para no primeiro sucesso):
  1. ID da entidade — com originEntityId, a transação usa essa entidade (deve existir na org).
  2. ID externo — sem originEntityId, com originExternalId, se houver pessoa/empresa com o mesmo externalId, a transação vincula automaticamente.
  3. Terceiro fallback: documento / tax ID (raiz) — ainda sem vínculo, com originTaxId no raiz do corpo, o API procura pessoa/empresa cujo taxId coincida após normalizar (apenas letras e números, ignorando pontuação; comparação em maiúsculas no match).
Nos passos 2 e 3, o API preenche originEntityId e, se você não enviou, pode preencher name e country a partir da entidade.Sem match, a transação é criada mesmo assim, com os campos enviados, sem vínculo.
(originDetails.taxId ajuda no grafo mas não vincula entidade; use originTaxId na raiz para vincular por documento.)
​
originEntityId
string
UUID da entidade de origem no gu1
​
originExternalId
string
Seu ID externo da entidade de origem
​
originTaxId
string
CPF/CNPJ ou outro tax ID de origem no raiz da requisição. Terceiro critério após originEntityId e originExternalId. Comparação com entity.taxId de forma normalizada. Se achar, preenche vínculo, nome e país. Opcional, máx. 50 caracteres.
​
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
​
destinationTaxId
string
Tax / documento do destino no raiz; terceiro fallback depois de destinationEntityId e destinationExternalId. Mesma regra de originTaxId. Opcional, máx. 50 caracteres.
​
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.
​
timeZone
string
Fuso horário IANA opcional (contexto local da transação, ex. com transactedAt). Valores de transaction_time_zone. Se omitido, fica null.Lista completa: Enum fuso horário.
​
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, timeZone (string | null), originDetails, destinationDetails, locationDetails, deviceDetails, processingTimeMs, processedAt, transactedAt, createdAt, updatedAt.
​
rulesExecutionSummary
object
Apenas quando executeRules é true e o motor de regras rodou. Omitido quando executeRules é false. 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"
  },
  "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