Skip to main content

​
Descripción general

Crea una nueva entidad con el tipo y atributos especificados. Las entidades representan los objetos de datos principales que deseas analizar para riesgo y cumplimiento.

​
Endpoint

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

​
Autenticación

Requiere una clave de API válida en el encabezado de autorización: 
Authorization: Bearer YOUR_API_KEY

​
Cuerpo de la solicitud

​
type
string
required
El tipo de entidad a crear. Tipos disponibles:
  • person - Persona individual/cliente
  • company - Entidad empresarial
  • transaction - Transacción financiera
  • device - Identificador de dispositivo
  • payment_method - Instrumento de pago
  • location - Ubicación geográfica
  • document - Documento legal
  • account - Cuenta/billetera
  • card - Información de tarjeta
  • alert - Alerta/marcador
  • custom - Tipo de entidad personalizado
  • other - Otros tipos
​
externalId
string
required
Tu identificador único para esta entidad en tu sistema
​
name
string
required
Nombre para mostrar de la entidad
​
countryCode
string
required
Código de país ISO 3166-1 alfa-2 (ej., “US”, “BR”, “AR”)
​
taxId
string
Número de identificación fiscal (validado según el país)
​
attributes
object
Atributos personalizados como pares clave-valor
​
entityData
object
Estructura de datos específica del tipo. Ver ejemplos a continuación para cada tipo de entidad.

​
Estructuras de datos de entidades

​
Entidad Persona

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number
  }
}

​
Entidad Empresa

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "industry": "string",
    "employeeCount": number,
    "revenue": number
  }
}

​
Entidad Transacción

{
  "transaction": {
    "transactionId": "string",
    "type": "string",
    "status": "string",
    "amount": number,
    "currency": "string",
    "paymentMethod": "string",
    "originEntityId": "string",
    "destinationEntityId": "string",
    "transactedAt": "ISO8601 timestamp",
    "riskScore": number,
    "flagged": boolean,
    "category": "string",
    "description": "string"
  }
}

​
Entidad Alerta

{
  "alert": {
    "alertNumber": "string",
    "alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM",
    "severity": "INFO | WARNING | HIGH | CRITICAL",
    "status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE",
    "sourceSystem": "string",
    "triggerRuleId": "string",
    "triggerCondition": "string",
    "affectedEntityId": "string",
    "relatedEntityIds": ["string"],
    "alertedAt": "ISO8601 timestamp",
    "acknowledgedAt": "ISO8601 timestamp",
    "acknowledgedBy": "string",
    "resolvedAt": "ISO8601 timestamp",
    "resolvedBy": "string",
    "resolutionNotes": "string",
    "falsePositiveReason": "string"
  }
}

​
Respuesta

​
success
boolean
Indica si la entidad se creó correctamente
​
entity
object
El objeto de entidad creado incluyendo:
  • id - ID interno de gu1
  • externalId - Tu ID externo
  • organizationId - ID de tu organización
  • type - Tipo de entidad
  • name - Nombre de la entidad
  • riskScore - Puntuación de riesgo inicial (0-100)
  • status - Estado de la entidad
  • entityData - Datos específicos del tipo
  • attributes - Atributos personalizados
  • createdAt - Marca de tiempo de creación
  • updatedAt - Marca de tiempo de última actualización

​
Ejemplos

​
Crear Entidad Persona (KYC)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "externalId": "customer_12345",
    "name": "María González",
    "countryCode": "AR",
    "taxId": "20-12345678-9",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "attributes": {
      "email": "[email protected]",
      "phone": "+54 11 1234-5678",
      "customerSince": "2024-01-15"
    }
  }'

​
Crear Entidad Empresa (KYB)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "externalId": "company_789",
    "name": "Tech Solutions S.A.",
    "countryCode": "BR",
    "taxId": "12.345.678/0001-90",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "registeredAddress": "Av. Paulista, 1000, São Paulo",
      "partnershipTier": "gold"
    }
  }'

​
Crear Entidad Transacción (Detección de fraude)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transaction",
    "externalId": "txn_98765",
    "name": "Wire Transfer - $50,000",
    "countryCode": "US",
    "entityData": {
      "transaction": {
        "transactionId": "txn_98765",
        "type": "wire_transfer",
        "status": "completed",
        "amount": 50000,
        "currency": "USD",
        "paymentMethod": "bank_transfer",
        "originEntityId": "customer_12345",
        "destinationEntityId": "merchant_456",
        "transactedAt": "2024-10-03T14:30:00Z",
        "category": "business_payment",
        "description": "Payment for professional services"
      }
    }
  }'

​
Ejemplo de respuesta

{
  "success": true,
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "person",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 25,
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "attributes": {
      "email": "[email protected]",
      "phone": "+54 11 1234-5678",
      "customerSince": "2024-01-15"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  }
}

​
Respuestas de Error

​
400 Bad Request - ID Fiscal Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Formato de CUIT inválido. Por favor verifica el formato e intenta nuevamente.",
    "details": {
      "field": "taxId",
      "taxIdName": "CUIT",
      "providedValue": "20-12345678-9"
    }
  },
  "entity": null
}

​
400 Bad Request - Campos Requeridos Faltantes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Faltan campos requeridos para la creación de la empresa",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

​
409 Conflict - Entidad Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Ya existe una entidad con este external_id",
    "details": {
      "field": "external_id",
      "value": "customer_12345",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

​
429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Has excedido tu límite de velocidad de la API. Por favor espera antes de hacer más solicitudes.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Ocurrió un error inesperado al crear la entidad",
    "details": {
      "message": "Database connection timeout"
    }
  },
  "entity": null
}

​
Próximos pasos

Después de crear una entidad, puedes:
  1. Solicitar análisis de IA - Obtener evaluación de riesgo automatizada
  2. Listar entidades - Consultar tus entidades
  3. Obtener detalles de entidad - Recuperar información completa de la entidad
  4. Aplicar reglas - Ejecutar reglas de cumplimiento y riesgo