Cambiar Estado de Transacción

Endpoint

Cambiar Estado de Transacción

PATCH http://api.gu1.ai/transactions/:id/changeStatus

Actualiza el estado de una transacción existente con validación automática de transiciones de estado y ejecución opcional de reglas para re-evaluación de riesgo en tiempo real. Características:

Validación automática de transiciones de estado (previene cambios de estado inválidos)
Aplicación de máquina de estados (reglas de estados abiertos ↔ cerrados)
Ejecución automática de reglas de actualización con trigger trigger_transaction_updated
Protección de integridad de transacciones
Rastro de auditoría completo

Autenticación

Todas las solicitudes deben incluir una clave API en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Encabezados Requeridos

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

string

required

El UUID de la transacción a actualizarTipo: string (uuid)

Cuerpo de la Solicitud

status

string

required

Nuevo estado de la transacción. Debe ser un valor válido del enum de estados.Estados Válidos:

CREATED - Transacción creada (estado abierto)
PROCESSING - Transacción en proceso (estado abierto)
SUSPENDED - Transacción temporalmente suspendida (estado abierto)
SENT - Transacción enviada/transmitida (estado cerrado)
EXPIRED - Transacción expirada (estado cerrado)
DECLINED - Transacción rechazada/declinada (estado cerrado)
REFUNDED - Transacción reembolsada/reversada (estado cerrado)
SUCCESSFUL - Transacción completada exitosamente (estado cerrado)

Reglas de Transición de Estados

El endpoint aplica reglas estrictas de transición de estados para mantener la integridad de las transacciones:

Estados Abiertos

Estados que permiten transiciones adicionales:

CREATED
PROCESSING
SUSPENDED
SENT

Estados Cerrados

Estados finales que no pueden transicionar a otros estados:

EXPIRED
DECLINED
REFUNDED
SUCCESSFUL

Matriz de Transiciones

Estado Origen	Estado Destino	¿Permitido?	Nota
CREATED	PROCESSING	✅ Sí	Flujo normal
CREATED	SUSPENDED	✅ Sí	Suspender para revisión
CREATED	SUCCESSFUL	✅ Sí	Aprobación rápida
PROCESSING	SUSPENDED	✅ Sí	Suspender durante procesamiento
PROCESSING	SUCCESSFUL	✅ Sí	Finalización normal
PROCESSING	DECLINED	✅ Sí	Rechazar durante procesamiento
SUSPENDED	PROCESSING	✅ Sí	Reanudar procesamiento
SUSPENDED	SUCCESSFUL	✅ Sí	Aprobar transacción suspendida
SUSPENDED	DECLINED	✅ Sí	Rechazar transacción suspendida
SUCCESSFUL	PROCESSING	❌ No	No se puede reabrir transacción cerrada
DECLINED	PROCESSING	❌ No	No se puede reabrir transacción cerrada
EXPIRED	PROCESSING	❌ No	No se puede reabrir transacción cerrada
REFUNDED	any	❌ No	No se puede cambiar transacción reembolsada
SUCCESSFUL	DECLINED	❌ No	No se puede cambiar entre estados cerrados

Reglas Clave:

✅ Abierto → Abierto: Permitido (ej: CREATED → PROCESSING)
✅ Abierto → Cerrado: Permitido (ej: PROCESSING → SUCCESSFUL)
❌ Cerrado → Abierto: NO Permitido (ej: SUCCESSFUL → PROCESSING)
❌ Cerrado → Cerrado: NO Permitido (ej: DECLINED → REFUNDED)

Ejecución de Reglas de Actualización

Cuando se cambia el estado de una transacción, el endpoint automáticamente:

Valida la transición - Asegura que el nuevo estado es válido y la transición está permitida
Actualiza el estado - Cambia el estado de la transacción en la base de datos
Ejecuta reglas de actualización - Ejecuta todas las reglas con trigger: 'updated' en su alcance
Actualiza puntuación de riesgo - Re-calcula el riesgo basado en los resultados de las reglas
Devuelve transacción actualizada - Devuelve la transacción completa con la nueva evaluación de riesgo

Trigger de Reglas

El endpoint usa el modo trigger_transaction_updated, que ejecuta todas las reglas configuradas con el trigger updated. Ejemplo de configuración de alcance de regla:

{
  "scope": {
    "triggers": ["updated"],
    "targetEntityTypes": ["transaction"]
  }
}

Ejemplos Completos de Solicitud

Aprobar una Transacción Suspendida

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUCCESSFUL"
  }'

Rechazar una Transacción en Revisión

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "DECLINED"
  }'

