Skip to main content
GET
http://api.gu1.ai
/
entities
/
{id}
Obter
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>"
}

Visão Geral

Recupera detalhes completos de uma pessoa específica por ID, incluindo status de avaliação atual e avaliação de risco.

Endpoint

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

Autenticação

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

Parâmetros de Caminho

id
string
required
O ID único do gu1 da pessoa a recuperar

Resposta

Retorna o objeto pessoa completo com os seguintes campos:
id
string
ID de entidade interno do gu1
externalId
string
Seu identificador externo para esta pessoa
organizationId
string
ID da sua organização
type
string
Sempre “person”
name
string
Nome de exibição da pessoa
taxId
string
Número de identificação fiscal
countryCode
string
Código de país ISO 3166-1 alpha-2
riskScore
number
Pontuação de risco calculada de 0 (baixo risco) a 100 (alto risco)
riskFactors
array
Array de fatores de risco identificados que contribuem para a pontuação de risco
status
string
Status da pessoa: active, inactive, under_review, approved, rejected, suspended
kycVerified
boolean
Se a verificação KYC foi concluída
kycProvider
string
Nome do provedor KYC usado (se aplicável)
kycData
object
Dados de verificação KYC do provedor
entityData
object
Estrutura de dados específica da pessoa
attributes
object
Atributos personalizados como pares chave-valor
currentEvaluation
object
Resultados da avaliação AI mais recente (null se não existir avaliação)
  • id - ID da avaliação
  • entityId - ID da entidade
  • evaluationType - Tipo de avaliação realizada
  • result - Resultado da avaliação
  • confidence - Pontuação de confiança (0-1)
  • evaluatedAt - Timestamp da avaliação
createdAt
string
Timestamp ISO 8601 da criação da pessoa
updatedAt
string
Timestamp ISO 8601 da última atualização
deletedAt
string
Timestamp ISO 8601 da exclusão suave (null se não excluído)

Exemplos

Obter Pessoa

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

Exemplo de Resposta

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

Respostas de Erro

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

Verificação de KYC

Recuperar um cliente para verificar seu status KYC antes de aprovar uma transação:
const person = await fetch(`http://api.gu1.ai/entities/${customerId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (person.kycVerified && person.status === 'active') {
  // Prosseguir com a transação
  console.log('Customer verified, risk score:', person.riskScore);
} else {
  // Solicitar verificação adicional
  console.log('KYC verification required');
}

Monitoramento de Pontuação de Risco

Verificar a pontuação de risco atual e fatores para monitoramento contínuo:
person = requests.get(
    f'http://api.gu1.ai/entities/{person_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

if person['riskScore'] > 70:
    # Alto risco - acionar diligência aprimorada
    print(f"High risk person detected: {person['riskScore']}")
    print("Risk factors:", person['riskFactors'])
elif person['riskScore'] > 40:
    # Risco médio - aplicar monitoramento adicional
    print(f"Medium risk person: {person['riskScore']}")

Próximos Passos