Skip to main content
POST
http://api.gu1.ai
/
transactions
Crear transacción
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": {}
}

​
Resumen

Crea una nueva transacción. Con executeRules: true (por defecto), se ejecuta el motor de reglas y la respuesta incluye rulesResult y rulesExecutionSummary.

​
Endpoint

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

​
Autenticación

Requiere una API key válida en el header Authorization: 
Authorization: Bearer YOUR_API_KEY

​
Cuerpo de la petición

​
Campos requeridos

​
externalId
string
required
Tu identificador único para esta transacción en tu sistema
​
type
string
required
Tipo de transacción. Opciones:
  • PAYMENT - Pago
  • TRANSFER - Transferencia
  • WITHDRAWAL - Retiro
  • DEPOSIT - Depósito
  • REFUND - Reembolso
  • CHARGEBACK - Contracargo
  • REVERSAL - Reversión
  • FEE - Comisión
  • ADJUSTMENT - Ajuste
  • OTHER - Otro
​
amount
number
required
Monto (debe ser cero o positivo)
​
currency
string
required
Código de moneda (3-4 caracteres, ej. “USD”, “EUR”, “BRL”)

​
Campos opcionales

​
status
string
default:"CREATED"
Estado. Opciones:
  • CREATED - Creada (por defecto)
  • PROCESSING - En proceso
  • SUSPENDED - Suspendida
  • SENT - Enviada
  • EXPIRED - Expirada
  • DECLINED - Rechazada
  • REFUNDED - Reembolsada
  • SUCCESSFUL - Exitosa
​
paymentMethod
string
Método de pago. Opciones: CARD, ACH, PIX, TED, BOLETO, WALLET, SWIFT, IBAN, CBU, CVU, DEBIN, GENERIC_BANK_ACCOUNT, MPESA, UPI, CHECK, ECHECK, QR_CODE, ONLINE_PAYMENT, WITHDRAWAL_ORDER
​
description
string
Descripción o notas
​
category
string
Categoría de la transacción
​
transactedAt
string
Fecha/hora ISO 8601 del hecho (por defecto: momento de creación)
​
executeRules
boolean
default:"true"
Si se ejecuta el motor de reglas para esta transacción

​
Origen (entidad)

​
originEntityId
string
UUID de la entidad origen en gu1
​
originExternalId
string
Tu ID externo de la entidad origen
​
originName
string
Nombre del origen
​
originCountry
string
Código de país ISO 2 del origen (ej. “US”, “BR”, “AR”)
​
originDetails
object
Detalles del origen (dispositivo, cuenta, etc.). Ver Esquema de payment details para estructuras sugeridas. Campos extra permitidos. Si el origen no es una entidad en gu1, puedes enviar opcionalmente taxId y/o accountNumber en originDetails o originDetails.paymentDetails para mejorar la visualización en grafos de red (nodos “pseudo” agrupados por el mismo identificador).

​
Destino (entidad)

​
destinationEntityId
string
UUID de la entidad destino en gu1
​
destinationExternalId
string
Tu ID externo de la entidad destino
​
destinationName
string
Nombre del destino
​
destinationCountry
string
Código de país ISO 2 del destino
​
destinationDetails
object
Detalles del destino (comercio, cuenta, etc.). Campos opcionales: mcc, merchantId, merchantName, deviceId, accountNumber, bankCode, bankName, etc. Campos extra permitidos. Si el destino no es una entidad en gu1, puedes enviar opcionalmente taxId y/o accountNumber en destinationDetails o destinationDetails.paymentDetails para mejorar la visualización en grafos de red (nodos “pseudo” agrupados).

​
Ubicación y dispositivo

​
locationDetails
object
Ubicación: 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 del resultado (opcional). Ver Enum de motivos. Si se omite se usa WITHOUT_REASON.
​
metadata
object
Metadatos adicionales: tags, purpose, enhanced_due_diligence, block_reason, compliance_alert, etc. Campos custom permitidos.

​
Respuesta

​
transaction
object
La transacción creada (objeto). Incluye: id, externalId, organizationId, type, amount (string), currency, status, riskScore (string), flagged, channel, reason, originDetails, destinationDetails, locationDetails, deviceDetails, processingTimeMs, processedAt, transactedAt, createdAt, updatedAt.
​
rulesResult
object
Solo si executeRules fue true. Resultado de la ejecución de reglas:
  • success (boolean) - Si la ejecución fue exitosa
  • executed (boolean) - Si el motor se ejecutó
  • result (object, opcional) - Resultado completo del motor (riskScore, decision, alerts, etc.)
  • rulesExecutionSummary (object) - Resumen detallado; también duplicado en la raíz
  • rulesTriggered (number) - Cantidad de reglas que hicieron match
  • executionTimeMs (number) - Tiempo de ejecución en milisegundos
  • auditId (string, opcional) - ID del audit de matriz de riesgo
  • isNewAudit (boolean, opcional) - Si se creó un nuevo audit
​
rulesExecutionSummary
object
Solo si executeRules es true y el motor de reglas se ejecutó. Mismo objeto que rulesResult.rulesExecutionSummary. Incluye rulesHit, rulesNoHit, actionsExecuted (opcional), totalScore, scoreResult, riskMatrixName, executionTimeMs, trigger, matchedRulesCount. Ver Resumen de Ejecución de Reglas para la estructura completa y un ejemplo con todos los campos.

​
Ejemplo 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"
  }'

​
Ejemplo de respuesta

{
  "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
  }
}

​
Errores

​
400 - Datos 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 - Transacción duplicada

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

​
429 - Límite de tasa

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

​
Próximos pasos