Obter sócios 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
}Referência API
Obter sócios materializados
Lê os sócios e os demais relacionamentos já materializados de uma entidade, sem executar enrichment de novo.
GET
/
entities
/
{id}
/
shareholders
Obter sócios 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
}Visão geral
Devolve os sócios e os demais relacionamentos já gravados de uma pessoa ou empresa. É uma leitura deentities e entity_relationships. Não chama integrações, não materializa linhas novas e não consome créditos de enrichment.
Use depois da criação automática quando precisar dos mesmos sócios mais tarde. data.shareholders desse POST é só a resposta da criação (id, name, taxId, type das fichas filhas materializadas naquela corrida). Percentual e papéis ficam no relacionamento e são lidos aqui em shareholderInfo.
Linhas de QSA que nunca viraram entidades (por exemplo um documento mascarado) não entram. Continuam em Obter enrichment normalizado.
Exige a permissão granular entities:read na API key (fallback legacy entities:read).
Endpoints
Os dois devolvem o mesmo body. A organização vem da API key.GET https://api.gu1.ai/entities/{id}/shareholders
GET https://api.gu1.ai/entities/by-tax-id/{taxId}/shareholders
Autenticação
Authorization: Bearer YOUR_API_KEY
Parâmetros de rota
string
UUID da entidade. Use em
GET /entities/{id}/shareholders.string
Identificador fiscal gravado na entidade (CNPJ, CUIT, etc.). Os dígitos são comparados do mesmo jeito que obter por tax id. Use em
GET /entities/by-tax-id/{taxId}/shareholders. Se houver várias linhas, usa-se a criada mais recentemente.Parâmetros de query
integer
default:"1"
Quantos níveis de propriedade percorrer em
shareholders. 1 são só os donos diretos. Máximo 5. A lista é plana e deduplicada por id da entidade. Empresas aninhadas só entram se depth for maior que 1. relationships continua a um salto da entidade consultada.integer
default:"100"
Tamanho da página aplicado em separado a
shareholders e a relationships. Máximo 500.integer
default:"0"
Quantos itens pular em cada array. Aplica-se depois dos filtros de sócios.
string
Mantém sócios cujo tipo seja
person ou company. Os vínculos de relationships não são filtrados.string
Identificador fiscal exato do sócio. Os dígitos são comparados, então
123.456.789-00 coincide com 12345678900.number
riskScore mínimo, inclusive. Sócios com riskScore: null ficam de fora quando este parâmetro ou maxRiskScore é enviado.number
riskScore máximo, inclusive.number
Percentual de participação mínimo, inclusive. Sócios sem percentual gravado ficam de fora quando este parâmetro ou
maxOwnershipPercentage é enviado.number
Percentual de participação máximo, inclusive.
shareholders, depois de percorrer depth e antes de limit / offset. Uma empresa que não passa no filtro ainda é percorrida quando depth é maior que 1, então um dono que passa abaixo dela pode aparecer. minRiskScore não pode ser maior que maxRiskScore; a mesma regra vale para os limites de percentual (400).
Resposta
200 com { "success": true, "data": { ... } }.
Vínculos de propriedade usam a direção sócio = source, entidade possuída = target, e um tipo shareholder, owns ou controls. Esses vão em shareholders. Os demais vínculos não apagados em que esta entidade é source ou target vão em relationships.
string
UUID da entidade consultada.
array
Donos materializados.
id,name,taxId,type,riskScore— a entidade relacionada.riskScoreénullse o sócio não tem score.taxIdénullse a API key não tementities:read_sensitive.shareholderInfo.percentage—metadata.shareholdingPercentage, ounullshareholderInfo.roles—metadata.roles(array vazio se não houver)shareholderInfo.isActive—metadata.isActive, ounull
number
Sócios que passam nos filtros, antes de
limit / offset.array
Outras contrapartes materializadas.
id,name,taxId,type— a entidade relacionada.taxIdénullse a API key não tementities:read_sensitive.relationshipType— tipo do vínculo (por exemplorelated_to)
number
Os demais vínculos, antes de
limit / offset. Os filtros não mudam esse total.200 e os dois arrays vazios.
Erros
| Status | Código | Quando |
|---|---|---|
| 400 | INVALID_ENTITY_ID | id não é um UUID |
| 404 | NOT_FOUND | Não há entidade viva com esse id ou tax id na sua organização |
Exemplo
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?