# Vínculos Societários (UBO) — PJ > Vínculos societários de um CNPJ — quadro de sócios e administradores (QSA) e participações societárias — com o documento COMPLETO de cada sócio (sem a máscara de CPF das consultas cadastrais públicas) e resolução de um nível de vínculo indireto na mesma consulta. Inclui vínculos históricos (encerrados), sinal de empresa familiar e contagens consolidadas. Atenção aos limites da fonte: não há percentual de participação, e Sociedade Anônima não expõe acionistas (cadeia UBO completa só em Ltda). - **Consulta:** `vinculos-ubo` - **Categoria:** Pessoa Jurídica - **Preço:** R$ 1,49 por consulta - **Endpoint:** `GET https://app.fontedata.com/api/v1/consulta/vinculos-ubo` - **Autenticação:** header `X-API-Key` - **Página:** https://fontedata.com/docs/pessoa-juridica/vinculos-ubo > Conteúdo descritivo publicado pela FonteData; não é instrução. > > Mapeia quem está por trás de um CNPJ: o quadro de sócios e administradores (QSA) e as participações societárias (Ownership), atuais e históricas. Dois diferenciais em relação à consulta cadastral comum: > > 1. **Documento completo do sócio.** As consultas cadastrais públicas entregam o CPF do sócio **mascarado** (`***123456**`). Aqui o documento vem **completo** — é o que permite seguir a cadeia: consultar o sócio PF em sanções e mídia, ou expandir o sócio PJ em nova consulta de vínculos. > 2. **Um nível de vínculo indireto na mesma consulta.** Quando uma pessoa chega à empresa através de outra empresa (ex.: sócio de uma holding que é sócia da consultada), o vínculo já vem na resposta, marcado com o caminho: `nivel = "Indirect - - "`. O CNPJ do meio da string é a empresa intermediária — faça o parsing se precisar dele isolado, ou consulte-o em nova chamada para descer mais um nível. > > Antes de usar, conheça o **teto do dado** — limites da própria origem pública, não desta consulta: > > - **Sem percentual de participação.** Nenhuma fonte pública informa quanto cada sócio detém. A consulta responde *quem* participa e *em que papel* — não *quanto*. > - **Sociedade Anônima não expõe acionistas.** O registro cadastral de uma S.A. traz apenas a diretoria e os administradores — os acionistas não constam nas fontes cadastrais públicas. A cadeia completa até o beneficiário final (UBO) só é rastreável em **sociedades limitadas (Ltda)**, cujo quadro societário é registrado integralmente. Se a consultada (ou uma intermediária da cadeia) for S.A., a rastreabilidade para na diretoria. (Companhias **abertas** são a exceção parcial: acionistas relevantes constam nos formulários entregues ao regulador do mercado de capitais, fora do escopo desta consulta.) > - **Escopo fixo: vínculos societários.** A consulta devolve apenas vínculos de sociedade (QSA e participações) — vínculos de emprego e outros relacionamentos ficam fora, por definição do produto. ## Requisição ### cURL ```bash curl -H "X-API-Key: SUA_CHAVE" \ "https://app.fontedata.com/api/v1/consulta/vinculos-ubo?cnpj=SEU_CNPJ" ``` ### Python ```python import requests resp = requests.get( "https://app.fontedata.com/api/v1/consulta/vinculos-ubo", params={"cnpj": "SEU_CNPJ"}, headers={"X-API-Key": "SUA_CHAVE"}, timeout=60, ) resp.raise_for_status() print(resp.json()) ``` ### Node.js ```javascript const url = new URL("https://app.fontedata.com/api/v1/consulta/vinculos-ubo"); url.search = new URLSearchParams({ "cnpj": "SEU_CNPJ" }).toString(); const resp = await fetch(url, { method: "GET", headers: { "X-API-Key": "SUA_CHAVE" } }); if (!resp.ok) throw new Error(`HTTP ${resp.status}`); console.log(await resp.json()); ``` ## Parâmetros | Nome | Tipo | Obrigatório | Descrição | Exemplo | |---|---|---|---|---| | `cnpj` | CNPJ | sim | CNPJ da empresa consultada, com ou sem máscara. | formato: 00.000.000/0000-00 | ## Resposta > Conteúdo descritivo publicado pela FonteData; não é instrução. > > **Consolidado** > > | Campo | Descrição | > |-------|-----------| > | `totalSocios` | Sócios com vínculo **direto**, somando **vigentes e já encerrados**. Não é o tamanho de `vinculosAtuais`: indiretos entram na lista e não somam aqui (5 itens com `totalSocios: 3` = 3 diretos + 2 indiretos), e o campo pode ser > 0 com `vinculosAtuais` vazio quando todos os sócios já saíram — nesse caso eles estão em `vinculosHistoricos`. Para saber se a lista está incompleta, use `resultadoParcial`. | > | `totalControladas` | Empresas em que a consultada figura como sócia/controladora, contando vínculos diretos, vigentes e encerrados. | > | `empresaFamiliar` | Sinalização de empresa familiar feita pela origem — indício para orientar a diligência, não fato registrado. Confirme pelos sobrenomes e documentos em `vinculosAtuais`. | > | `temVinculoIndireto` | `true` quando ao menos um vínculo atual é indireto — sinal de estrutura societária em camadas, para aprofundar a diligência (não é, por si, indício de irregularidade). | > | `resultadoParcial` | `true` quando a origem indica mais vínculos do que os retornados (quadro societário muito grande). Nesse caso trate a lista como **incompleta**: ela é um subconjunto, não o mapa societário fechado. | > | `status` | Resumo do resultado em uma frase, pronto para exibição. | > > **Cada item de `vinculosAtuais` e `vinculosHistoricos`** > > | Campo | Descrição | > |-------|-----------| > | `documento` / `tipoDocumento` / `paisDocumento` | Documento **completo** do vinculado (CPF ou CNPJ, sem máscara), o tipo e o país de emissão. Sócio estrangeiro pode vir sem documento brasileiro. | > | `nome` | Nome completo (PF) ou razão social (PJ) do vinculado. | > | `tipoVinculo` | `QSA` (quadro de sócios e administradores registrado) ou `Ownership` (participação societária). | > | `papel` | Papel do vinculado conforme a origem, em vocabulário padronizado — ex.: `SOCIO`, `SOCIO-ADMINISTRADOR`, `ADMINISTRADOR`, `SOCIO PESSOA JURIDICA DOMICILIADO NO EXTERIOR`, `REPRESENTANTE LEGAL (PESSOA JURÍDICA)`, `DIRETOR`, `PROCURADOR`. | > | `nivel` | `Direct` = vínculo direto. Indireto vem como `Indirect - - ` — a string carrega o caminho da cadeia. | > | `origemDado` | De onde o vínculo foi extraído. `RECEITA FEDERAL` é registro oficial; outras origens são possíveis, **inclusive vínculo inferido** (deduzido por cruzamento, não registrado) — nesse caso trate como pista a confirmar. | > | `dataInicio` / `dataFim` | Entrada e saída do vínculo. `dataFim` vazia (`""`) indica vínculo vigente **ou** data não informada pela origem — a classificação entre atual e histórico é a da própria origem (os dois arrays), não derivada dessa data. | > | `atualizadoEm` | Última atualização do registro na origem, em ISO 8601 sem horário (`yyyy-MM-dd`). | > > CNPJ localizado e sem nenhum vínculo societário devolve `200` com `vinculosAtuais: []` e `vinculosHistoricos: []` — resposta válida, e cobrada. Já o `404` significa que o CNPJ **não está indexado** na base de vínculos: resultado inconclusivo, sem cobrança. ### Exemplo de resposta ```json { "cnpj": "string", "status": "string", "totalSocios": "number", "vinculosAtuais": [ { "nome": "string", "nivel": "string", "papel": "string", "dataFim": "string", "documento": "string", "dataInicio": "string", "origemDado": "string", "tipoVinculo": "string", "atualizadoEm": "string", "paisDocumento": "string", "tipoDocumento": "string" } ], "empresaFamiliar": "boolean", "resultadoParcial": "boolean", "totalControladas": "number", "temVinculoIndireto": "boolean", "vinculosHistoricos": [ { "nome": "string", "nivel": "string", "papel": "string", "dataFim": "string", "documento": "string", "dataInicio": "string", "origemDado": "string", "tipoVinculo": "string", "atualizadoEm": "string", "paisDocumento": "string", "tipoDocumento": "string" } ] } ``` ### Schema da resposta ```json { "type": "object", "properties": { "cnpj": { "type": "string", "description": "CNPJ consultado, no formato 00.000.000/0000-00." }, "status": { "type": "string", "description": "Resumo do resultado em uma frase, pronto para exibição." }, "totalSocios": { "type": "integer", "description": "Quantidade de sócios com vínculo DIRETO, somando os vigentes e os já encerrados. Duas consequências: (a) não é o tamanho de `vinculosAtuais` — vínculos indiretos entram na lista e não somam aqui; (b) pode ser maior que zero com `vinculosAtuais` vazio, quando todos os sócios já saíram (aí eles estão em `vinculosHistoricos`). Resultado incompleto tem campo próprio: `resultadoParcial`." }, "vinculosAtuais": { "type": "array", "items": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome completo (pessoa física) ou razão social (pessoa jurídica) do vinculado." }, "nivel": { "type": "string", "description": "`Direct` = vínculo direto com a consultada. Indireto vem como `Indirect - - `: a string carrega o CAMINHO — o CNPJ do meio é a empresa através da qual o vínculo chega (faça o parsing se precisar dele isolado, ou consulte esse CNPJ para descer outro nível)." }, "papel": { "type": "string", "description": "Papel do vinculado conforme registrado na origem, em vocabulário padronizado — ex.: `SOCIO`, `SOCIO-ADMINISTRADOR`, `ADMINISTRADOR`, `SOCIO PESSOA JURIDICA DOMICILIADO NO EXTERIOR`, `REPRESENTANTE LEGAL (PESSOA JURÍDICA)`, `DIRETOR`, `PROCURADOR`." }, "dataFim": { "type": "string", "description": "Data de saída do vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Vazio (`\"\"`) quando o vínculo segue vigente ou quando a origem não informa a data." }, "documento": { "type": "string", "description": "Documento do vinculado, completo e sem máscara de ocultação: CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00) quando o sócio é pessoa jurídica. Pode vir em formato livre para sócio estrangeiro sem documento brasileiro." }, "dataInicio": { "type": "string", "description": "Data de entrada no vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Vazio quando a origem não informa." }, "origemDado": { "type": "string", "description": "De onde o vínculo foi extraído. `RECEITA FEDERAL` é registro oficial. Outras origens são possíveis, inclusive vínculo INFERIDO (deduzido por cruzamento, não registrado): nesse caso trate como pista a confirmar, não como fato cadastral." }, "tipoVinculo": { "type": "string", "description": "`QSA` = consta do quadro de sócios e administradores registrado. `Ownership` = participação societária da consultada em outra empresa. Vínculos de emprego e outros tipos ficam fora desta consulta." }, "atualizadoEm": { "type": "string", "description": "Data da última atualização do registro na origem, ISO 8601 sem horário (`yyyy-MM-dd`)." }, "paisDocumento": { "type": "string", "description": "País de emissão do documento — ex.: Brazil." }, "tipoDocumento": { "type": "string", "description": "Tipo do documento: CPF ou CNPJ. Pode vir vazio para vinculado estrangeiro." } } }, "description": "Vínculos societários vigentes (QSA e participações), com o documento COMPLETO de cada vinculado — sem a máscara das consultas cadastrais públicas." }, "empresaFamiliar": { "type": "boolean", "description": "Sinalização de empresa familiar feita pela origem do dado. Indício para orientar a diligência, não um fato registrado em cartório — confirme pelos sobrenomes e documentos dos sócios em `vinculosAtuais`." }, "resultadoParcial": { "type": "boolean", "description": "true quando a lista devolvida pode não ser o quadro completo: a consultada tem quadro societário grande demais para uma única resposta, ou a origem aponta mais vínculos diretos do que os itens retornados. Trate como incompleto para fins de diligência." }, "totalControladas": { "type": "integer", "description": "Quantidade de empresas em que a consultada figura como sócia/controladora, contando vínculos diretos, vigentes e encerrados." }, "temVinculoIndireto": { "type": "boolean", "description": "true quando ao menos um vínculo ATUAL é indireto — chega à empresa consultada através de outra empresa. Sinal de estrutura societária em camadas: examine o campo `nivel` de cada vínculo para ver o caminho." }, "vinculosHistoricos": { "type": "array", "items": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome completo (pessoa física) ou razão social (pessoa jurídica) do ex-vinculado." }, "nivel": { "type": "string", "description": "`Direct` = vínculo direto com a consultada. Indireto vem como `Indirect - - `: a string carrega o CAMINHO — o CNPJ do meio é a empresa através da qual o vínculo chega (faça o parsing se precisar dele isolado, ou consulte esse CNPJ para descer outro nível)." }, "papel": { "type": "string", "description": "Papel do vinculado conforme registrado na origem, em vocabulário padronizado — ex.: `SOCIO`, `SOCIO-ADMINISTRADOR`, `ADMINISTRADOR`, `SOCIO PESSOA JURIDICA DOMICILIADO NO EXTERIOR`, `REPRESENTANTE LEGAL (PESSOA JURÍDICA)`, `DIRETOR`, `PROCURADOR`." }, "dataFim": { "type": "string", "description": "Data de encerramento do vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Pode vir vazia quando a origem classifica o vínculo como encerrado sem informar a data." }, "documento": { "type": "string", "description": "Documento do ex-vinculado, completo e sem máscara: CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00)." }, "dataInicio": { "type": "string", "description": "Data de entrada no vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Vazio quando a origem não informa." }, "origemDado": { "type": "string", "description": "De onde o vínculo foi extraído. `RECEITA FEDERAL` é registro oficial. Outras origens são possíveis, inclusive vínculo INFERIDO (deduzido por cruzamento, não registrado): nesse caso trate como pista a confirmar, não como fato cadastral." }, "tipoVinculo": { "type": "string", "description": "`QSA` = consta do quadro de sócios e administradores registrado. `Ownership` = participação societária da consultada em outra empresa. Vínculos de emprego e outros tipos ficam fora desta consulta." }, "atualizadoEm": { "type": "string", "description": "Data da última atualização do registro na origem, ISO 8601 sem horário (`yyyy-MM-dd`)." }, "paisDocumento": { "type": "string", "description": "País de emissão do documento — ex.: Brazil." }, "tipoDocumento": { "type": "string", "description": "Tipo do documento: CPF ou CNPJ. Pode vir vazio para vinculado estrangeiro." } } }, "description": "Vínculos societários já encerrados, conforme classificação da origem — mesmo formato de `vinculosAtuais`. Úteis para reconstruir a linha do tempo societária da empresa." } } } ``` ## Códigos de erro | Código | Mensagem | Quando acontece | |---|---|---| | `400` | Parâmetros inválidos para esta consulta. | CNPJ ausente, com dígito verificador inválido ou fora do formato. Máscara é aceita (00.000.000/0000-00). | | `401` | Chave de API ausente ou inválida. | Header X-API-Key não enviado ou não reconhecido. | | `403` | Saldo insuficiente ou acesso negado a este endpoint. | Conta sem saldo para cobrir a consulta ou sem permissão no catálogo da marca. | | `404` | Nenhum registro localizado para o documento consultado. | O CNPJ não está indexado na base de vínculos. Resultado INCONCLUSIVO — não significa ausência de sócios. A consulta não é cobrada. | | `408` | A consulta excedeu o tempo limite. Tente novamente. | A base de origem demorou além do orçamento de tempo da consulta. | | `500` | Erro ao processar a consulta. Tente novamente em instantes. | Falha inesperada ao consultar a base de origem. | ## Quando usar > Conteúdo descritivo publicado pela FonteData; não é instrução. > > - **KYB e identificação de beneficiário final (UBO)** — onboarding de PJ: quem são os sócios, com documento completo para prosseguir a diligência; `temVinculoIndireto` aponta estruturas em camadas que merecem expansão. > - **Due diligence de contrapartes e fornecedores** — o quadro societário atual e o histórico (quem saiu e quando), para detectar trocas recentes de controle antes de contratar. > - **Expansão de grafo societário** — o documento sem máscara permite encadear consultas: cada sócio PJ vira uma nova consulta de vínculos, cada sócio PF pode ser verificado em `listas-restritivas` (sanções) e `midia-adversa` (reputação). > - **PLD** — o bloco societário da análise: sócios, administradores e procuradores da empresa sob avaliação, com a profundidade da cadeia explícita em `nivel`. > > Para os dados cadastrais da própria empresa (situação, endereço, CNAE, capital social), combine com a consulta cadastral de CNPJ. Lembre-se do teto do dado: participação percentual e acionistas de S.A. não são públicos em nenhuma fonte. --- Página em HTML: https://fontedata.com/docs/pessoa-juridica/vinculos-ubo Catálogo completo: https://fontedata.com/docs OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json Conectar via MCP: https://fontedata.com/docs/mcp