Crear Regla

Descripción General

Crea una nueva regla para detección automatizada de riesgos, monitoreo de cumplimiento y prevención de fraude. Las reglas pueden evaluar entidades (personas, empresas), transacciones, relaciones y patrones de red utilizando lógica de condiciones flexible y acciones automatizadas.

Endpoint

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

Autenticación

Requiere una clave API válida en el encabezado de Authorization:

Authorization: Bearer YOUR_API_KEY

Cuerpo de la Solicitud

name

string

required

Nombre descriptivo para la regla

description

string

required

Descripción detallada de lo que detecta la regla

Estructura de Condiciones

Las reglas utilizan una estructura de condiciones anidadas con operadores lógicos:

{
  "operator": "AND" | "OR" | "NOT" | "XOR",
  "conditions": [
    {
      "id": "cond-unique-id",
      "type": "simple",
      "field": "enrichmentData.normalized.taxId",
      "operator": "eq",
      "value": "12.345.678/0001-90",
      "filters": [],
      "countryMetadata": {
        "countryCode": "BR",
        "confidence": 100,
        "manuallySet": true,
        "autoDetected": false,
        "reason": "Selected from BR enrichment fields"
      }
    }
  ]
}

Campos de Condiciones

operator: Operador lógico que conecta condiciones (AND, OR, NOT, XOR)
conditions: Array de objetos de condición (pueden estar anidados para lógica compleja)
id: Identificador único para la condición
type: Tipo de condición (simple, complex, array, object)
field: Ruta del campo a evaluar (ej., taxId, entityData.company.revenue, enrichmentData.normalized.sanctions.$.type)
operator: Operador de comparación (ver Operadores a continuación)
value: Valor con el que comparar
filters: Array de filtros para campos de array/objeto
countryMetadata: Metadatos específicos del país para la condición

Operadores

Operadores de Comparación

eq - Igual
neq - No igual
gt - Mayor que
gte - Mayor o igual que
lt - Menor que
lte - Menor o igual que

Operadores de Texto

contains - Contiene subcadena
notContains - No contiene subcadena
startsWith - Comienza con
endsWith - Termina con
regex - Coincide con expresión regular

Operadores de Array

in - El valor está en el array
notIn - El valor no está en el array
hasAny - Tiene alguno de los valores
hasAll - Tiene todos los valores

Operadores de Lista

inList - El valor existe en una lista de datos
notInList - El valor no existe en una lista de datos

Operadores de Existencia

exists - El campo existe
notExists - El campo no existe
isEmpty - El campo está vacío/nulo
isNotEmpty - El campo no está vacío/nulo

Operadores Booleanos

isTrue - El campo booleano es verdadero
isFalse - El campo booleano es falso

Sintaxis de Campos de Array

Para campos dentro de arrays, use el símbolo $:

{
  "field": "enrichmentData.normalized.sanctions.$.type",
  "operator": "in",
  "value": "terrorism",
  "filters": []
}

Esto evalúa si ALGÚN elemento en el array sanctions tiene type igual a "terrorism".

Filtros

Puede pre-filtrar elementos del array antes de la evaluación:

{
  "field": "enrichmentData.normalized.legalProceedings.$.amount",
  "operator": "gt",
  "value": 100000,
  "filters": [
    {
      "field": "status",
      "operator": "eq",
      "value": "active"
    }
  ]
}

Esto evalúa si ALGÚN proceso legal activo tiene un monto mayor a 100,000.

Acciones

Las reglas soportan múltiples tipos de acciones:

Crear Alerta

{
  "type": "createAlert",
  "createAlert": {
    "type": "FRAUD" | "COMPLIANCE" | "AML" | "KYC" | "OTHER",
    "title": "High Risk Transaction Detected",
    "description": "Transaction exceeds threshold",
    "severity": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
    "recipients": ["user@example.com"]
  },
  "tags": ["high-value", "cross-border"]
}

Actualizar Estado de Entidad

{
  "type": "updateEntityStatus",
  "updateEntityStatus": {
    "status": "blocked",
    "reason": "Failed sanctions check"
  }
}

Enviar Notificación

{
  "type": "sendNotification",
  "sendNotification": {
    "channel": "email" | "sms" | "webhook",
    "recipients": ["compliance@company.com"],
    "message": "Urgent: High risk entity detected"
  }
}

Crear Caso

{
  "type": "createCase",
  "createCase": {
    "title": "PEP Investigation Required",
    "description": "Entity flagged as politically exposed person",
    "assignee": "user-uuid"
  }
}

Ejemplos de Solicitudes

Regla KYC Simple - Verificar Tax ID