Suspender una Transacción para Revisión Manual

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUSPENDED"
  }'

Respuesta

Respuesta Exitosa (200 OK)

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "status": "SUCCESSFUL",
    "amount": 1500.00,
    "currency": "USD",
    "amountInUsd": 1500.00,
    "origin": {
      "entityId": "customer_001",
      "externalId": "EXT-001",
      "name": "Juan Pérez",
      "country": "US",
      "details": {},
      "type": "person",
      "riskScore": 15.50
    },
    "destination": {
      "entityId": "merchant_002",
      "externalId": "MER-002",
      "name": "Tienda de Electrónicos",
      "country": "US",
      "details": {},
      "type": "company",
      "riskScore": 8.20
    },
    "riskScore": 22.50,
    "riskFactors": [
      {
        "factor": "status_change",
        "score": 5,
        "description": "Estado de transacción cambió a SUCCESSFUL"
      }
    ],
    "flagged": false,
    "description": "Compra de laptop",
    "category": "electronics",
    "metadata": {},
    "transactedAt": "2024-12-23T14:30:00.000Z",
    "createdAt": "2024-12-23T14:30:00.000Z",
    "updatedAt": "2024-12-23T15:45:00.000Z"
  },
  "statusChanged": {
    "from": "SUSPENDED",
    "to": "SUCCESSFUL"
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "executionTimeMs": 245,
    "result": {
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityType": "transaction",
      "rulesExecuted": [
        {
          "ruleId": "rule_001",
          "ruleName": "Verificación de Transacciones de Alto Valor",
          "passed": true,
          "score": 5
        }
      ],
      "totalRules": 3,
      "successfulRules": 3,
      "failedRules": 0,
      "overallConfidence": 0.95,
      "riskScore": 22.50,
      "flags": []
    },
    "auditId": "audit_12345",
    "isNewAudit": false
  }
}

Campos de Respuesta

success

boolean

Si el cambio de estado fue exitoso

transaction

object

La transacción actualizada con todos sus datos, incluyendo:

id (string) - UUID de la transacción
status (string) - Nuevo estado de la transacción
origin (object) - Información de la parte origen (estructura anidada)
- entityId (string) - UUID de la entidad origen
- name (string) - Nombre de la parte origen
- country (string) - País de origen
- details (object) - Detalles adicionales de origen
- type (string) - Tipo de entidad origen
- riskScore (number) - Puntuación de riesgo de la entidad origen
destination (object) - Información de la parte destino (estructura anidada)
- entityId (string) - UUID de la entidad destino
- name (string) - Nombre de la parte destino
- country (string) - País de destino
- details (object) - Detalles adicionales de destino
- type (string) - Tipo de entidad destino
- riskScore (number) - Puntuación de riesgo de la entidad destino
riskScore (number) - Puntuación de riesgo actualizada después de la re-evaluación
riskFactors (array) - Factores de riesgo actualizados
flagged (boolean) - Estado de marcado actualizado
updatedAt (string) - Timestamp de la actualización

statusChanged

object

Información sobre la transición de estado:

from (string) - Estado anterior
to (string) - Nuevo estado

rulesResult

object

Resultado completo de la ejecución de reglas de actualización (RulesExecutionResult):

success (boolean) - Si las reglas se ejecutaron exitosamente
executed (boolean) - Si se ejecutó alguna regla
result (object | undefined) - Resultado del análisis de entidad con detalles de ejecución de reglas
rulesTriggered (number | undefined) - Número de reglas que fueron ejecutadas
executionTimeMs (number | undefined) - Tiempo de ejecución en milisegundos
error (string | undefined) - Mensaje de error si la ejecución falló
auditId (string | undefined) - ID del registro de auditoría
isNewAudit (boolean | undefined) - Si se creó una nueva auditoría
warnings (array | undefined) - Array de mensajes de advertencia
metadata (object | undefined) - Metadata adicional incluyendo resumen de cobertura, campos faltantes y recomendaciones
rulesExecutionSummary (object | undefined) - Cuando se ejecutaron reglas, resumen detallado; ver más abajo

rulesExecutionSummary

object

En la raíz de la respuesta (igual que la API de transacciones). Mismo valor que rulesResult.rulesExecutionSummary. Solo presente cuando se ejecutaron reglas. Resumen de qué reglas hicieron match (hit) y cuáles no (no hit), acciones ejecutadas y puntuación total.

