Obtener Entidad

Descripción General

Recupera los detalles completos de una entidad específica por ID, incluyendo su estado de evaluación actual y evaluación de riesgo.

Endpoint

GET http://api.gu1.ai/entities/{id}

Autenticación

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

Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

string

required

El ID único de gu1 de la entidad a recuperar

Respuesta

Devuelve el objeto de entidad completo con los siguientes campos:

string

ID interno de entidad de gu1

externalId

string

Su identificador externo para esta entidad

organizationId

string

Su ID de organización

type

string

Tipo de entidad (person, company, transaction, etc.)

name

string

Nombre de visualización de la entidad

taxId

string

Número de identificación tributaria

countryCode

string

Código de país ISO 3166-1 alfa-2

riskScore

number

Puntuación de riesgo calculada de 0 (riesgo bajo) a 100 (riesgo alto)

riskFactors

array

Array de factores de riesgo identificados que contribuyen a la puntuación de riesgo

status

string

Estado de la entidad: active, inactive, under_review, approved, rejected, suspended

kycVerified

boolean

Si se ha completado la verificación KYC

kycProvider

string

Nombre del proveedor KYC utilizado (si aplica)

kycData

object

Datos de verificación KYC del proveedor

entityData

object

Estructura de datos de entidad específica del tipo

attributes

object

Atributos personalizados como pares clave-valor

currentEvaluation

object

Últimos resultados de evaluación de IA (null si no existe evaluación)

id - ID de evaluación
entityId - ID de entidad
evaluationType - Tipo de evaluación realizada
result - Resultado de la evaluación
confidence - Puntuación de confianza (0-1)
evaluatedAt - Marca de tiempo de la evaluación

createdAt

string

Marca de tiempo ISO 8601 de creación de la entidad

updatedAt

string

Marca de tiempo ISO 8601 de la última actualización

deletedAt

string

Marca de tiempo ISO 8601 de eliminación suave (null si no está eliminada)

Ejemplos

Obtener Entidad de Persona

curl -X GET http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de Respuesta - Entidad de Persona

{
  "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,
  "riskFactors": [
    {
      "factor": "new_customer",
      "impact": 15,
      "description": "Customer registered within last 30 days"
    },
    {
      "factor": "high_income_occupation",
      "impact": -10,
      "description": "Professional occupation with verified income"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T14:30:00Z",
    "documentsVerified": ["national_id", "proof_of_address"],
    "livenessCheck": "passed",
    "overallStatus": "approved"
  },
  "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",
    "accountTier": "premium"
  },
  "currentEvaluation": {
    "id": "eval_abc123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "evaluationType": "risk_assessment",
    "result": {
      "overallRisk": "low",
      "amlRisk": "low",
      "fraudRisk": "low",
      "complianceScore": 95,
      "recommendation": "approve"
    },
    "confidence": 0.92,
    "evaluatedAt": "2024-10-03T14:35:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:35:00.000Z",
  "deletedAt": null
}

Ejemplo de Respuesta - Entidad de Empresa

{
  "id": "660e9511-f39c-52e5-b827-557766551111",
  "externalId": "company_789",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "12.345.678/0001-90",
  "countryCode": "BR",
  "riskScore": 35,
  "riskFactors": [
    {
      "factor": "new_business",
      "impact": 20,
      "description": "Company incorporated less than 2 years ago"
    },
    {
      "factor": "high_growth_industry",
      "impact": 15,
      "description": "Operating in high-growth tech sector"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T15:00:00Z",
    "documentsVerified": ["articles_of_incorporation", "tax_registration", "beneficial_owners"],
    "overallStatus": "approved"
  },
  "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",
    "monthlyVolume": 250000
  },
  "currentEvaluation": {
    "id": "eval_xyz789",
    "entityId": "660e9511-f39c-52e5-b827-557766551111",
    "evaluationType": "kyb_assessment",
    "result": {
      "overallRisk": "medium",
      "financialRisk": "low",
      "reputationalRisk": "low",
      "complianceScore": 88,
      "recommendation": "approve_with_monitoring"
    },
    "confidence": 0.87,
    "evaluatedAt": "2024-10-03T15:05:00Z"
  },
  "createdAt": "2024-10-03T15:00:00.000Z",
  "updatedAt": "2024-10-03T15:05:00.000Z",
  "deletedAt": null
}

Ejemplo de Respuesta - Entidad de Transacción

{
  "id": "770f0622-g40d-63f6-c938-668877662222",
  "externalId": "txn_98765",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "transaction",
  "name": "Wire Transfer - $50,000",
  "taxId": null,
  "countryCode": "US",
  "riskScore": 45,
  "riskFactors": [
    {
      "factor": "high_value_transaction",
      "impact": 30,
      "description": "Transaction amount exceeds $10,000 threshold"
    },
    {
      "factor": "wire_transfer",
      "impact": 15,
      "description": "Wire transfers carry higher fraud risk"
    }
  ],
  "status": "under_review",
  "kycVerified": false,
  "kycProvider": null,
  "kycData": null,
  "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",
      "riskScore": 45,
      "flagged": true,
      "category": "business_payment",
      "description": "Payment for professional services"
    }
  },
  "attributes": {
    "ipAddress": "192.168.1.100",
    "deviceId": "device_abc123",
    "userAgent": "Mozilla/5.0...",
    "referenceNumber": "REF-2024-10-03-001"
  },
  "currentEvaluation": {
    "id": "eval_def456",
    "entityId": "770f0622-g40d-63f6-c938-668877662222",
    "evaluationType": "fraud_detection",
    "result": {
      "overallRisk": "medium",
      "fraudProbability": 0.35,
      "amlFlags": ["high_value", "cross_border"],
      "recommendation": "manual_review"
    },
    "confidence": 0.78,
    "evaluatedAt": "2024-10-03T14:32:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:32:00.000Z",
  "deletedAt": null
}