curl -X POST http://api.gu1.ai/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CNPJ Blocklist Check",
    "description": "Block companies with specific CNPJ",
    "category": "kyb",
    "targetEntityTypes": ["company"],
    "enabled": true,
    "priority": 100,
    "score": 85,
    "conditions": {
      "operator": "AND",
      "conditions": [
        {
          "id": "cond-1",
          "type": "simple",
          "field": "enrichmentData.normalized.taxId",
          "operator": "eq",
          "value": "33.592.510/0001-54",
          "filters": [],
          "countryMetadata": {
            "countryCode": "BR",
            "confidence": 100,
            "manuallySet": true,
            "autoDetected": false,
            "reason": "Selected from BR enrichment fields"
          }
        }
      ]
    },
    "actions": [
      {
        "type": "createAlert",
        "createAlert": {
          "type": "COMPLIANCE",
          "title": "Blocklisted Company Detected",
          "description": "Company CNPJ found in blocklist",
          "severity": "CRITICAL",
          "recipients": ["compliance@company.com"]
        },
        "tags": ["blocklist", "high-priority"]
      },
      {
        "type": "updateEntityStatus",
        "updateEntityStatus": {
          "status": "blocked",
          "reason": "CNPJ in blocklist"
        }
      }
    ],
    "scope": {
      "type": "entity",
      "countries": ["BR"],
      "entityTypes": ["company"]
    },
    "status": "active",
    "evaluationMode": "sync"
  }'

Regla Compleja - Verificación de Sanciones con Múltiples Condiciones

curl -X POST http://api.gu1.ai/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Terrorism Sanctions Check",
    "description": "Detect entities with terrorism-related sanctions",
    "category": "aml",
    "targetEntityTypes": ["person", "company"],
    "enabled": true,
    "priority": 100,
    "score": 95,
    "conditions": {
      "operator": "OR",
      "conditions": [
        {
          "id": "cond-1",
          "type": "simple",
          "field": "enrichmentData.normalized.sanctions.$.type",
          "operator": "in",
          "value": "terrorism",
          "filters": [],
          "countryMetadata": {
            "countryCode": "GLOBAL",
            "confidence": 100,
            "manuallySet": true,
            "autoDetected": false,
            "reason": "Global sanctions field"
          }
        },
        {
          "id": "cond-2",
          "type": "simple",
          "field": "enrichmentData.normalized.sanctioned",
          "operator": "isTrue",
          "value": true,
          "filters": []
        }
      ]
    },
    "actions": [
      {
        "type": "createAlert",
        "createAlert": {
          "type": "AML",
          "title": "Sanctions Match - Immediate Review Required",
          "description": "Entity matched terrorism sanctions list",
          "severity": "CRITICAL",
          "recipients": ["aml-team@company.com"]
        },
        "tags": ["sanctions", "terrorism", "critical"]
      },
      {
        "type": "updateEntityStatus",
        "updateEntityStatus": {
          "status": "blocked",
          "reason": "Terrorism sanctions match"
        }
      },
      {
        "type": "createCase",
        "createCase": {
          "title": "Sanctions Investigation Required",
          "description": "Entity flagged for terrorism-related sanctions",
          "assignee": "compliance-lead-uuid"
        }
      }
    ],
    "scope": {
      "type": "entity",
      "entityTypes": ["person", "company"]
    },
    "status": "active",
    "evaluationMode": "sync",
    "tags": ["sanctions", "aml", "critical"]
  }'

Regla de Monitoreo de Transacciones

curl -X POST http://api.gu1.ai/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Value Transaction Alert",
    "description": "Alert on transactions over $50,000 USD",
    "category": "fraud",
    "targetEntityTypes": ["transaction"],
    "enabled": true,
    "priority": 80,
    "score": 70,
    "conditions": {
      "operator": "AND",
      "conditions": [
        {
          "id": "cond-1",
          "type": "simple",
          "field": "amountInUsd",
          "operator": "gt",
          "value": 50000,
          "filters": []
        },
        {
          "id": "cond-2",
          "type": "simple",
          "field": "status",
          "operator": "eq",
          "value": "PENDING",
          "filters": []
        }
      ]
    },
    "actions": [
      {
        "type": "createAlert",
        "createAlert": {
          "type": "FRAUD",
          "title": "High Value Transaction Detected",
          "description": "Transaction exceeds $50,000 threshold",
          "severity": "HIGH",
          "recipients": ["fraud-team@company.com"]
        },
        "tags": ["high-value", "pending-review"]
      }
    ],
    "scope": {
      "type": "transaction"
    },
    "status": "active",
    "evaluationMode": "sync"
  }'

Respuesta

string

UUID de la regla creada

name

string

Nombre de la regla

