Listar empresas

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 empresas

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 empresas com filtragem opcional por país, tax ID ou external ID. Retorna até 100 empresas por requisição.

Endpoint

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

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Parâmetros de Consulta

string

required

Deve ser definido como company para recuperar apenas empresas

string

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

string

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

string

Filtrar pelo seu identificador externo

Resposta

array

Array de objetos de empresa, cada um contendo:

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

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

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

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

import requests

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

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

Filtrar por País

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

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

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

import requests

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

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

Encontrar por External ID

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

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

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

import requests

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

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

Encontrar por Tax ID

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

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

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

import requests

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

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

Exemplo de Resposta

{
  "entities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "business_12345",
      "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
      "type": "company",
      "name": "María González",
      "taxId": "20-12345678-9",
      "countryCode": "AR",
      "riskScore": 25,
      "riskFactors": [
        {
          "factor": "new_business",
          "impact": 15,
          "description": "Business registered within last 30 days"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T14:30:00Z",
        "overallStatus": "approved"
      },
      "entityData": {
        "company": {
          "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 Empresas de Alto Risco

Consulte todas as empresas e filtre por pontuação de risco:

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

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

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

Painel de Conformidade KYB

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

import requests

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

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

print(f"Unverified businesses: {len(unverified)}")
for company in unverified:
    print(f"- {company['name']} ({company['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 empresas
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 Empresa - Recuperar informações completas para uma empresa específica
Criar Empresa - Adicionar novas empresas à sua organização
Atualizar Empresa - Modificar atributos da empresa

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Consulta

​Resposta

​Exemplos

​Listar Todas as Empresas

​Filtrar por País

​Encontrar por External ID

​Encontrar por Tax ID

​Exemplo de Resposta

​Casos de Uso

​Monitoramento de Empresas de Alto Risco

​Painel de Conformidade KYB

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

Filtrar por País

Encontrar por External ID

Encontrar por Tax ID

Exemplo de Resposta

Casos de Uso

Monitoramento de Empresas de Alto Risco

Painel de Conformidade KYB

Respostas de Erro

401 Unauthorized

500 Internal Server Error

Limites

Próximos Passos