Skip to main content
GET
Obter sócios materializados

Visão geral

Devolve os sócios e os demais relacionamentos já gravados de uma pessoa ou empresa. É uma leitura de entities 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.

Autenticação

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.
Os filtros se combinam com AND. Valem só para 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 é null se o sócio não tem score. taxId é null se a API key não tem entities:read_sensitive.
  • shareholderInfo.percentage — metadata.shareholdingPercentage, ou null
  • shareholderInfo.roles — metadata.roles (array vazio se não houver)
  • shareholderInfo.isActive — metadata.isActive, ou null
number
Sócios que passam nos filtros, antes de limit / offset.
array
Outras contrapartes materializadas.
  • id, name, taxId, type — a entidade relacionada. taxId é null se a API key não tem entities:read_sensitive.
  • relationshipType — tipo do vínculo (por exemplo related_to)
number
Os demais vínculos, antes de limit / offset. Os filtros não mudam esse total.
Uma entidade sem vínculos responde 200 e os dois arrays vazios.

Erros

Exemplo