Criar transação
Referência API
Criar transação
Criar uma nova transação financeira para monitoramento e análise — na API de monitoramento de transações gu1 para fraude e AML, com exemplos para create.
POST
Criar transação
Visão geral
Cria uma nova transação. ComexecuteRules: true (padrão), o motor de regras roda de forma síncrona e a resposta inclui rulesExecutionSummary completo quando as regras terminam na mesma request.
Sem enviar asyncRules (padrão false), o comportamento permanece o mesmo — integrações existentes não mudam.
Endpoint
Autenticação
Requer uma API key válida no header Authorization:Parâmetros de query
Com
true e executeRules diferente de false, a transação é criada na hora e a avaliação de regras é enfileirada em background. A resposta HTTP retorna antes das regras terminarem. O query param tem precedência sobre o mesmo campo no body JSON.Valores truthy aceitos: true, 1, "true", "1", "yes".Não se aplica a endpoints batch — apenas POST /transactions (criação unitária).Corpo da requisição
Campos obrigatórios
Seu identificador único para esta transação no seu sistema
Tipo da transação. Opções:
PAYMENT- PagamentoTRANSFER- TransferênciaWITHDRAWAL- SaqueDEPOSIT- DepósitoREFUND- ReembolsoCHARGEBACK- ChargebackREVERSAL- EstornoFEE- TaxaADJUSTMENT- AjusteOTHER- Outro
Valor (deve ser zero ou positivo)
Código da moeda (3-4 caracteres, ex.: “USD”, “EUR”, “BRL”)
Taxa de câmbio opcional, usada somente quando a conversão automática para a moeda base da organização não está disponível (erro do provedor, timeout ou par não suportado). Se omitir este campo, o comportamento permanece o mesmo — o Gueno consulta o serviço de moedas como hoje.Semântica: unidades da moeda base por 1 unidade de
currency. Valor normalizado na moeda base da org: valorNormalizado = amount × exchangeRate.Ignorada quando a conversão automática tem sucesso (prevalece a taxa do provedor).Necessária quando a conversão automática não está disponível para moedas não conversíveis (ver abaixo). Ver Conversão de moeda.Campos opcionais
Status. Opções:
CREATED, PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFULMétodo de pagamento. Opções:
CARD, ACH, PIX, TED, BOLETO, WALLET, SWIFT, IBAN, CBU, CVU, DEBIN, etc.Descrição ou notas
Categoria da transação
Data/hora ISO 8601 do fato (padrão: momento da criação). Gravado em UTC. Use
Z ou offset ±HH:MM no string, ou datetime sem offset junto com timeZone (horário local nesse fuso).Se o motor de regras deve rodar. Com
false, pula regras por completo (sync e async).Mesma semântica do query
asyncRules. Para ingestão em alto volume: persistir a transação rápido e revisar alertas depois no gu1. Requer executeRules: true (padrão). Ignorado se executeRules for false.Ajuste opcional da execução de regras após a criação (sync ou async). Não desativa ações
Com
createAlert nem a consolidação de investigações.| Campo | Tipo | Padrão |
|---|---|---|
notifications | boolean | true na maioria das organizações; false na Paytime prod (3bc1f621-27d4-423e-9d64-86680bec2388) quando omitido |
notifications: false, o gu1 não envia notificações in-app da avaliação de regras (matriz de risco / mudanças de status). Alertas e investigações seguem o fluxo normal.Legacy KYT POST /legacy/kyt/verifyTransaction: mesmo objeto no body Gu2 como configRulesExecution; se omitido, Paytime prod recebe notifications: false por padrão (igual a POST /transactions).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)
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.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):
Se a entidade não tem
(
- ID da entidade — com
originEntityId, a transação usa essa entidade (deve existir na org). - ID externo — sem
originEntityId, comoriginExternalId, se houver pessoa/empresa com o mesmoexternalId, a transação vincula automaticamente. - Terceiro fallback: documento / tax ID (raiz) — ainda sem vínculo, com
originTaxIdno raiz do corpo, o API procura pessoa/empresa cujotaxIdcoincida após normalizar (apenas letras e números, ignorando pontuação; comparação em maiúsculas no match).
originEntityId e, se você não enviou, pode preencher name e country a partir da entidade.Denormalização canônica (origem vinculada): quando a origem está vinculada a pessoa/empresa — você enviou originEntityId, ou o auto-link resolveu por originExternalId / originTaxId — o gu1 sincroniza as colunas denormalizadas a partir da entidade antes do insert:| Campo na transação | Origem na entidade | Valor do cliente é mantido? |
|---|---|---|
originEntityId | entities.id | Definido no auto-link; inalterado se você já enviou UUID válido |
originTaxId | entities.tax_id | Não — sempre sobrescrito pela entidade vinculada |
originExternalId | entities.external_id | Não — sempre sobrescrito pela entidade vinculada |
taxId ou externalId, a coluna correspondente na transação fica null, mesmo que você tenha enviado valores no body.Nota para integradores: você pode enviar qualquer combinação de identificadores para vincular (precedência: originEntityId → originExternalId → originTaxId). Após o vínculo, originTaxId / originExternalId persistidos refletem a entidade no gu1, não necessariamente o que digitou. Isso alinha regras transacionais com eventos de usuário.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.)UUID da entidade de origem no gu1
Seu ID externo da entidade de origem. Segundo critério de vínculo sem
originEntityId. Após vincular, o valor gravado é entities.external_id (valor do cliente não é mantido se diferir).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. Após vincular, gravado como entities.tax_id. Opcional, máx. 50 caracteres.Nome da origem
Código de país ISO 2 da origem (ex.: “US”, “BR”, “AR”)
Detalhes da origem (dispositivo, conta, etc.). Ver Schema de payment details. Campos extras permitidos. Se a origem não for uma entidade no gu1, envie identificadores em
originDetails.paymentDetails para agrupar nós pseudo (taxId, cbu, cvu, pixKey, clabe, alias, iban, holderId, debinId, cardFingerprint, accountNumber + bankCode opcional — ver prioridade no schema).Destino (entidade)
Vínculo do destino: mesma precedência da origem:
destinationEntityId → destinationExternalId → destinationTaxId.Com destino vinculado, o gu1 sempre sincroniza destinationTaxId e destinationExternalId a partir da entidade (mesmas regras da origem). Sem vínculo, mantém os valores enviados.UUID da entidade de destino no gu1
Seu ID externo da entidade de destino. Após vincular, gravado como
entities.external_id.Tax / documento do destino no raiz; terceiro fallback depois de
destinationEntityId e destinationExternalId. Mesma regra de originTaxId. Após vincular, gravado como entities.tax_id. Opcional, máx. 50 caracteres.Nome do destino
Código de país ISO 2 do destino
Detalhes do destino (comerciante, conta, etc.). Campos opcionais; extras permitidos. Se o destino não for uma entidade no gu1, envie os mesmos identificadores em
destinationDetails.paymentDetails para agrupar nós pseudo (mesma prioridade que origem — ver Payment Details Schema).Localização e dispositivo
Localização:
country, city, region, address, latitude, longitude, postalCode, etc.Dispositivo:
deviceId, platform, osName, model, ipAddress, isVpn, isTor, etc.Canal (máx. 50 caracteres):
mobile_app, web_browser, pos_terminal, api, atm, etc.Motivo do resultado (opcional). Ver Enum de motivos. Se omitido, usa
WITHOUT_REASON.Fuso horário IANA opcional (independente de
operationalHours da entidade). Valores de transaction_time_zone. Se omitido, fica null.Normalização de transactedAt: se transactedAt tiver Z (como exige o validador deste endpoint), esse instante é gravado em UTC; timeZone é metadata opcional e não entra no parse. Com datetime local + timeZone (ferramentas internas/lote), a API pode converter horário local para UTC. Integrações que não enviam timeZone continuam como antes. Regras de horário operacional usam o instante gravado + operationalHours.timezone da entidade, não transaction.timeZone.Lista completa: Enum fuso horário.Metadados adicionais:
tags, purpose, enhanced_due_diligence, block_reason, compliance_alert, etc.Resposta
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.Presente quando executeRules é true.Síncrono (padrão): completo após as regras terminarem na mesma request.Async (
asyncRules=true): placeholder com success: true, rulesHit / rulesNoHit vazios e matchedRulesCount: 0. Alertas e score atualizam quando o processamento em background termina.Omitido se executeRules for false. Ver Resumo de Execução de Regras.Presente e
true apenas quando as regras foram enfileiradas. Omitido no fluxo síncrono padrão.No modo async:
"queued". Omitido quando as regras rodaram de forma síncrona.Exemplo básico
Regras async (ingestão em alto volume)
Para respostas rápidas e revisar alertas depois no gu1. As regras rodam em background;rulesExecutionSummary.rulesHit vem vazio na resposta HTTP.
Conversão de moeda
Quandocurrency difere da moeda base da organização (padrão USD), o Gueno busca a taxa automaticamente. O comportamento não muda se você omitir exchangeRate.
Ordem de resolução
| Etapa | Condição | Resultado |
|---|---|---|
| 1 | currency igual à base | rateSource: no-conversion, exchangeRate: 1 |
| 2 | Conversão automática com sucesso | Taxa do provedor (ms-provider, cache, etc.) |
| 3 | Conversão falha e você enviou exchangeRate | rateSource: client-provided |
| 4 | Conversão falha, sem exchangeRate | rateSource: conversion-unavailable; sem valor normalizado na moeda base |
Semântica de exchangeRate
- Direção: unidades da moeda base por 1 unidade de
currency(igual às taxas do provedor). - Fórmula:
valorNormalizado = amount × exchangeRate(persistido na moeda base da org). - Não é override: se a etapa 2 tiver sucesso,
exchangeRatedo cliente é ignorado.
Moedas não conversíveis (conversão automática)
O Gueno não obtém taxa de câmbio automática para estes códigos hoje. A conversão automática fica unavailable salvo se você enviarexchangeRate:
| Moeda | Código | Notas |
|---|---|---|
| Worldcoin | WLD | O cliente deve enviar exchangeRate para valor normalizado na base |
| Ethereum | ETH | O cliente deve enviar exchangeRate para valor normalizado na base |
transactedAt).
Envie exchangeRate se precisar de valor normalizado na base para regras e relatórios.
Exemplo — WLD com taxa do cliente
63.05, rateSource: client-provided):
O batch (
POST /transactions/batch, upload, JSON) aceita o mesmo exchangeRate opcional em cada linha, com a mesma semântica.Com Redis configurado, os jobs vão para a fila
transaction-rules-eval (workers dedicados se DISABLE_INPROCESS_BULL_WORKERS=true). Se Redis não existir ou o enqueue falhar, a API ainda responde 200 com asyncRules: true e executa as regras no processo dessa instância (adequado para dev ou instância única; alto volume multi-instância: Redis + workers).Exemplo de resposta
Erros
400 - Dados inválidos
409 - Transação duplicada
429 - Limite de taxa
Próximos passos
- Obter transação - Por ID ou external ID
- Criar transações em lote - Carga em massa
- Alterar status da transação - Alterar status
- Monitoramento de transações - Detecção de fraude