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>",
"exchangeRate": 123,
"status": "<string>",
"paymentMethod": "<string>",
"description": "<string>",
"category": "<string>",
"transactedAt": "<string>",
"executeRules": true,
"asyncRules": true,
"configRulesExecution": {},
"linkEntityStrict": 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": {}
}
'import requests
url = "http://api.gu1.ai/transactions"
payload = {
"externalId": "<string>",
"type": "<string>",
"amount": 123,
"currency": "<string>",
"exchangeRate": 123,
"status": "<string>",
"paymentMethod": "<string>",
"description": "<string>",
"category": "<string>",
"transactedAt": "<string>",
"executeRules": True,
"asyncRules": True,
"configRulesExecution": {},
"linkEntityStrict": 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": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
externalId: '<string>',
type: '<string>',
amount: 123,
currency: '<string>',
exchangeRate: 123,
status: '<string>',
paymentMethod: '<string>',
description: '<string>',
category: '<string>',
transactedAt: '<string>',
executeRules: true,
asyncRules: true,
configRulesExecution: {},
linkEntityStrict: 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: {}
})
};
fetch('http://api.gu1.ai/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/transactions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'externalId' => '<string>',
'type' => '<string>',
'amount' => 123,
'currency' => '<string>',
'exchangeRate' => 123,
'status' => '<string>',
'paymentMethod' => '<string>',
'description' => '<string>',
'category' => '<string>',
'transactedAt' => '<string>',
'executeRules' => true,
'asyncRules' => true,
'configRulesExecution' => [
],
'linkEntityStrict' => 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' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/transactions"
payload := strings.NewReader("{\n \"externalId\": \"<string>\",\n \"type\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"exchangeRate\": 123,\n \"status\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"transactedAt\": \"<string>\",\n \"executeRules\": true,\n \"asyncRules\": true,\n \"configRulesExecution\": {},\n \"linkEntityStrict\": true,\n \"validateExistingEntity\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"originEntityId\": \"<string>\",\n \"originExternalId\": \"<string>\",\n \"originTaxId\": \"<string>\",\n \"originName\": \"<string>\",\n \"originCountry\": \"<string>\",\n \"originDetails\": {},\n \"destinationEntityId\": \"<string>\",\n \"destinationExternalId\": \"<string>\",\n \"destinationTaxId\": \"<string>\",\n \"destinationName\": \"<string>\",\n \"destinationCountry\": \"<string>\",\n \"destinationDetails\": {},\n \"locationDetails\": {},\n \"deviceDetails\": {},\n \"channel\": \"<string>\",\n \"reason\": \"<string>\",\n \"timeZone\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/transactions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"externalId\": \"<string>\",\n \"type\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"exchangeRate\": 123,\n \"status\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"transactedAt\": \"<string>\",\n \"executeRules\": true,\n \"asyncRules\": true,\n \"configRulesExecution\": {},\n \"linkEntityStrict\": true,\n \"validateExistingEntity\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"originEntityId\": \"<string>\",\n \"originExternalId\": \"<string>\",\n \"originTaxId\": \"<string>\",\n \"originName\": \"<string>\",\n \"originCountry\": \"<string>\",\n \"originDetails\": {},\n \"destinationEntityId\": \"<string>\",\n \"destinationExternalId\": \"<string>\",\n \"destinationTaxId\": \"<string>\",\n \"destinationName\": \"<string>\",\n \"destinationCountry\": \"<string>\",\n \"destinationDetails\": {},\n \"locationDetails\": {},\n \"deviceDetails\": {},\n \"channel\": \"<string>\",\n \"reason\": \"<string>\",\n \"timeZone\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/transactions")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"externalId\": \"<string>\",\n \"type\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"exchangeRate\": 123,\n \"status\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"transactedAt\": \"<string>\",\n \"executeRules\": true,\n \"asyncRules\": true,\n \"configRulesExecution\": {},\n \"linkEntityStrict\": true,\n \"validateExistingEntity\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"originEntityId\": \"<string>\",\n \"originExternalId\": \"<string>\",\n \"originTaxId\": \"<string>\",\n \"originName\": \"<string>\",\n \"originCountry\": \"<string>\",\n \"originDetails\": {},\n \"destinationEntityId\": \"<string>\",\n \"destinationExternalId\": \"<string>\",\n \"destinationTaxId\": \"<string>\",\n \"destinationName\": \"<string>\",\n \"destinationCountry\": \"<string>\",\n \"destinationDetails\": {},\n \"locationDetails\": {},\n \"deviceDetails\": {},\n \"channel\": \"<string>\",\n \"reason\": \"<string>\",\n \"timeZone\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"transaction": {},
"rulesExecutionSummary": {},
"asyncRules": true,
"rulesEvaluationStatus": "<string>"
}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
/
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>",
"exchangeRate": 123,
"status": "<string>",
"paymentMethod": "<string>",
"description": "<string>",
"category": "<string>",
"transactedAt": "<string>",
"executeRules": true,
"asyncRules": true,
"configRulesExecution": {},
"linkEntityStrict": 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": {}
}
'import requests
url = "http://api.gu1.ai/transactions"
payload = {
"externalId": "<string>",
"type": "<string>",
"amount": 123,
"currency": "<string>",
"exchangeRate": 123,
"status": "<string>",
"paymentMethod": "<string>",
"description": "<string>",
"category": "<string>",
"transactedAt": "<string>",
"executeRules": True,
"asyncRules": True,
"configRulesExecution": {},
"linkEntityStrict": 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": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
externalId: '<string>',
type: '<string>',
amount: 123,
currency: '<string>',
exchangeRate: 123,
status: '<string>',
paymentMethod: '<string>',
description: '<string>',
category: '<string>',
transactedAt: '<string>',
executeRules: true,
asyncRules: true,
configRulesExecution: {},
linkEntityStrict: 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: {}
})
};
fetch('http://api.gu1.ai/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/transactions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'externalId' => '<string>',
'type' => '<string>',
'amount' => 123,
'currency' => '<string>',
'exchangeRate' => 123,
'status' => '<string>',
'paymentMethod' => '<string>',
'description' => '<string>',
'category' => '<string>',
'transactedAt' => '<string>',
'executeRules' => true,
'asyncRules' => true,
'configRulesExecution' => [
],
'linkEntityStrict' => 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' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/transactions"
payload := strings.NewReader("{\n \"externalId\": \"<string>\",\n \"type\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"exchangeRate\": 123,\n \"status\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"transactedAt\": \"<string>\",\n \"executeRules\": true,\n \"asyncRules\": true,\n \"configRulesExecution\": {},\n \"linkEntityStrict\": true,\n \"validateExistingEntity\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"originEntityId\": \"<string>\",\n \"originExternalId\": \"<string>\",\n \"originTaxId\": \"<string>\",\n \"originName\": \"<string>\",\n \"originCountry\": \"<string>\",\n \"originDetails\": {},\n \"destinationEntityId\": \"<string>\",\n \"destinationExternalId\": \"<string>\",\n \"destinationTaxId\": \"<string>\",\n \"destinationName\": \"<string>\",\n \"destinationCountry\": \"<string>\",\n \"destinationDetails\": {},\n \"locationDetails\": {},\n \"deviceDetails\": {},\n \"channel\": \"<string>\",\n \"reason\": \"<string>\",\n \"timeZone\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/transactions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"externalId\": \"<string>\",\n \"type\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"exchangeRate\": 123,\n \"status\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"transactedAt\": \"<string>\",\n \"executeRules\": true,\n \"asyncRules\": true,\n \"configRulesExecution\": {},\n \"linkEntityStrict\": true,\n \"validateExistingEntity\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"originEntityId\": \"<string>\",\n \"originExternalId\": \"<string>\",\n \"originTaxId\": \"<string>\",\n \"originName\": \"<string>\",\n \"originCountry\": \"<string>\",\n \"originDetails\": {},\n \"destinationEntityId\": \"<string>\",\n \"destinationExternalId\": \"<string>\",\n \"destinationTaxId\": \"<string>\",\n \"destinationName\": \"<string>\",\n \"destinationCountry\": \"<string>\",\n \"destinationDetails\": {},\n \"locationDetails\": {},\n \"deviceDetails\": {},\n \"channel\": \"<string>\",\n \"reason\": \"<string>\",\n \"timeZone\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/transactions")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"externalId\": \"<string>\",\n \"type\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"exchangeRate\": 123,\n \"status\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"transactedAt\": \"<string>\",\n \"executeRules\": true,\n \"asyncRules\": true,\n \"configRulesExecution\": {},\n \"linkEntityStrict\": true,\n \"validateExistingEntity\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"originEntityId\": \"<string>\",\n \"originExternalId\": \"<string>\",\n \"originTaxId\": \"<string>\",\n \"originName\": \"<string>\",\n \"originCountry\": \"<string>\",\n \"originDetails\": {},\n \"destinationEntityId\": \"<string>\",\n \"destinationExternalId\": \"<string>\",\n \"destinationTaxId\": \"<string>\",\n \"destinationName\": \"<string>\",\n \"destinationCountry\": \"<string>\",\n \"destinationDetails\": {},\n \"locationDetails\": {},\n \"deviceDetails\": {},\n \"channel\": \"<string>\",\n \"reason\": \"<string>\",\n \"timeZone\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"transaction": {},
"rulesExecutionSummary": {},
"asyncRules": true,
"rulesEvaluationStatus": "<string>"
}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
POST http://api.gu1.ai/transactions
Autenticação
Requer uma API key válida no header Authorization:Authorization: Bearer YOUR_API_KEY
Parâmetros de query
boolean
default:"false"
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
string
required
Seu identificador único para esta transação no seu sistema
string
required
Tipo da transação. Opções:
PAYMENT- PagamentoTRANSFER- TransferênciaWITHDRAWAL- SaqueDEPOSIT- DepósitoREFUND- ReembolsoCHARGEBACK- ChargebackREVERSAL- EstornoFEE- TaxaADJUSTMENT- AjusteOTHER- Outro
number
required
Valor (deve ser zero ou positivo)
string
required
Código da moeda (3–4 caracteres, por exemplo
USD, EUR, BRL). A conversão automática vale só para os códigos de Moedas com conversão automática.number
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 porque o código não está em Moedas com conversão automática. Ver Conversão de moeda.Campos opcionais
string
default:"CREATED"
Status. Opções:
CREATED, PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFULstring
Método de pagamento. Opções:
CARD, ACH, PIX, TED, BOLETO, WALLET, SWIFT, IBAN, CBU, CVU, DEBIN, GENERIC_BANK_ACCOUNT, MPESA, UPI, CHECK, ECHECK, CASH, QR_CODE, ONLINE_PAYMENT, WITHDRAWAL_ORDERstring
Descrição ou notas
string
Categoria da transação
string
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).boolean
default:"true"
Se o motor de regras deve rodar. Com
false, pula regras por completo (sync e async).boolean
default:"false"
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.object
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).boolean
default:"false"
Com
false (padrão): o Gu1 ainda auto-vincula quando há match. Se não, a TX ainda é criada (sem vínculo). Um UUID *EntityId inexistente é limpo (sem 404). Também ?linkEntityStrict=true.Com true: refs não resolvidas → 400 INVALID_ENTITY_REFERENCES e não cria.boolean
default:"false"
Alias legado de
linkEntityStrict: true. Prefira linkEntityStrict.Matrizes de risco (opcional)
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.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):
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.)string
UUID da entidade de origem no gu1. Entidades arquivadas (
deletedAt definido) não podem ser origem nem destino: a API retorna 403 ENTITY_ARCHIVED.string
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).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. Após vincular, gravado como entities.tax_id. Opcional, máx. 50 caracteres.string
Nome da origem
string
Código de país ISO 2 da origem (ex.: “US”, “BR”, “AR”)
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, 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).Gu1 adiciona o campo reservado linkedEntityGu1 ao criar a transação: linked indica que a origem foi vinculada, unresolved que pelo menos uma referência raiz (originEntityId, originExternalId ou originTaxId) foi enviada mas não resolvida no modo soft-link, e not_requested que nenhuma referência foi enviada. O campo pertence ao servidor: qualquer valor enviado pelo integrador é ignorado e sobrescrito.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.string
UUID da entidade de destino no gu1
string
Seu ID externo da entidade de destino. Após vincular, gravado como
entities.external_id.string
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.string
Nome do destino
string
Código de país ISO 2 do destino
object
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).Gu1 adiciona o campo reservado linkedEntityGu1 ao criar a transação: linked indica que o destino foi vinculado, unresolved que pelo menos uma referência raiz (destinationEntityId, destinationExternalId ou destinationTaxId) foi enviada mas não resolvida no modo soft-link, e not_requested que nenhuma referência foi enviada. O campo pertence ao servidor: qualquer valor enviado pelo integrador é ignorado e sobrescrito.Localização e dispositivo
object
Localização:
country, city, region, address, latitude, longitude, postalCode, etc.object
Dispositivo:
deviceId, platform, osName, model, ipAddress, isVpn, isTor, etc.string
Canal (máx. 50 caracteres):
mobile_app, web_browser, pos_terminal, api, atm, etc.string
Motivo do resultado (opcional). Ver Enum de motivos. Se omitido, usa
WITHOUT_REASON.string
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.object
Metadados adicionais:
tags, purpose, enhanced_due_diligence, block_reason, compliance_alert, etc.Resposta
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.object
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.boolean
Presente e
true apenas quando as regras foram enfileiradas. Omitido no fluxo síncrono padrão.string
No modo async:
"queued". Omitido quando as regras rodaram de forma síncrona.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"
}'
const response = await fetch('http://api.gu1.ai/transactions', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
externalId: 'txn_12345',
type: 'PAYMENT',
amount: 150.50,
currency: 'USD',
originExternalId: 'customer_001',
destinationExternalId: 'merchant_456',
description: 'Compra online'
})
});
const data = await response.json();
console.log(data.transaction);
import requests
response = requests.post(
'http://api.gu1.ai/transactions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'externalId': 'txn_12345',
'type': 'PAYMENT',
'amount': 150.50,
'currency': 'USD',
'originExternalId': 'customer_001',
'destinationExternalId': 'merchant_456',
'description': 'Compra online'
}
)
transaction = response.json()['transaction']
print(transaction)
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.
curl -X POST "http://api.gu1.ai/transactions?asyncRules=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "txn_nightly_001",
"type": "PAYMENT",
"amount": 150.50,
"currency": "BRL",
"destinationExternalId": "merchant_456"
}'
{
"transaction": { "id": "...", "externalId": "txn_nightly_001", "status": "SUCCESSFUL" },
"rulesExecutionSummary": {
"success": true,
"rulesHit": [],
"rulesNoHit": [],
"totalScore": 0,
"matchedRulesCount": 0,
"executionTimeMs": 0
},
"asyncRules": true,
"rulesEvaluationStatus": "queued"
}
Não use a resposta síncrona para aprovar ou bloquear pagamentos quando
asyncRules=true. Não há segundo webhook ao terminar as regras em background — monitore alertas no gu1 ou consulte APIs de transação/investigação.Conversão de moeda
Quandocurrency difere da moeda base da organização (padrão USD) e o código está em Moedas com conversão automática, a Gu1 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 com conversão automática
A conversão automática roda só para os códigos de Moedas com conversão automática. Qualquer outro código de 3–4 caracteres (por exemploETH, USDT, USDC, SOL, WLD) é gravado na transação, e a taxa automática não está disponível salvo se você enviar exchangeRate.
BTC está nessa lista. Os demais códigos de cripto, não.
Envie exchangeRate se precisar de valor normalizado na moeda base para regras e relatórios.
Exemplo — WLD com taxa do cliente
{
"externalId": "txn-wld-001",
"type": "PAYMENT",
"amount": 26.16,
"currency": "WLD",
"exchangeRate": 2.41,
"destinationExternalId": "merchant_001"
}
63.05, rateSource: client-provided):
{
"transaction": {
"amount": "26.16",
"currency": "WLD",
"exchangeRate": "2.41",
"rateSource": "client-provided",
"currenciesExchange": [
{ "currency": "USD", "exchangeRate": 2.41, "value": 63.05 }
]
}
}
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
{
"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 - Validação
{
"error": "TRANSACTION_VALIDATION_ERROR",
"message": "The request body does not match the schema required to create a transaction.",
"summary": "amount: Required",
"issues": [
{
"path": "amount",
"code": "invalid_type",
"message": "Required",
"expected": "number",
"received": "undefined"
}
],
"details": "Validation failed: [...]"
}
400 - Referências de entidade inválidas
ComlinkEntityStrict / validateExistingEntity em true e um lado sem resolução:
{
"error": "INVALID_ENTITY_REFERENCES",
"message": "One or more entity references could not be resolved to a person or company in this organization.",
"summary": "origin: …",
"issues": []
}
400 - Matriz de risco inválida
Quando você enviariskMatrixId ou riskMatrixIds e alguma matriz não é utilizável para a organização:
{
"success": false,
"error": {
"code": "INVALID_RISK_MATRIX",
"message": "One or more risk matrices are not usable for this organization"
}
}
403 - Entidade arquivada
{
"success": false,
"error": {
"code": "ENTITY_ARCHIVED",
"message": "…",
"details": { "entityIds": ["…"] }
}
}
409 - Transação duplicada
{
"error": "DUPLICATE_TRANSACTION_EXTERNAL_ID",
"message": "A transaction with this externalId already exists in the organization",
"externalId": "txn_12345"
}
429 - Cota de criação
{
"success": false,
"error": {
"code": "CREATION_CONTRACT_QUOTA_EXCEEDED",
"message": "Creation quota exceeded for module transactions: …",
"module": "transactions",
"requested": 1,
"remainingTotal": 0
}
}
500 - Falha ao criar
Falha inesperada ao criar a transação (sem campocode estruturado):
{
"error": "Failed to create transaction",
"details": "…"
}
503 - Fila de regras async indisponível
QuandoexecuteRules é true, asyncRules é true e a fila de regras não consegue aceitar o job. A transação já foi criada; a resposta inclui o objeto transaction:
{
"success": false,
"error": {
"code": "ASYNC_RULES_QUEUE_UNAVAILABLE",
"message": "Could not enqueue rules evaluation"
},
"transaction": { }
}
Resumo dos códigos de erro
| HTTP | Código | Quando |
|---|---|---|
| 400 | TRANSACTION_VALIDATION_ERROR | Body falha na validação do schema |
| 400 | INVALID_ENTITY_REFERENCES | Link estrito de entidade não resolve |
| 400 | INVALID_RISK_MATRIX | riskMatrixId / riskMatrixIds não utilizável na org |
| 403 | ENTITY_ARCHIVED | Origem ou destino arquivado |
| 409 | DUPLICATE_TRANSACTION_EXTERNAL_ID | Mesmo externalId já existe na org |
| 429 | CREATION_CONTRACT_QUOTA_EXCEEDED | Cota de criação excedida |
| 500 | (sem code) | Falha inesperada (Failed to create transaction) |
| 503 | ASYNC_RULES_QUEUE_UNAVAILABLE | Enfileirar regras async falhou após o insert |
Simulação de erros no sandbox
Somente no sandbox você pode forçar esses (e outros) erros de create sem gravar uma linha — veja Simulação de erros no sandbox.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
- Simulação de erros no sandbox - Forçar erros de create no sandbox
- Monitoramento de transações - Detecção de fraude
Was this page helpful?