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

POST

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

Resumen

Crea una nueva transacción. Con executeRules: true (por defecto), se ejecuta el motor de reglas y la respuesta incluye rulesExecutionSummary en la raíz cuando se ejecutan las reglas.

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

Matrices de riesgo (opcional)

riskMatrixId

string | string[]

Compatible con clientes legacy: un UUID o un array de UUIDs de matrices de la organización. Si se envía una lista no vacía, solo se evalúan reglas activas asociadas a esas matrices (sin mezclar con reglas “sueltas” solo por triggers). Omití riskMatrixId y riskMatrixIds para conservar el comportamiento histórico basado en triggers.

riskMatrixIds

string[]

Forma preferida para varias matrices: lista ordenada de UUIDs. Tiene precedencia sobre riskMatrixId cuando viene informada y no vacía.

Origen (entidad)

Cómo se vincula el origen en gu1 (en orden; se aplica el primer criterio que resuelva):

ID de entidad — si enviás originEntityId, se usa esa entidad (debe existir en tu organización).
ID externo — si no enviaste originEntityId pero sí originExternalId y existe una persona/empresa con el mismo externalId, se vincula automáticamente.
Tercer fallback: tax / documento (root) — si aún no hay vinculación, pero enviás en la raíz de la transacción originTaxId, el API busca una persona/empresa cuyo taxId coincida tras normalizar (solo letras y números, sin puntuación ni espacios; la comparación ignora mayúsculas).

Si resuelve el paso 2 o 3, se rellenan originEntityId y, si no los enviaste, se pueden completar originName y originCountry desde la entidad.Si no hay coincidencia, la transacción se crea igual (comportamiento por defecto); quedan guardados los campos que enviaste, sin enlace a entidad. Con validateExistingEntity: true, si enviaste algún identificador de origen y no hay entidad, la API responde 400 y no crea la transacción.
(En originDetails también podés enviar un tax para el grafo, pero eso no vincula entidades: para vincular por documento usá originTaxId a nivel raíz.)

originEntityId

string

UUID de la entidad origen en gu1

originExternalId

string

Tu ID externo de la entidad origen

originTaxId

string

CUIT o identificador fiscal / documento del origen a nivel raíz (no dentro de originDetails). Es el tercer criterio, después de originEntityId y originExternalId. Se compara con el taxId de entidades (persona/empresa) con la misma normalización alfanumérica. Si hay match, se rellenan enlace, nombre y país. Opcional, máx. 50 caracteres.

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

destinationTaxId

string

CUIT o documento del destino a nivel raíz; tercer criterio de vinculación, después de destinationEntityId y destinationExternalId. Misma lógica que originTaxId (normalización, enriquecimiento de nombre y país). Opcional, máx. 50 caracteres.

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.

timeZone

string

Zona horaria IANA opcional (independiente de operationalHours de la entidad). Valores de transaction_time_zone. Si se omite, queda null.Normalización de transactedAt: si transactedAt trae Z (como exige el validador de este endpoint), se guarda ese instante en UTC; timeZone es metadata opcional y no se usa para parsear. Con datetime local + timeZone (herramientas internas/lote), la API puede convertir hora local a UTC. Las integraciones que no envían timeZone siguen igual que antes. Las reglas de horario operativo usan el instante guardado + operationalHours.timezone de la entidad, no transaction.timeZone.Lista completa: Enum zona horaria.

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, timeZone (string | null), originDetails, destinationDetails, locationDetails, deviceDetails, processingTimeMs, processedAt, transactedAt, createdAt, updatedAt.

rulesExecutionSummary

object

Solo si executeRules es true y el motor de reglas se ejecutó. No se incluye cuando executeRules es false. 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"
  },
  "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

Obtener transacción - Por ID o external ID
Crear transacciones en lote - Carga masiva
Cambiar estado de transacción - Cambiar estado
Monitoreo de transacciones - Detección de fraude

Cambiar Estado de Transacción Obtener transacción

⌘I

Documentation Index

​Resumen

​Endpoint

​Autenticación

​Cuerpo de la petición

​Campos requeridos

​Campos opcionales

​Matrices de riesgo (opcional)

​Origen (entidad)

​Destino (entidad)

​Ubicación y dispositivo

​Respuesta

​Ejemplo básico

​Ejemplo de respuesta

​Errores

​400 - Datos inválidos

​409 - Transacción duplicada

​429 - Límite de tasa

​Próximos pasos

Resumen

Endpoint

Autenticación

Cuerpo de la petición

Campos requeridos

Campos opcionales

Matrices de riesgo (opcional)

Origen (entidad)

Destino (entidad)

Ubicación y dispositivo

Respuesta

Ejemplo básico

Ejemplo de respuesta

Errores

400 - Datos inválidos

409 - Transacción duplicada

429 - Límite de tasa

Próximos pasos