Obtener una 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}

Obtener una 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>"
}

Descripción general

Recupera los detalles completos de una empresa, incluyendo el estado de evaluación y la valoración de riesgo. Podés consultar una empresa de tres formas:

Método	Endpoint	Cuándo usar
Por ID	`GET /entities/{id}`	Tenés el UUID interno de la entidad en gu1
Por external ID	`GET /entities/by-external-id/{externalId}`	Usás tu propio identificador (ej. `business_456`)
Por tax ID	`GET /entities/by-tax-id/{taxId}`	Tenés el CUIT/CNPJ y querés buscar la empresa

Los tres devuelven el mismo objeto. El alcance de organización se aplica según tu API key.

Endpoints

Obtener por ID

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

string

required

ID único (UUID) de gu1 de la empresa a recuperar

Obtener por external ID

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

string

required

Tu identificador externo de esta empresa (el valor enviado al crear la entidad)

Obtener por tax ID

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

string

required

Número de identificación fiscal (CUIT, CNPJ, etc.). Debe coincidir con el tax ID almacenado de la entidad en tu organización.

Autenticación

Requiere una clave API válida en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Respuesta

Devuelve el objeto completo de la empresa con los siguientes campos:

string

ID de entidad interno de gu1

string

Tu identificador externo para esta empresa

string

ID de tu organización

string

Siempre “company”

string

Nombre para mostrar de la empresa

string

Número de identificación fiscal

string

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

number

Puntuación de riesgo calculada de 0 (riesgo bajo) a 100 (riesgo alto)

array

Array de factores de riesgo identificados que contribuyen a la puntuación de riesgo

string

Estado de la empresa: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Si se completó la verificación KYB

string

Nombre del proveedor KYB utilizado (si aplica)

object

Datos de verificación KYB del proveedor

object

Estructura de datos específica de la empresa

object

Atributos personalizados como pares clave-valor

object

Resultados de la última evaluación AI (null si no existe evaluación)

id - ID de evaluación
entityId - ID de entidad
evaluationType - Tipo de evaluación realizada
result - Resultado de la evaluación
confidence - Puntuación de confianza (0-1)
evaluatedAt - Marca de tiempo de la evaluación

string

Marca de tiempo ISO 8601 de creación de la empresa

string

Marca de tiempo ISO 8601 de última actualización

string

Marca de tiempo ISO 8601 de eliminación lógica (null si no está eliminada)

Ejemplos

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()

Ejemplo de respuesta

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

Respuestas de error

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

Verificación de KYB

Recupera un negocio para verificar su estado KYB antes de aprobar una transacción:

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') {
  // Proceder con la transacción
  console.log('Business verified, risk score:', company.riskScore);
} else {
  // Solicitar verificación adicional
  console.log('KYB verification required');
}

Monitoreo de puntuación de riesgo

Verifica la puntuación de riesgo actual y los factores para el monitoreo continuo:

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

if company['riskScore'] > 70:
    # Alto riesgo - activar debida diligencia mejorada
    print(f"High risk company detected: {company['riskScore']}")
    print("Risk factors:", company['riskFactors'])
elif company['riskScore'] > 40:
    # Riesgo medio - aplicar monitoreo adicional
    print(f"Medium risk company: {company['riskScore']}")

Próximos pasos

Actualizar empresa - Modificar atributos de la empresa
Listar empresas - Consultar múltiples empresas
Crear validación KYB - Iniciar verificación de identidad

​Descripción general

​Endpoints

​Obtener por ID

​Obtener por external ID

​Obtener por tax ID

​Autenticación

​Respuesta

​Ejemplos

​Por ID (UUID)

​Por external ID

​Por tax ID

​Ejemplo de respuesta

​Respuestas de error

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Casos de uso

​Verificación de KYB

​Monitoreo de puntuación de riesgo

​Próximos pasos

Descripción general

Endpoints

Obtener por ID

Obtener por external ID

Obtener por tax ID

Autenticación

Respuesta

Ejemplos

Por ID (UUID)

Por external ID

Por tax ID

Ejemplo de respuesta

Respuestas de error

404 Not Found

401 Unauthorized

500 Internal Server Error

Casos de uso

Verificación de KYB

Monitoreo de puntuación de riesgo

Próximos pasos