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
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
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.Tamanho da página aplicado em separado a
shareholders e a relationships. Máximo 500.Mantém sócios cujo tipo seja
person ou company. Os vínculos de relationships não são filtrados.Identificador fiscal exato do sócio. Os dígitos são comparados, então
123.456.789-00 coincide com 12345678900.riskScore mínimo, inclusive. Sócios com riskScore: null ficam de fora quando este parâmetro ou maxRiskScore é enviado.Percentual de participação mínimo, inclusive. Sócios sem percentual gravado ficam de fora quando este parâmetro ou
maxOwnershipPercentage é enviado.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.
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
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)
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?