Participação Societária — percentual por sócio

{
  "type": "object",
  "properties": {
    "cnpj": {
      "type": [
        "string",
        "null"
      ],
      "description": "CNPJ consultado, no formato 00.000.000/0000-00. É o eco do parâmetro enviado — a origem não devolve o documento da consultada."
    },
    "socios": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "nome": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nome completo (pessoa física) ou razão social (pessoa jurídica) do participante."
          },
          "papel": {
            "type": [
              "string",
              "null"
            ],
            "description": "Papel na sociedade conforme a origem — ex.: `SOCIO`, `SOCIO-ADMINISTRADOR`, `ADMINISTRADOR`. Quem aparece como `ADMINISTRADOR` puro costuma vir com `percentual` 0."
          },
          "documento": {
            "type": [
              "string",
              "null"
            ],
            "description": "CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00) do participante, COMPLETO — sem a máscara de ocultação das consultas cadastrais públicas. Vem vazio quando o participante é estrangeiro sem documento brasileiro (observado em ~4,6% dos itens); nesses casos identifique pelo `nome`."
          },
          "percentual": {
            "type": [
              "number",
              "null"
            ],
            "description": "Percentual do capital detido, de 0 a 100. É o campo que só esta consulta entrega — nenhuma fonte cadastral pública informa quanto cada sócio detém. Pode vir com muitas casas decimais (ex.: 49.75124378). O valor 0 significa participante sem cota (tipicamente administrador), não dado ausente."
          },
          "dataEntrada": {
            "type": [
              "string",
              "null"
            ],
            "description": "Data de entrada na sociedade, `AAAA-MM-DD`. ATENÇÃO: a origem carimba parte dos registros com uma data de carga (`2017-01-01` é a mais comum) em vez da data real de entrada, e usa `0001-01-01` para data desconhecida. Quando a data de entrada for decisiva, confirme pelo quadro societário da Receita Federal (consulta `vinculos-ubo`), que traz a data registrada."
          },
          "tipoDocumento": {
            "type": [
              "string",
              "null"
            ],
            "description": "`CPF` ou `CNPJ`. Vem vazio junto com `documento` no caso do participante estrangeiro."
          },
          "indicioDeDebito": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Sinalização de débito do participante feita pela origem, sem detalhamento do que a originou. Trate como pista para aprofundar (consulta de dívidas/protestos), nunca como fato. Ausente em parte das respostas."
          },
          "indicioDeFraude": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Sinalização de indício de fraude do participante feita pela origem, sem detalhamento do que a originou. Trate como pista para aprofundar, nunca como fato — e não comunique ao titular como conclusão. Ausente em parte das respostas."
          },
          "situacaoDocumento": {
            "type": [
              "string",
              "null"
            ],
            "description": "Situação do documento do participante na Receita Federal — `REGULAR` para CPF, `ATIVA`/`ATIVO` para CNPJ. É a situação do participante, não da empresa consultada."
          },
          "podeAssinarPelaEmpresa": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Indica que o participante tem poder de assinatura pela empresa segundo a origem. Serve para orientar quem procurar; não substitui a leitura do contrato social."
          }
        }
      },
      "x-display": "table",
      "description": "Participantes da empresa com o percentual de cada um. Lista de vínculos DIRETOS e VIGENTES: esta consulta não traz vínculo indireto (sócio que entra via holding), não traz vínculo encerrado e não traz as empresas controladas pela consultada — para isso use `vinculos-ubo`."
    },
    "totalSocios": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Quantidade de participantes retornados em `socios`. Inclui quem aparece com participação 0% (administrador sem cota), por isso não é o número de detentores de capital."
    },
    "ultimaEntrada": {
      "type": [
        "string",
        "null"
      ],
      "description": "Data de entrada mais recente do quadro, `AAAA-MM-DD`. Sujeita à mesma ressalva de `socios[].dataEntrada`."
    },
    "primeiraEntrada": {
      "type": [
        "string",
        "null"
      ],
      "description": "Data de entrada mais antiga do quadro, `AAAA-MM-DD`. Sujeita à mesma ressalva de `socios[].dataEntrada`."
    },
    "maiorParticipacao": {
      "type": [
        "number",
        "null"
      ],
      "description": "Maior percentual entre os participantes."
    },
    "menorParticipacao": {
      "type": [
        "number",
        "null"
      ],
      "description": "Menor percentual entre os participantes. Vem 0 sempre que há administrador sem cota na lista."
    },
    "participacaoMedia": {
      "type": [
        "number",
        "null"
      ],
      "description": "Média aritmética simples dos percentuais, administradores de 0% incluídos — não é participação média dos detentores de capital."
    },
    "temSocioMajoritario": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "`true` quando algum participante detém mais da metade do capital. Calculado pela origem sobre os percentuais desta resposta."
    },
    "totalPessoasFisicas": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Quantos dos participantes são pessoa física (CPF)."
    },
    "totalPessoasJuridicas": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Quantos dos participantes são pessoa jurídica (CNPJ). Sócio PJ é o ponto onde a cadeia continua: consulte o CNPJ dele para subir mais um nível."
    }
  }
}