Obter uma entidade por ID

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

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

fetch('http://api.gu1.ai/entities/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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

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

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

fetch('http://api.gu1.ai/entities/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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

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

string

Seu identificador externo para esta entidade

string

ID da sua organização

string

Tipo de entidade (person ou company)

string

Nome de exibição da entidade

string

Número de identificação fiscal

string

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

string | null

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

number

Pontuação de risco calculada de 0 (baixo risco) a 100 (alto risco)

array

Array de fatores de risco identificados que contribuem para a pontuação de risco

string

Status da entidade: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Se a verificação KYC foi concluída

string

Nome do provedor KYC utilizado (se aplicável)

object

Dados de verificação KYC do provedor

object

Estrutura de dados específica do tipo de entidade

object

Atributos personalizados, armazenados exatamente como enviados. Valores escalares/array ficam na raiz (sem categoria); um objeto aninhado agrupa suas chaves internas sob essa categoria (ex.: { "contact": { "phone": "..." } }). A resposta retorna a mesma forma que foi escrita — o input aninhado não é achatado. Regras e webhooks leem a forma armazenada (attributes.phone ou attributes.contact.phone).

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

string

Timestamp ISO 8601 da criação da entidade

string

Timestamp ISO 8601 da última atualização

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"

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const entity = await response.json();
console.log(entity);

import requests

response = requests.get(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

entity = response.json()
print(entity)

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
Obter enrichment normalizado - Dossiê canônico dos enrichments
Obter dados atuais de enrichment - Mapped/raw por código de integração

​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