rulesHit (array) - Reglas cuyas condiciones se cumplieron. Cada elemento: name, description, score, priority, category, status, conditions, actions.
rulesNoHit (array) - Reglas evaluadas pero condiciones no cumplidas. Misma estructura que rulesHit.
actionsExecuted (object) - Acciones ejecutadas agregadas: alerts, suggestion, status, assignedUser, customKeys (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match; para integraciones/workflows.
totalScore (number) - Suma de puntuación de todas las reglas que hicieron hit (excluyendo shadow).

Respuestas de Error

400 Bad Request - Estado Inválido

{
  "error": "Invalid status",
  "validStatuses": [
    "CREATED",
    "PROCESSING",
    "SUSPENDED",
    "SENT",
    "EXPIRED",
    "DECLINED",
    "REFUNDED",
    "SUCCESSFUL"
  ]
}

400 Bad Request - Transición Inválida

{
  "error": "Cannot transition from closed status to open status",
  "currentStatus": "SUCCESSFUL",
  "requestedStatus": "PROCESSING",
  "message": "Transaction is in a closed state (SUCCESSFUL) and cannot be reopened"
}

404 Not Found

{
  "error": "Transaction not found"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to change transaction status",
  "details": "Internal server error message"
}

Casos de Uso

1. Flujo de Revisión Manual

// Paso 1: Suspender transacción sospechosa
await changeStatus(transactionId, 'SUSPENDED');

// Paso 2: Analista revisa la transacción
// ... proceso de revisión manual ...

// Paso 3: Aprobar o rechazar según la revisión
if (approved) {
  await changeStatus(transactionId, 'SUCCESSFUL');
} else {
  await changeStatus(transactionId, 'DECLINED');
}

2. Verificación Automática de Cumplimiento

// Transacción creada con estado CREATED
const transaction = await createTransaction({...});

// Ejecutar verificaciones de cumplimiento adicionales
const complianceResult = await runComplianceChecks(transaction.id);

if (complianceResult.passed) {
  // Mover a procesamiento
  await changeStatus(transaction.id, 'PROCESSING');

  // Completar transacción
  await changeStatus(transaction.id, 'SUCCESSFUL');
} else {
  // Rechazar por problemas de cumplimiento
  await changeStatus(transaction.id, 'DECLINED');
}

3. Respuesta a Detección de Fraude

// Monitorear actualizaciones de transacciones
if (fraudDetected) {
  // Suspender transacción inmediatamente
  await changeStatus(transactionId, 'SUSPENDED');

  // Crear alerta para investigación
  await createAlert({
    transactionId,
    type: 'fraud_suspected',
    severity: 'high'
  });

  // Después de la investigación, tomar acción
  if (confirmed) {
    await changeStatus(transactionId, 'DECLINED');
  } else {
    await changeStatus(transactionId, 'SUCCESSFUL');
  }
}

4. Actualizaciones Masivas de Estado

// Actualizar múltiples transacciones en paralelo
const suspendedTransactions = await getTransactionsByStatus('SUSPENDED');

const results = await Promise.allSettled(
  suspendedTransactions.map(async (txn) => {
    if (shouldApprove(txn)) {
      return await changeStatus(txn.id, 'SUCCESSFUL');
    } else if (shouldDecline(txn)) {
      return await changeStatus(txn.id, 'DECLINED');
    }
  })
);

console.log(`Actualizadas ${results.filter(r => r.status === 'fulfilled').length} transacciones`);

Mejores Prácticas

Validar antes de cambiar - Siempre verificar el estado actual antes de intentar un cambio de estado para evitar llamadas API innecesarias
Manejar errores de transición - Implementar manejo de errores apropiado para transiciones inválidas, ya que las transacciones cerradas no pueden ser reabiertas
Usar estados apropiados - Elegir el estado correcto que refleje el estado de negocio real de la transacción
Monitorear ejecución de reglas - Prestar atención al objeto rulesResult para asegurar que las reglas de actualización se ejecuten como se espera y verificar detalles de ejecución, advertencias y metadata
Implementar registro de auditoría - Rastrear todos los cambios de estado en su sistema para cumplimiento y depuración
Actualizaciones masivas - Al actualizar múltiples transacciones, usar Promise.allSettled() para continuar procesando incluso si algunas actualizaciones fallan
Integración de webhooks - Considerar configurar webhooks para recibir notificaciones cuando los cambios de estado ejecuten reglas importantes
Probar transiciones de estado - Probar todas las posibles transiciones de estado en su entorno de desarrollo antes de desplegar a producción

Endpoints Relacionados

Crear Transacción

Crear nuevas transacciones

Obtener Transacción

Recuperar detalles de transacción

Configuración de Reglas

Configurar reglas de actualización

Resumen

Volver al resumen

Comenzando

Casos de Uso

Webhooks

Persona

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

​Endpoint