Listar entidades (pessoas e empresas)

Visão Geral

Recupera uma lista de entidades com filtragem opcional por tipo, país, identificação fiscal ou ID externo. Retorna até 100 entidades por solicitação.

Endpoint

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

Autenticação

Requer uma chave de API válida no cabeçalho de autorização:

Authorization: Bearer YOUR_API_KEY

Parâmetros de Consulta

type

string

Filtrar por tipo de entidade. Valores disponíveis:

person
company

country

string

Filtrar por código de país ISO 3166-1 alfa-2 (ex: “US”, “BR”, “AR”)

taxId

string

Filtrar por número de identificação fiscal exato

externalId

string

Filtrar por seu identificador externo

Resposta

entities

array

Array de objetos de entidade, cada um contendo:

id - ID interno do gu1
externalId - Seu ID externo
organizationId - ID da sua organização
type - Tipo de entidade
name - Nome da entidade
taxId - Identificação fiscal
countryCode - Código do país
nationality - Nacionalidade (ISO 3166-1 alpha-2 na raiz, ou null)
riskScore - Pontuação de risco (0-100)
riskFactors - Array de fatores de risco
status - Status da entidade
kycVerified - Status de verificação KYC
kycProvider - Nome do provedor KYC
kycData - Dados de verificação KYC
entityData - Dados específicos do tipo
attributes - Atributos personalizados
createdAt - Timestamp de criação
updatedAt - Timestamp da última atualização
deletedAt - Timestamp de exclusão (null se ativo)

Exemplos

Listar Todas as Entidades

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

Filtrar por Tipo de Entidade

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 Identificação Fiscal

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

Exemplo de Resposta

{
  "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

Monitoramento de Entidades de Alto Risco

Consulte todas as entidades e filtre por pontuação de risco em sua aplicação:

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})`);
});

Painel de Conformidade KYC

Obtenha todas as entidades não verificadas para o painel de conformidade:

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álise de Volume de Transações

Liste todas as transações para um período específico (combine com filtragem de data em sua aplicação):

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}`);

Conformidade Específica por País

Obtenha todas as entidades de um país específico para relatórios regulatórios:

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)}")

Paginação

A API atualmente retorna até 100 entidades por solicitação. Se você tiver mais de 100 entidades e precisar de paginação:

Use filtros específicos para restringir os resultados (tipo, país, etc.)
Implemente paginação no lado do cliente armazenando o último timestamp de createdAt
Entre em contato com o suporte para recursos de paginação empresarial

Exemplo com paginação baseada em timestamp:

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;
}

Respostas de Erro

401 Unauthorized

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

500 Internal Server Error

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

Limites

Máximo de resultados por solicitação: 100 entidades
Parâmetros de consulta: Podem ser combinados para filtragem avançada
Limites de taxa: Aplicam-se com base no nível do seu plano

Próximos Passos

Obter Detalhes da Entidade - Recuperar informações completas de uma entidade específica
Criar Entidade - Adicionar novas entidades à sua organização
Atualizar Entidade - Modificar atributos da entidade
Operações em Lote - Processar múltiplas entidades de uma vez

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Consulta

​Resposta

​Exemplos

​Listar Todas as Entidades

​Filtrar por Tipo de Entidade

​Filtrar por País

​Buscar por ID Externo

​Buscar por Identificação Fiscal

​Exemplo de Resposta

​Casos de Uso

​Monitoramento de Entidades de Alto Risco

​Painel de Conformidade KYC

​Análise de Volume de Transações

​Conformidade Específica por País

​Paginação

​Respostas de Erro

​401 Unauthorized

​500 Internal Server Error

​Limites

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Parâmetros de Consulta

Resposta

Exemplos

Listar Todas as Entidades

Filtrar por Tipo de Entidade

Filtrar por País

Buscar por ID Externo

Buscar por Identificação Fiscal

Exemplo de Resposta

Casos de Uso

Monitoramento de Entidades de Alto Risco

Painel de Conformidade KYC

Análise de Volume de Transações

Conformidade Específica por País

Paginação

Respostas de Erro

401 Unauthorized

500 Internal Server Error

Limites

Próximos Passos