description

string

Descripción de la regla

organizationId

string

ID de su organización

status

string

Estado actual de la regla

enabled

boolean

Si la regla está habilitada

version

number

Número de versión de la regla

createdAt

string

Marca de tiempo ISO de creación

createdBy

string

ID del usuario que creó la regla

Ejemplo de Respuesta

{
  "id": "e2cdd639-52cc-4749-9b16-927bfa5dfaea",
  "organizationId": "71e8f908-e032-4fcb-b0ce-ad0cd0ffb236",
  "name": "CNPJ Blocklist Check",
  "description": "Block companies with specific CNPJ",
  "category": "kyb",
  "status": "active",
  "enabled": true,
  "priority": 100,
  "score": 85,
  "conditions": {
    "operator": "AND",
    "conditions": [...]
  },
  "actions": [
    {
      "type": "createAlert",
      "createAlert": {...},
      "tags": ["blocklist", "high-priority"]
    }
  ],
  "scope": {
    "type": "entity",
    "countries": ["BR"],
    "entityTypes": ["company"]
  },
  "targetEntityTypes": ["company"],
  "evaluationMode": "sync",
  "version": 1,
  "previousVersionId": null,
  "tags": [],
  "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
  "createdAt": "2024-12-23T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:00:00.000Z",
  "stats": {
    "executions": 0,
    "successes": 0,
    "failures": 0
  }
}

Respuestas de Error

400 Bad Request - Condición Inválida

{
  "error": "Validation failed",
  "details": {
    "field": "conditions",
    "message": "Invalid operator 'xyz'"
  }
}

400 Bad Request - Campos Requeridos Faltantes

{
  "error": "Validation failed",
  "details": {
    "missingFields": ["name", "targetEntityTypes", "conditions"]
  }
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

Mejores Prácticas

Comience con Modo Shadow: Use status: "shadow" para probar reglas sin afectar producción
Use Nombres Descriptivos: Haga que los nombres de las reglas sean claros y buscables
Establezca Prioridades Apropiadas: Las reglas de mayor prioridad se ejecutan primero (escala 1-100)
Etiquete sus Reglas: Use etiquetas para organización y filtrado
Reglas Específicas por País: Use scope.countries para cumplimiento geo-específico
Pruebe Exhaustivamente: Pruebe las reglas con datos de ejemplo antes de habilitar
Monitoree el Rendimiento: Use modo sync para reglas críticas en tiempo real, async para procesamiento por lotes
Puntúe Estratégicamente: Alinee los puntajes con los umbrales de su matriz de riesgo

Ver También

Referencia de Campos de Condiciones - Lista completa de campos de condición disponibles por tipo de entidad y país
Ejecutar Regla - Probar reglas contra entidades específicas
Listar Reglas - Consultar y filtrar reglas
Actualizar Regla - Modificar reglas existentes

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

​Descripción General

​Endpoint

​Autenticación

​Cuerpo de la Solicitud

​Estructura de Condiciones

​Campos de Condiciones

​Operadores

​Operadores de Comparación

​Operadores de Texto

​Operadores de Array

​Operadores de Lista

​Operadores de Existencia

​Operadores Booleanos

​Sintaxis de Campos de Array

​Filtros

​Acciones

​Crear Alerta

​Actualizar Estado de Entidad

​Enviar Notificación

​Crear Caso

​Ejemplos de Solicitudes

​Regla KYC Simple - Verificar Tax ID

​Regla Compleja - Verificación de Sanciones con Múltiples Condiciones

​Regla de Monitoreo de Transacciones

​Respuesta

​Ejemplo de Respuesta

​Respuestas de Error

​400 Bad Request - Condición Inválida

​400 Bad Request - Campos Requeridos Faltantes

​401 Unauthorized

​Mejores Prácticas

​Ver También

Descripción General

Endpoint

Autenticación

Cuerpo de la Solicitud

Estructura de Condiciones

Campos de Condiciones

Operadores

Operadores de Comparación

Operadores de Texto

Operadores de Array

Operadores de Lista

Operadores de Existencia

Operadores Booleanos

Sintaxis de Campos de Array

Filtros

Acciones

Crear Alerta

Actualizar Estado de Entidad

Enviar Notificación

Crear Caso

Ejemplos de Solicitudes

Regla KYC Simple - Verificar Tax ID

Regla Compleja - Verificación de Sanciones con Múltiples Condiciones

Regla de Monitoreo de Transacciones

Respuesta

Ejemplo de Respuesta

Respuestas de Error

400 Bad Request - Condición Inválida

400 Bad Request - Campos Requeridos Faltantes

401 Unauthorized

Mejores Prácticas

Ver También