Documentation Index
Fetch the complete documentation index at: https://developers.gyramais.com.br/llms.txt
Use this file to discover all available pages before exploring further.
Resumo: a fonte de vínculos societários mapeia quem se conecta a um CPF ou CNPJ: sócios diretos (QSA), participações em outras empresas, filiais, grupo econômico e parentes quando relevante. É a base para análises de concentração, risco de grupo, conflito de interesse e suporte à feature opcional de Operações (cadeia de políticas por relacionamento).
O que é
Em crédito e compliance, olhar apenas para o documento tomador não basta. Uma empresa pode parecer saudável mas ter sócio com restritivos graves; um CPF pode ter participação em dezenas de empresas inativas. Mapear vínculos revela risco que o documento isolado esconde. A seção responde:- Quem são os sócios da empresa? Quanto cada um detém?
- Em quais outras empresas esses sócios participam?
- Existem filiais? Matriz?
- Há grupo econômico (empresas com sócios ou endereço em comum)?
- Para PF: cônjuge, pais, filhos com relevância para a análise?
De onde vem
- Tipo de fonte: bases públicas (Receita Federal, Juntas Comerciais) e bases proprietárias agregadas.
- Cobertura geográfica: Brasil.
- Natureza do dado: público (QSA) + derivado (grupo econômico inferido por cruzamento).
- Base legal: dados públicos da RFB e Juntas Comerciais; LGPD para dados de PF relacionada.
Frequência de atualização
| Componente | Atualização |
|---|---|
| QSA direto | real-time, sincronizado com RFB em ciclo de 24-48 h |
| Participações cruzadas | diária |
| Grupo econômico inferido | diária |
| Parentesco (PF) | conforme base de origem |
Níveis de profundidade
A política define até que nível buscar:| Nível | O que traz |
|---|---|
ROOT | Apenas o documento consultado |
FIRST_LEVEL | + sócios diretos e filiais diretas |
SECOND_LEVEL | + empresas onde os sócios têm participação |
THIRD_LEVEL | + sócios dessas empresas (raro, caro) |
FIRST_LEVEL como padrão, subir apenas quando o produto exige (ex: crédito grande ticket, M&A).
Dados entregues
| Campo | Descrição |
|---|---|
partners[].document | CPF/CNPJ do sócio |
partners[].name | Nome ou razão social |
partners[].role | Qualificação (ex: sócio administrador) |
partners[].sharePercent | % de participação |
partners[].entryDate | Data de entrada no QSA |
branches[] | Filiais do CNPJ (outros estabelecimentos) |
participations[] | Empresas onde a pessoa/empresa participa |
economicGroup[] | Empresas identificadas como parte do mesmo grupo |
relatives[] | Parentes próximos (PF), quando disponível |
Casos de uso
Risco de sócio
Analisar cada sócio no mesmo nível do tomador: score, processos, protestos. Sócio com restritivo grave é bandeira.
Concentração em grupo
Crédito concedido a várias empresas do mesmo grupo soma. Mapear grupo evita overexposure.
Empresa de sócio laranja
Sócio pessoa física com 50+ participações em empresas inativas é sinal clássico de fraude.
Due diligence de M&A
Nível THIRD_LEVEL mapeia rede completa, útil em auditoria e investigação.
PEP por parentesco
PEP pode estar no cônjuge do tomador. Cruzamento com PEP e Sanções.
Cadeia de políticas (Operações)
A feature de Operações roda política no sócio automaticamente a partir do vínculo mapeado aqui.
Como usar na política
Ativar vínculos no painel de dados
No editor da política, painel Dados Consultados, ativar Vínculos Societários com a profundidade desejada (começar em
FIRST_LEVEL).Regras sobre QSA
Ex:
partners.count < 1 : DENIED (empresa sem sócios é anomalia); partners.count > 20 : ALERT (fragmentação incomum).Regras de concentração
Se você já tem o tomador em carteira, regra externa (no seu backend) pode cruzar
economicGroup com posição atual.Feature Operações (opcional)
Se contratada, configurar cadeia para rodar política específica sobre sócios e retornar como subrelatório. Ver Operações.
Limitações e considerações
- QSA defasado: alterações no QSA (entrada/saída de sócio) podem demorar semanas para refletir na RFB, e portanto na nossa consulta.
- Grupo econômico é inferido: o “grupo” não é declarado oficialmente. A GYRA+ infere por cruzamento (sócios comuns, endereço compartilhado). Pode haver falso positivo.
- Parentes não-declarados: a base de parentesco cobre casos mais comuns (pais, filhos, cônjuges), mas pode ter gaps.
- Sócio estrangeiro: sócios sem CPF (pessoa jurídica estrangeira, fundos) aparecem com documento parcial ou nulo.
Perguntas frequentes
Quanto maior o nível, maior o custo?
Quanto maior o nível, maior o custo?
Sim.
FIRST_LEVEL é barato, SECOND_LEVEL multiplica por N (número de sócios), THIRD_LEVEL multiplica por N*M. Usar com critério.O relatório do sócio roda automaticamente?
O relatório do sócio roda automaticamente?
Não no fluxo simples. No fluxo simples, a seção traz os dados dos vínculos (nome, documento, %). Para rodar política completa nos sócios, usar a feature de Operações.
Sócio oculto aparece?
Sócio oculto aparece?
Apenas o QSA formalizado aparece. Sócio oculto (beneficiário final não declarado) exige investigação manual ou produtos específicos de KYC avançado.
Empresa unipessoal (EIRELI / SLU) tem QSA?
Empresa unipessoal (EIRELI / SLU) tem QSA?
Sim, com um único sócio. O relatório traz normalmente.
Qual nível de relatório inclui vínculos?
Qual nível de relatório inclui vínculos?
Disponível a partir do ESSENCIAL em
FIRST_LEVEL. Níveis mais profundos exigem COMPLETO ou COMPLETO+.Próximos passos
Operações (feature)
Cadeia de políticas por relacionamento.
PEP e Sanções
Checar sócios contra listas restritivas.
Cadastral
Dados básicos de cada sócio identificado.
Criar regra de QSA
Passo a passo no Toolbox.