Obter uma entidade por ID

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>",
  "nationality": {},
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

GET

entities

{id}

Obter uma entidade por ID

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>",
  "nationality": {},
  "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 entidade específica por ID, incluindo seu status de avaliação atual e análise de risco.

Endpoint

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

Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Parâmetros de Path

string

required

O ID único gu1 da entidade a ser recuperada

Resposta

Retorna o objeto completo da entidade com os seguintes campos:

string

ID interno da entidade no gu1

externalId

string

Seu identificador externo para esta entidade

organizationId

string

ID da sua organização

type

string

Tipo de entidade (person ou company)

name

string

Nome de exibição da entidade

taxId

string

Número de identificação fiscal

countryCode

string

Código de país ISO 3166-1 alpha-2

nationality

string | null

Nacionalidade na raiz (ISO 3166-1 alpha-2, desnormalizada; pode ser null em registros antigos). Complementa entityData.person.nationality / entityData.company.nationality.

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 entidade: active, inactive, under_review, approved, rejected, suspended

kycVerified

boolean

Se a verificação KYC foi concluída

kycProvider

string

Nome do provedor KYC utilizado (se aplicável)

kycData

object

Dados de verificação KYC do provedor

entityData

object

Estrutura de dados específica do tipo de entidade

attributes

object

Atributos personalizados como pares chave-valor

currentEvaluation

object

Resultados da última avaliação de IA (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 entidade

updatedAt

string

Timestamp ISO 8601 da última atualização

deletedAt

string

Timestamp ISO 8601 da exclusão lógica (null se não excluída)

Exemplos

Obter Entidade Pessoa

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

Exemplo de Resposta - Entidade Pessoa

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

Exemplo de Resposta - Entidade Empresa

{
  "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"
    },
    {
      "factor": "high_growth_industry",
      "impact": 15,
      "description": "Operating in high-growth tech sector"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T15:00:00Z",
    "documentsVerified": ["articles_of_incorporation", "tax_registration", "beneficial_owners"],
    "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",
    "partnershipTier": "gold",
    "monthlyVolume": 250000
  },
  "currentEvaluation": {
    "id": "eval_xyz789",
    "entityId": "660e9511-f39c-52e5-b827-557766551111",
    "evaluationType": "kyb_assessment",
    "result": {
      "overallRisk": "medium",
      "financialRisk": "low",
      "reputationalRisk": "low",
      "complianceScore": 88,
      "recommendation": "approve_with_monitoring"
    },
    "confidence": 0.87,
    "evaluatedAt": "2024-10-03T15:05:00Z"
  },
  "createdAt": "2024-10-03T15:00:00.000Z",
  "updatedAt": "2024-10-03T15:05:00.000Z",
  "deletedAt": null
}

Exemplo de Resposta - Entidade Transação

{
  "id": "770f0622-g40d-63f6-c938-668877662222",
  "externalId": "txn_98765",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "transaction",
  "name": "Wire Transfer - $50,000",
  "taxId": null,
  "countryCode": "US",
  "nationality": null,
  "riskScore": 45,
  "riskFactors": [
    {
      "factor": "high_value_transaction",
      "impact": 30,
      "description": "Transaction amount exceeds $10,000 threshold"
    },
    {
      "factor": "wire_transfer",
      "impact": 15,
      "description": "Wire transfers carry higher fraud risk"
    }
  ],
  "status": "under_review",
  "kycVerified": false,
  "kycProvider": null,
  "kycData": null,
  "entityData": {
    "transaction": {
      "transactionId": "txn_98765",
      "type": "wire_transfer",
      "status": "completed",
      "amount": 50000,
      "currency": "USD",
      "paymentMethod": "bank_transfer",
      "originEntityId": "customer_12345",
      "destinationEntityId": "merchant_456",
      "transactedAt": "2024-10-03T14:30:00Z",
      "riskScore": 45,
      "flagged": true,
      "category": "business_payment",
      "description": "Payment for professional services"
    }
  },
  "attributes": {
    "ipAddress": "192.168.1.100",
    "deviceId": "device_abc123",
    "userAgent": "Mozilla/5.0...",
    "referenceNumber": "REF-2024-10-03-001"
  },
  "currentEvaluation": {
    "id": "eval_def456",
    "entityId": "770f0622-g40d-63f6-c938-668877662222",
    "evaluationType": "fraud_detection",
    "result": {
      "overallRisk": "medium",
      "fraudProbability": 0.35,
      "amlFlags": ["high_value", "cross_border"],
      "recommendation": "manual_review"
    },
    "confidence": 0.78,
    "evaluatedAt": "2024-10-03T14:32:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:32: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 uma entidade de cliente para verificar seu status KYC antes de aprovar uma transação:

const entity = await fetch(`http://api.gu1.ai/entities/${customerId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (entity.kycVerified && entity.status === 'active') {
  // Prosseguir com a transação
  console.log('Cliente verificado, pontuação de risco:', entity.riskScore);
} else {
  // Solicitar verificação adicional
  console.log('Verificação KYC necessária');
}

Monitoramento de Pontuação de Risco

Verificar a pontuação de risco atual e os fatores para monitoramento contínuo:

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

if entity['riskScore'] > 70:
    # Alto risco - acionar due diligence reforçada
    print(f"Entidade de alto risco detectada: {entity['riskScore']}")
    print("Fatores de risco:", entity['riskFactors'])
elif entity['riskScore'] > 40:
    # Risco médio - aplicar monitoramento adicional
    print(f"Entidade de risco médio: {entity['riskScore']}")

Análise de Resultados de Avaliação

Acessar a última avaliação de IA para entender os detalhes da análise:

const entity = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (entity.currentEvaluation) {
  console.log('Confiança da avaliação:', entity.currentEvaluation.confidence);
  console.log('Recomendação:', entity.currentEvaluation.result.recommendation);
  console.log('Avaliação de risco:', entity.currentEvaluation.result.overallRisk);
}

Próximos Passos

Atualizar Entidade - Modificar atributos da entidade
Listar Entidades - Consultar múltiplas entidades
Solicitar Análise de IA - Obter avaliação de risco
Visualizar Linha do Tempo da Entidade - Ver histórico da entidade

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Path

​Resposta

​Exemplos

​Obter Entidade Pessoa

​Exemplo de Resposta - Entidade Pessoa

​Exemplo de Resposta - Entidade Empresa

​Exemplo de Resposta - Entidade Transação

​Respostas de Erro

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Verificação de KYC

​Monitoramento de Pontuação de Risco

​Análise de Resultados de Avaliação

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Parâmetros de Path

Resposta

Exemplos

Obter Entidade Pessoa

Exemplo de Resposta - Entidade Pessoa

Exemplo de Resposta - Entidade Empresa

Exemplo de Resposta - Entidade Transação

Respostas de Erro

404 Not Found

401 Unauthorized

500 Internal Server Error

Casos de Uso

Verificação de KYC

Monitoramento de Pontuação de Risco

Análise de Resultados de Avaliação

Próximos Passos