Skip to main content

​
Descripción general

Recupera una lista de entidades con filtrado opcional por tipo, país, identificación fiscal o ID externo. Devuelve hasta 100 entidades por solicitud.

​
Endpoint

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

​
Autenticación

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

​
Parámetros de consulta

​
type
string
Filtrar por tipo de entidad. Valores disponibles:
  • person
  • company
  • transaction
  • device
  • payment_method
  • location
  • document
  • account
  • card
  • alert
  • custom
  • other
​
country
string
Filtrar por código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)
​
taxId
string
Filtrar por número de identificación fiscal exacto
​
externalId
string
Filtrar por tu identificador externo

​
Respuesta

​
entities
array
Array de objetos de entidad, cada uno contiene:
  • id - ID interno de gu1
  • externalId - Tu ID externo
  • organizationId - ID de tu organización
  • type - Tipo de entidad
  • name - Nombre de la entidad
  • taxId - ID fiscal
  • countryCode - Código de país
  • riskScore - Puntuación de riesgo (0-100)
  • riskFactors - Array de factores de riesgo
  • status - Estado de la entidad
  • kycVerified - Estado de verificación KYC
  • kycProvider - Nombre del proveedor KYC
  • kycData - Datos de verificación KYC
  • entityData - Datos específicos del tipo
  • attributes - Atributos personalizados
  • createdAt - Marca de tiempo de creación
  • updatedAt - Marca de tiempo de última actualización
  • deletedAt - Marca de tiempo de eliminación (null si está activa)

​
Ejemplos

​
Listar todas las entidades

curl -X GET "http://api.gu1.ai/entities" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por tipo de entidad

curl -X GET "http://api.gu1.ai/entities?type=company" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por país

curl -X GET "http://api.gu1.ai/entities?country=BR&type=company" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Buscar por ID externo

curl -X GET "http://api.gu1.ai/entities?externalId=customer_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Buscar por identificación fiscal

curl -X GET "http://api.gu1.ai/entities?taxId=20-12345678-9" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Ejemplo de respuesta

{
  "entities": [
    {
      "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"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T14:30:00Z",
        "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"
      },
      "createdAt": "2024-10-03T14:30:00.000Z",
      "updatedAt": "2024-10-03T14:35:00.000Z",
      "deletedAt": null
    },
    {
      "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"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T15:00:00Z",
        "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"
      },
      "createdAt": "2024-10-03T15:00:00.000Z",
      "updatedAt": "2024-10-03T15:05:00.000Z",
      "deletedAt": null
    }
  ]
}

​
Casos de uso

​
Monitoreo de entidades de alto riesgo

Consulta todas las entidades y filtra por puntuación de riesgo en tu aplicación: 
const response = await fetch('http://api.gu1.ai/entities', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
const highRiskEntities = data.entities.filter(e => e.riskScore > 70);

console.log(`Found ${highRiskEntities.length} high-risk entities requiring review`);
highRiskEntities.forEach(entity => {
  console.log(`- ${entity.name} (Risk: ${entity.riskScore})`);
});

​
Panel de cumplimiento KYC

Obtén todas las entidades no verificadas para el panel de cumplimiento: 
import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'type': 'person'}
)

entities = response.json()['entities']
unverified = [e for e in entities if not e['kycVerified']]

print(f"Unverified customers: {len(unverified)}")
for entity in unverified:
    print(f"- {entity['name']} ({entity['externalId']})")

​
Análisis de volumen de transacciones

Lista todas las transacciones para un período específico (combina con filtrado de fechas en tu aplicación): 
const response = await fetch(
  'http://api.gu1.ai/entities?type=transaction',
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

const data = await response.json();
const transactions = data.entities;

const totalVolume = transactions.reduce((sum, txn) => {
  return sum + (txn.entityData?.transaction?.amount || 0);
}, 0);

console.log(`Total transaction volume: $${totalVolume.toLocaleString()}`);
console.log(`Transaction count: ${transactions.length}`);

​
Cumplimiento específico por país

Obtén todas las entidades de un país específico para reportes regulatorios: 
import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'country': 'US'}
)

us_entities = response.json()['entities']

# Separate by type
companies = [e for e in us_entities if e['type'] == 'company']
persons = [e for e in us_entities if e['type'] == 'person']

print(f"US Companies: {len(companies)}")
print(f"US Persons: {len(persons)}")

​
Paginación

La API actualmente devuelve hasta 100 entidades por solicitud. Si tienes más de 100 entidades y necesitas paginación:
  1. Usa filtros específicos para reducir los resultados (tipo, país, etc.)
  2. Implementa paginación del lado del cliente almacenando la última marca de tiempo createdAt
  3. Contacta con soporte para funciones de paginación empresarial
Ejemplo con paginación basada en marca de tiempo: 
let allEntities = [];
let lastCreatedAt = null;

async function fetchAllEntities() {
  const response = await fetch('http://api.gu1.ai/entities?type=company', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });

  const data = await response.json();

  // Filter by last timestamp if this is not the first batch
  const newEntities = lastCreatedAt
    ? data.entities.filter(e => new Date(e.createdAt) > new Date(lastCreatedAt))
    : data.entities;

  allEntities = allEntities.concat(newEntities);

  if (newEntities.length > 0) {
    lastCreatedAt = newEntities[newEntities.length - 1].createdAt;
  }

  return allEntities;
}

​
Respuestas de error

​
401 No autorizado

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

​
500 Error interno del servidor

{
  "error": "Failed to search entities"
}

​
Límites

  • Máximo de resultados por solicitud: 100 entidades
  • Parámetros de consulta: Se pueden combinar para filtrado avanzado
  • Límites de tasa: Se aplican según el nivel de tu plan

​
Próximos pasos