Skip to main content
GET
http://api.gu1.ai
/
entities
/
{id}
Obtener
curl --request GET \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "externalId": "<string>",
  "organizationId": "<string>",
  "type": "<string>",
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

Descripción general

Recupera detalles completos de una empresa específica por ID, incluyendo el estado de evaluación actual y la valoración de riesgo.

Endpoint

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

Autenticación

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

Parámetros de ruta

id
string
required
El ID único de gu1 de la empresa a recuperar

Respuesta

Devuelve el objeto completo de la empresa con los siguientes campos:
id
string
ID de entidad interno de gu1
externalId
string
Tu identificador externo para esta empresa
organizationId
string
ID de tu organización
type
string
Siempre “company”
name
string
Nombre para mostrar de la empresa
taxId
string
Número de identificación fiscal
countryCode
string
Código de país ISO 3166-1 alpha-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 empresa: active, inactive, under_review, approved, rejected, suspended
kycVerified
boolean
Si se completó la verificación KYB
kycProvider
string
Nombre del proveedor KYB utilizado (si aplica)
kycData
object
Datos de verificación KYB del proveedor
entityData
object
Estructura de datos específica de la empresa
attributes
object
Atributos personalizados como pares clave-valor
currentEvaluation
object
Resultados de la última evaluación AI (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 empresa
updatedAt
string
Marca de tiempo ISO 8601 de última actualización
deletedAt
string
Marca de tiempo ISO 8601 de eliminación lógica (null si no está eliminada)

Ejemplos

Obtener empresa

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

Ejemplo de respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "business_12345",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "company",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskScore": 25,
  "riskFactors": [
    {
      "factor": "new_business",
      "impact": 15,
      "description": "Business 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": {
    "company": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR",
      "occupation": "Software Engineer",
      "income": 85000
    }
  },
  "attributes": {
    "email": "maria.gonzalez@example.com",
    "phone": "+54 11 1234-5678",
    "businessSince": "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
}

Respuestas de error

404 Not Found

{
  "error": "Entity not found"
}

401 Unauthorized

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

500 Internal Server Error

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

Casos de uso

Verificación de KYB

Recupera un negocio para verificar su estado KYB antes de aprobar una transacción:
const company = await fetch(`http://api.gu1.ai/entities/${businessId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (company.kycVerified && company.status === 'active') {
  // Proceder con la transacción
  console.log('Business verified, risk score:', company.riskScore);
} else {
  // Solicitar verificación adicional
  console.log('KYB verification required');
}

Monitoreo de puntuación de riesgo

Verifica la puntuación de riesgo actual y los factores para el monitoreo continuo:
company = requests.get(
    f'http://api.gu1.ai/entities/{company_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

if company['riskScore'] > 70:
    # Alto riesgo - activar debida diligencia mejorada
    print(f"High risk company detected: {company['riskScore']}")
    print("Risk factors:", company['riskFactors'])
elif company['riskScore'] > 40:
    # Riesgo medio - aplicar monitoreo adicional
    print(f"Medium risk company: {company['riskScore']}")

Próximos pasos