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

GET

entities

{id}

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

Visão Geral

Recupera os detalhes completos de uma empresa, incluindo status de avaliação e avaliação de risco. É possível consultar uma empresa de três formas:

Método	Endpoint	Quando usar
Por ID	`GET /entities/{id}`	Você tem o UUID interno da entidade no gu1
Por external ID	`GET /entities/by-external-id/{externalId}`	Você usa seu próprio identificador (ex.: `business_456`)
Por tax ID	`GET /entities/by-tax-id/{taxId}`	Você tem o CNPJ/CUIT e quer buscar a empresa

Os três retornam o mesmo objeto. O escopo da organização é aplicado conforme sua API key.

Endpoints

Obter por ID

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

string

required

ID único (UUID) do gu1 da empresa a recuperar

Obter por external ID

GET http://api.gu1.ai/entities/by-external-id/{externalId}

string

required

Seu identificador externo desta empresa (o valor enviado ao criar a entidade)

Obter por tax ID

GET http://api.gu1.ai/entities/by-tax-id/{taxId}

string

required

Número de identificação fiscal (CNPJ, CUIT, etc.). Deve coincidir com o tax ID armazenado da entidade na sua organização.

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Resposta

Retorna o objeto completo da empresa com os seguintes campos:

string

ID de entidade interno do gu1

string

Seu identificador externo para esta empresa

string

ID da sua organização

string

Sempre “company”

string

Nome de exibição da empresa

string

Número de identificação fiscal

string

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

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 empresa: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Se a verificação KYB foi concluída

string

Nome do provedor KYB usado (se aplicável)

object

Dados de verificação KYB do provedor

object

Estrutura de dados específica da empresa

object

Atributos personalizados como pares chave-valor

object

Últimos resultados de avaliação de IA (null se não houver 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 de criação da empresa

string

Timestamp ISO 8601 da última atualização

string

Timestamp ISO 8601 de exclusão reversível (null se não excluído)

Exemplos

Por ID (UUID)

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 company = await response.json();

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

Por external ID

curl -X GET "http://api.gu1.ai/entities/by-external-id/business_456" \
  -H "Authorization: Bearer YOUR_API_KEY"

const externalId = 'business_456';
const response = await fetch(
  `http://api.gu1.ai/entities/by-external-id/${encodeURIComponent(externalId)}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const company = await response.json();

import requests
response = requests.get(
    "http://api.gu1.ai/entities/by-external-id/business_456",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
company = response.json()

Por tax ID

curl -X GET "http://api.gu1.ai/entities/by-tax-id/30-71234567-8" \
  -H "Authorization: Bearer YOUR_API_KEY"

const taxId = '30-71234567-8';
const response = await fetch(
  `http://api.gu1.ai/entities/by-tax-id/${encodeURIComponent(taxId)}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const company = await response.json();

import requests
response = requests.get(
    "http://api.gu1.ai/entities/by-tax-id/30-71234567-8",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
company = response.json()

Exemplo de Resposta

{
  "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"
    },
    {
      "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": {
    "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",
    "businessSince": "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 Verificação KYB

Recupere uma empresa para verificar seu status KYB antes de aprovar uma transação:

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

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

Monitoramento de Pontuação de Risco

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

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

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

Próximos Passos

Atualizar Empresa - Modificar atributos da empresa
Listar Empresas - Consultar múltiplas empresas
Criar Validação KYB - Iniciar verificação de identidade

​Visão Geral

​Endpoints

​Obter por ID

​Obter por external ID

​Obter por tax ID

​Autenticação

​Resposta

​Exemplos

​Por ID (UUID)

​Por external ID

​Por tax ID

​Exemplo de Resposta

​Respostas de Erro

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Verificação de Verificação KYB

​Monitoramento de Pontuação de Risco

​Próximos Passos

Visão Geral

Endpoints

Obter por ID

Obter por external ID

Obter por tax ID

Autenticação

Resposta

Exemplos

Por ID (UUID)

Por external ID

Por tax ID

Exemplo de Resposta

Respostas de Erro

404 Not Found

401 Unauthorized

500 Internal Server Error

Casos de Uso

Verificação de Verificação KYB

Monitoramento de Pontuação de Risco

Próximos Passos