Obtener socios materializados
curl --request GET \
--url http://api.gu1.ai/entities/{id}/shareholders \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/shareholders"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/shareholders', 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}/shareholders",
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}/shareholders"
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))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/shareholders")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/shareholders")
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{
"entityId": "<string>",
"shareholders": [
{}
],
"totalShareholders": 123,
"relationships": [
{}
],
"totalRelationships": 123
}Referencia API
Obtener socios materializados
Lee los socios y el resto de relaciones ya materializados de una entidad, sin volver a ejecutar un enrichment.
GET
/
entities
/
{id}
/
shareholders
Obtener socios materializados
curl --request GET \
--url http://api.gu1.ai/entities/{id}/shareholders \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/shareholders"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/shareholders', 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}/shareholders",
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}/shareholders"
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))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/shareholders")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/shareholders")
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{
"entityId": "<string>",
"shareholders": [
{}
],
"totalShareholders": 123,
"relationships": [
{}
],
"totalRelationships": 123
}Visión general
Devuelve los socios y las demás relaciones ya guardados de una persona o empresa. Es una lectura deentities y entity_relationships. No llama integraciones, no materializa filas nuevas y no consume créditos de enrichment.
Úselo después de la creación automática cuando necesite los mismos socios más tarde. data.shareholders de ese POST es solo la respuesta del alta (id, name, taxId, type de las fichas hijas materializadas en esa corrida). El porcentaje y los roles quedan en la relación y se leen acá en shareholderInfo.
Las filas de QSA que nunca se convirtieron en entidades (por ejemplo un documento enmascarado) no entran. Siguen en Obtener enrichment normalizado.
Exige el permiso granular entities:read en la API key (fallback legacy entities:read).
Endpoints
Los dos devuelven el mismo body. La organización sale de la API key.GET https://api.gu1.ai/entities/{id}/shareholders
GET https://api.gu1.ai/entities/by-tax-id/{taxId}/shareholders
Autenticación
Authorization: Bearer YOUR_API_KEY
Parámetros de ruta
string
UUID de la entidad. Úselo en
GET /entities/{id}/shareholders.string
Identificador fiscal guardado en la entidad (CNPJ, CUIT, etc.). Los dígitos se comparan igual que en obtener por tax id. Úselo en
GET /entities/by-tax-id/{taxId}/shareholders. Si hay varias filas, se usa la creada más recientemente.Parámetros de query
integer
default:"1"
Cuántos niveles de propiedad recorrer en
shareholders. 1 son solo los dueños directos. Máximo 5. La lista es plana y se deduplica por id de entidad. Las empresas anidadas se expanden solo si depth es mayor que 1. relationships sigue siendo un salto desde la entidad consultada.integer
default:"100"
Tamaño de página aplicado por separado a
shareholders y a relationships. Máximo 500.integer
default:"0"
Cuántos ítems omitir en cada array. Se aplica después de los filtros de socios.
string
Deja solo socios cuyo tipo sea
person o company. Los vínculos de relationships no se filtran.string
Identificador fiscal exacto del socio. Se comparan los dígitos, así
123.456.789-00 coincide con 12345678900.number
riskScore mínimo, inclusive. Los socios con riskScore: null quedan fuera si se envía este parámetro o maxRiskScore.number
riskScore máximo, inclusive.number
Porcentaje de participación mínimo, inclusive. Los socios sin porcentaje guardado quedan fuera si se envía este parámetro o
maxOwnershipPercentage.number
Porcentaje de participación máximo, inclusive.
shareholders, después de recorrer depth y antes de limit / offset. Una empresa que no cumple el filtro igual se recorre cuando depth es mayor que 1, así un dueño que sí cumple debajo de ella puede aparecer. minRiskScore no puede ser mayor que maxRiskScore; lo mismo vale para los límites de porcentaje (400).
Respuesta
200 con { "success": true, "data": { ... } }.
Los vínculos de propiedad usan dirección socio = source, entidad poseída = target, y un tipo shareholder, owns o controls. Esos van en shareholders. El resto de vínculos no borrados en los que esta entidad es source o target van en relationships.
string
UUID de la entidad consultada.
array
Dueños materializados.
id,name,taxId,type,riskScore— la entidad relacionada.riskScoreesnullsi el socio no tiene score.taxIdesnullsi la API key no tieneentities:read_sensitive.shareholderInfo.percentage—metadata.shareholdingPercentage, onullshareholderInfo.roles—metadata.roles(array vacío si no hay)shareholderInfo.isActive—metadata.isActive, onull
number
Socios que cumplen los filtros, antes de
limit / offset.array
Otras contrapartes materializadas.
id,name,taxId,type— la entidad relacionada.taxIdesnullsi la API key no tieneentities:read_sensitive.relationshipType— tipo de vínculo (por ejemplorelated_to)
number
Los demás vínculos, antes de
limit / offset. Los filtros no cambian este total.200 y ambos arrays vacíos.
Errores
| Estado | Código | Cuándo |
|---|---|---|
| 400 | INVALID_ENTITY_ID | id no es un UUID |
| 404 | NOT_FOUND | No hay una entidad viva con ese id o tax id en tu organización |
Ejemplo
curl -X GET "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/shareholders?depth=1" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"data": {
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"shareholders": [
{
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"name": "João Silva",
"taxId": "12345678900",
"type": "person",
"riskScore": 25,
"shareholderInfo": {
"percentage": 60,
"roles": ["Sócio Administrador"],
"isActive": true
}
}
],
"totalShareholders": 1,
"relationships": [
{
"id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
"name": "Carlos Lima",
"taxId": "55566677788",
"type": "person",
"relationshipType": "related_to"
}
],
"totalRelationships": 1
}
}
Was this page helpful?