Listar entidades (personas y empresas)

Listar

curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "entities": [
    {}
  ]
}

GET

entities

Listar

curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "entities": [
    {}
  ]
}

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

string

Filtrar por tipo de entidad. Valores disponibles:

person
company

string

Filtrar por código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)

string

Filtrar por número de identificación fiscal exacto

string

Filtrar por tu identificador externo

Respuesta

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
nationality - Nacionalidad (ISO 3166-1 alfa-2 en raíz, o null)
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"

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

const data = await response.json();
console.log(`Found ${data.entities.length} entities`);

import requests

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

data = response.json()
print(f"Found {len(data['entities'])} entities")

Filtrar por tipo de entidad

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

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

const data = await response.json();
const companies = data.entities;
console.log(`Found ${companies.length} companies`);

import requests

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

companies = response.json()['entities']
print(f"Found {len(companies)} companies")

Filtrar por país

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

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

const data = await response.json();
console.log(`Found ${data.entities.length} Brazilian companies`);

import requests

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

brazilian_companies = response.json()['entities']
print(f"Found {len(brazilian_companies)} Brazilian companies")

Buscar por ID externo

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

const response = await fetch(
  'http://api.gu1.ai/entities?externalId=customer_12345',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
const entity = data.entities[0]; // External IDs should be unique
console.log('Found entity:', entity.name);

import requests

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

entities = response.json()['entities']
if entities:
    print(f"Found entity: {entities[0]['name']}")

Buscar por identificación fiscal

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

const response = await fetch(
  'http://api.gu1.ai/entities?taxId=20-12345678-9',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
if (data.entities.length > 0) {
  console.log('Entity found:', data.entities[0].name);
}

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'taxId': '20-12345678-9'}
)

entities = response.json()['entities']
if entities:
    print(f"Entity found: {entities[0]['name']}")

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",
      "nationality": "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": "maria.gonzalez@example.com",
        "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",
      "nationality": "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:

Usa filtros específicos para reducir los resultados (tipo, país, etc.)
Implementa paginación del lado del cliente almacenando la última marca de tiempo createdAt
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

Obtener detalles de entidad - Recupera información completa para una entidad específica
Crear entidad - Agrega nuevas entidades a tu organización
Actualizar entidad - Modifica atributos de entidad
Operaciones por lotes - Procesa múltiples entidades a la vez

⌘I

​Descripción general

​Endpoint

​Autenticación

​Parámetros de consulta

​Respuesta

​Ejemplos

​Listar todas las entidades

​Filtrar por tipo de entidad

​Filtrar por país

​Buscar por ID externo

​Buscar por identificación fiscal

​Ejemplo de respuesta

​Casos de uso

​Monitoreo de entidades de alto riesgo

​Panel de cumplimiento KYC

​Análisis de volumen de transacciones

​Cumplimiento específico por país

​Paginación

​Respuestas de error

​401 No autorizado

​500 Error interno del servidor

​Límites

​Próximos pasos

Descripción general

Endpoint

Autenticación

Parámetros de consulta

Respuesta

Ejemplos

Listar todas las entidades

Filtrar por tipo de entidad

Filtrar por país

Buscar por ID externo

Buscar por identificación fiscal

Ejemplo de respuesta

Casos de uso

Monitoreo de entidades de alto riesgo

Panel de cumplimiento KYC

Análisis de volumen de transacciones

Cumplimiento específico por país

Paginación

Respuestas de error

401 No autorizado

500 Error interno del servidor

Límites

Próximos pasos