Listar pessoas

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": [
    {}
  ]
}

Visão Geral

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

Endpoint

GET http://api.gu1.ai/entities?type=person

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Parâmetros de Consulta

string

required

Deve ser definido como person para recuperar apenas pessoas

string

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

string

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

string

Filtrar por seu identificador externo

Resposta

array

Array de objetos pessoa, cada um contendo:

id - ID interno do gu1
externalId - Seu ID externo
organizationId - ID da sua organização
type - Sempre “person”
name - Nome da pessoa
taxId - ID fiscal
countryCode - Código do país
riskScore - Pontuação de risco (0-100)
riskFactors - Array de fatores de risco
status - Status da pessoa
kycVerified - Status de verificação KYC
kycProvider - Nome do provedor KYC
kycData - Dados de verificação KYC
entityData - Dados específicos da pessoa
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 Pessoas

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

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

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

import requests

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

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

Filtrar por País

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

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

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

import requests

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

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

Buscar por ID Externo

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

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

const data = await response.json();
const person = data.entities[0]; // IDs externos devem ser únicos
console.log('Found person:', person.name);

import requests

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

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

Buscar por ID Fiscal

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

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

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

import requests

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

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

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

Casos de Uso

Monitoramento de Clientes de Alto Risco

Consultar todas as pessoas e filtrar por pontuação de risco:

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

const data = await response.json();
const highRiskCustomers = data.entities.filter(e => e.riskScore > 70);

console.log(`Found ${highRiskCustomers.length} high-risk customers requiring review`);
highRiskCustomers.forEach(person => {
  console.log(`- ${person.name} (Risk: ${person.riskScore})`);
});

Painel de Conformidade KYC

Obter todos os clientes não verificados para o painel de conformidade:

import requests

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

persons = response.json()['entities']
unverified = [p for p in persons if not p['kycVerified']]

print(f"Unverified customers: {len(unverified)}")
for person in unverified:
    print(f"- {person['name']} ({person['externalId']})")

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 requisição: 100 pessoas
Parâmetros de consulta: Podem ser combinados para filtragem avançada
Limites de taxa: Aplicam-se com base no seu nível de plano

Próximos Passos

Obter Detalhes da Pessoa - Recuperar informações completas de uma pessoa específica
Criar Pessoa - Adicionar novas pessoas à sua organização
Atualizar Pessoa - Modificar atributos da pessoa

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Consulta

​Resposta

​Exemplos

​Listar Todas as Pessoas

​Filtrar por País

​Buscar por ID Externo

​Buscar por ID Fiscal

​Exemplo de Resposta

​Casos de Uso

​Monitoramento de Clientes de Alto Risco

​Painel de Conformidade KYC

​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 Pessoas

Filtrar por País

Buscar por ID Externo

Buscar por ID Fiscal

Exemplo de Resposta

Casos de Uso

Monitoramento de Clientes de Alto Risco

Painel de Conformidade KYC

Respostas de Erro

401 Unauthorized

500 Internal Server Error

Limites

Próximos Passos