Respuestas de Error

404 No Encontrado

{
  "error": "Entity not found"
}

401 No Autorizado

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

500 Error Interno del Servidor

{
  "error": "Failed to fetch entity"
}

Casos de Uso

Verificación de Estado KYC

Recuperar una entidad de cliente para verificar su estado KYC antes de aprobar una transacción:

const entity = await fetch(`http://api.gu1.ai/entities/${customerId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (entity.kycVerified && entity.status === 'active') {
  // Proceder con la transacción
  console.log('Cliente verificado, puntuación de riesgo:', entity.riskScore);
} else {
  // Solicitar verificación adicional
  console.log('Se requiere verificación KYC');
}

Monitoreo de Puntuación de Riesgo

Verificar la puntuación de riesgo actual y los factores para monitoreo continuo:

entity = requests.get(
    f'http://api.gu1.ai/entities/{entity_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

if entity['riskScore'] > 70:
    # Alto riesgo - activar debida diligencia mejorada
    print(f"Entidad de alto riesgo detectada: {entity['riskScore']}")
    print("Factores de riesgo:", entity['riskFactors'])
elif entity['riskScore'] > 40:
    # Riesgo medio - aplicar monitoreo adicional
    print(f"Entidad de riesgo medio: {entity['riskScore']}")

Análisis de Resultados de Evaluación

Acceder a la última evaluación de IA para comprender los detalles de la evaluación:

const entity = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (entity.currentEvaluation) {
  console.log('Confianza de la evaluación:', entity.currentEvaluation.confidence);
  console.log('Recomendación:', entity.currentEvaluation.result.recommendation);
  console.log('Evaluación de riesgo:', entity.currentEvaluation.result.overallRisk);
}

Próximos Pasos

Actualizar Entidad - Modificar atributos de entidad
Listar Entidades - Consultar múltiples entidades
Solicitar Análisis de IA - Obtener evaluación de riesgo
Ver Línea de Tiempo de Entidad - Ver historial de entidad

Comenzando

Referencia API

Ingesta de Datos

Entidades

Documentos

Conozca Su Negocio (KYB)

Conozca Su Cliente (KYC)

Monitoreo de Transacciones

Tutoriales Interactivos

Obtener Entidad

Descripción General

Endpoint

Autenticación

Parámetros de Ruta

Respuesta

Ejemplos

Obtener Entidad de Persona

Ejemplo de Respuesta - Entidad de Persona

Ejemplo de Respuesta - Entidad de Empresa

Ejemplo de Respuesta - Entidad de Transacción

Respuestas de Error

404 No Encontrado

401 No Autorizado

500 Error Interno del Servidor

Casos de Uso

Verificación de Estado KYC

Monitoreo de Puntuación de Riesgo

Análisis de Resultados de Evaluación

Próximos Pasos

Comenzando

Referencia API

Ingesta de Datos

Entidades

Documentos

Conozca Su Negocio (KYB)

Conozca Su Cliente (KYC)

Monitoreo de Transacciones

Tutoriales Interactivos

​Descripción General

​Endpoint

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplos

​Obtener Entidad de Persona

​Ejemplo de Respuesta - Entidad de Persona

​Ejemplo de Respuesta - Entidad de Empresa

​Ejemplo de Respuesta - Entidad de Transacción

​Respuestas de Error

​404 No Encontrado

​401 No Autorizado

​500 Error Interno del Servidor

​Casos de Uso

​Verificación de Estado KYC

​Monitoreo de Puntuación de Riesgo

​Análisis de Resultados de Evaluación

​Próximos Pasos

Descripción General

Endpoint

Autenticación

Parámetros de Ruta

Respuesta

Ejemplos

Obtener Entidad de Persona

Ejemplo de Respuesta - Entidad de Persona

Ejemplo de Respuesta - Entidad de Empresa

Ejemplo de Respuesta - Entidad de Transacción

Respuestas de Error

404 No Encontrado

401 No Autorizado

500 Error Interno del Servidor

Casos de Uso

Verificación de Estado KYC

Monitoreo de Puntuación de Riesgo

Análisis de Resultados de Evaluación

Próximos Pasos