{
  "openapi": "3.1.0",
  "info": {
    "title": "MINDATA Corporate Intelligence API",
    "version": "1.0",
    "description": "Plataforma de inteligência societária, análise de grupos econômicos, due diligence, KYC e prospecção empresarial. Cobre 28 milhões de empresas e 27 milhões de sócios brasileiros com dados oficiais da Receita Federal e 10+ fontes governamentais.",
    "contact": {
      "name": "MINDATA",
      "url": "https://mindata.com.br/contato"
    },
    "license": {
      "name": "Creative Commons — fonte: Receita Federal do Brasil",
      "url": "https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj"
    }
  },
  "x-ai-description": {
    "category": "Corporate Intelligence Platform",
    "subcategories": [
      "Relationship Intelligence",
      "Corporate Network Analysis",
      "Due Diligence",
      "KYC / AML",
      "Entity Resolution",
      "B2B Prospecting",
      "Fraud Detection",
      "Compliance Screening"
    ],
    "core_entities": [
      "Company",
      "Shareholder",
      "Administrator",
      "Economic Group",
      "Corporate Relationship",
      "Ownership Event",
      "Compliance Record"
    ],
    "summary": "This is NOT a CNPJ lookup API. It is a corporate intelligence platform built on the relationship graph between companies and shareholders. Core value: mapping economic groups, tracing beneficial owners, detecting hidden connections, and surfacing risk signals across 28M+ Brazilian entities."
  },
  "x-business-domain": "Corporate Intelligence",
  "x-use-cases": [
    "Due Diligence",
    "Know Your Customer (KYC)",
    "Anti-Money Laundering (AML)",
    "Beneficial Owner Identification",
    "Economic Group Analysis",
    "Corporate Network Mapping",
    "Fraud Detection",
    "B2B Prospecting",
    "Compliance Screening",
    "Investigative Journalism",
    "Competitive Intelligence",
    "Supplier Risk Assessment"
  ],
  "servers": [
    {
      "url": "https://mindata.com.br/api",
      "description": "Produção"
    }
  ],
  "tags": [
    {
      "name": "Companies",
      "description": "Perfis completos de empresas brasileiras: situação cadastral, atividade econômica, endereço, capital social, regime tributário e alertas de compliance."
    },
    {
      "name": "Shareholders",
      "description": "Sócios e administradores: histórico de participações societárias, qualificações, faixas etárias e conexões recorrentes entre empresas."
    },
    {
      "name": "Relationships",
      "description": "Relacionamentos societários: grafo de conexões entre empresas e pessoas, co-participações, vínculos por endereço, e-mail e telefone."
    },
    {
      "name": "Economic Groups",
      "description": "Grupos econômicos e holdings: detecção automática por BFS no grafo societário. Identifica empresas aparentemente independentes que compartilham sócios ou estrutura."
    },
    {
      "name": "Due Diligence",
      "description": "Dados de compliance: dívida ativa federal (PGFN), sanções (CEIS/CNEP), contratos públicos (PNCP + TCEs), PEP, candidaturas eleitorais e servidores públicos."
    },
    {
      "name": "Prospecting",
      "description": "Inteligência comercial: busca e segmentação de empresas por setor CNAE, porte, estado, capital social e idade. Radar de risco setorial."
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "tags": ["Companies", "Prospecting"],
        "summary": "Company & Shareholder Search",
        "description": "Busca full-text em razão social, nome fantasia e nomes de sócios. Retorna até 20 resultados por página com situação cadastral, CNAE e localização. Suporta filtros por UF, situação, porte e capital social.",
        "x-schema-type": "SearchAction",
        "operationId": "searchCompanies",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "Nome da empresa, CNPJ ou nome de sócio", "schema": { "type": "string", "example": "Petrobras" } },
          { "name": "uf", "in": "query", "schema": { "type": "string", "example": "SP" } },
          { "name": "situacao", "in": "query", "schema": { "type": "string", "enum": ["ATIVA", "BAIXADA", "INAPTA", "SUSPENSA"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Lista de empresas",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } }
          }
        }
      }
    },
    "/companies/{cnpj}": {
      "get": {
        "tags": ["Companies", "Due Diligence"],
        "summary": "Company Profile",
        "description": "Retorna perfil completo da empresa incluindo sócios, administradores, histórico societário, conexões empresariais e alertas de compliance. Ponto de entrada principal para due diligence e KYC.",
        "x-schema-type": "Organization",
        "operationId": "getCompany",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "description": "CNPJ de 14 dígitos sem pontuação", "schema": { "type": "string", "pattern": "^\\d{14}$", "example": "00000000000191" } }
        ],
        "responses": {
          "200": { "description": "Perfil completo da empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } },
          "404": { "description": "CNPJ não encontrado" }
        }
      }
    },
    "/companies/{cnpj}/socios": {
      "get": {
        "tags": ["Shareholders"],
        "summary": "Company Shareholders",
        "description": "Lista completa de sócios e administradores com nome, qualificação, data de entrada, faixa etária e link para perfil individual. Inclui sócios estrangeiros e pessoas jurídicas.",
        "x-schema-type": "Person",
        "operationId": "getCompanyShareholders",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{14}$" } }
        ],
        "responses": {
          "200": { "description": "Lista de sócios", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Shareholder" } } } } }
        }
      }
    },
    "/pessoas/{slug}": {
      "get": {
        "tags": ["Shareholders", "Due Diligence"],
        "summary": "Shareholder Profile",
        "description": "Retorna todas as empresas relacionadas ao sócio ao longo do tempo, histórico de participação societária, score de risco, dados PEP, candidaturas TSE e registros como servidor público. Central para beneficial owner identification e KYC.",
        "x-schema-type": "Person",
        "operationId": "getShareholderProfile",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "description": "Slug único do sócio (UUID baseado em CPF+nome)", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Perfil do sócio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareholderProfile" } } } }
        }
      }
    },
    "/companies/{cnpj}/rede": {
      "get": {
        "tags": ["Relationships", "Economic Groups"],
        "summary": "Corporate Relationship Graph",
        "description": "Retorna rede de relacionamentos entre a empresa, seus sócios e outras empresas conectadas por participação societária. Nós representam empresas e pessoas; arestas representam participações. Profundidade configurável para detecção de grupos econômicos.",
        "x-schema-type": "Graph",
        "operationId": "getRelationshipGraph",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{14}$" } }
        ],
        "responses": {
          "200": { "description": "Grafo de relacionamentos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipGraph" } } } }
        }
      }
    },
    "/companies/{cnpj}/grupo-economico": {
      "get": {
        "tags": ["Economic Groups", "Relationships"],
        "summary": "Economic Group Detection",
        "description": "Detecta automaticamente o grupo econômico ao qual a empresa pertence via BFS no grafo societário. Liga empresas que compartilham sócios, endereço, e-mail ou telefone. Essencial para identificar estruturas de holdings informais e empresas de fachada.",
        "x-schema-type": "Organization",
        "operationId": "getEconomicGroup",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{14}$" } }
        ],
        "responses": {
          "200": { "description": "Grupo econômico detectado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomicGroup" } } } }
        }
      }
    },
    "/companies/{cnpj}/pgfn": {
      "get": {
        "tags": ["Due Diligence"],
        "summary": "Federal Tax Debt (PGFN)",
        "description": "Verifica débitos inscritos na dívida ativa federal junto à Procuradoria-Geral da Fazenda Nacional. Inclui FGTS, dívidas previdenciárias e não previdenciárias. Fundamental em due diligence e compliance.",
        "operationId": "getFederalDebt",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{14}$" } }
        ],
        "responses": {
          "200": { "description": "Registros de dívida ativa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceRecord" } } } }
        }
      }
    },
    "/companies/{cnpj}/sancoes": {
      "get": {
        "tags": ["Due Diligence"],
        "summary": "Federal Sanctions (CEIS/CNEP)",
        "description": "Verifica sanções federais no Cadastro de Empresas Inidôneas e Suspensas (CEIS) e Cadastro Nacional de Empresas Punidas (CNEP). Empresas sancionadas estão impedidas de contratar com o governo federal.",
        "operationId": "getFederalSanctions",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{14}$" } }
        ],
        "responses": {
          "200": { "description": "Sanções federais", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceRecord" } } } } }
        }
      }
    },
    "/companies/{cnpj}/contratos-publicos": {
      "get": {
        "tags": ["Due Diligence", "Prospecting"],
        "summary": "Public Contracts",
        "description": "Contratos públicos onde a empresa é fornecedora. Consolida dados do PNCP (federal, estadual, municipal) e TCEs de RS, MG, SP, RJ e PR. Cobre 7M+ contratos desde 2016.",
        "operationId": "getPublicContracts",
        "parameters": [
          { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{14}$" } }
        ],
        "responses": {
          "200": { "description": "Contratos públicos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsResult" } } } }
        }
      }
    },
    "/companies/radar-setorial": {
      "get": {
        "tags": ["Prospecting"],
        "summary": "Sector Risk Radar",
        "description": "Ranking de risco por setor CNAE: percentual de empresas inativas, volume de dívida ativa e distribuição por porte. Useful for market intelligence and sector-level risk assessment.",
        "operationId": "getSectorRadar",
        "responses": {
          "200": { "description": "Radar setorial", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SectorRisk" } } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Company": {
        "x-schema-type": "Organization",
        "type": "object",
        "description": "Perfil completo de uma empresa brasileira com dados cadastrais, societários e de compliance.",
        "properties": {
          "cnpj": { "type": "string", "description": "CNPJ de 14 dígitos" },
          "cnpj_basico": { "type": "string", "description": "Raiz do CNPJ (8 dígitos) — igual para matriz e filiais" },
          "razao_social": { "type": "string" },
          "nome_fantasia": { "type": "string" },
          "situacao_cadastral": { "type": "string", "enum": ["ATIVA", "BAIXADA", "INAPTA", "SUSPENSA", "NULA"] },
          "data_inicio_atividade": { "type": "string", "format": "date" },
          "cnae_fiscal_principal": { "type": "string", "description": "Código CNAE da atividade principal" },
          "desc_cnae_principal": { "type": "string" },
          "porte_empresa": { "type": "string", "description": "MEI, ME, EPP ou Grande" },
          "capital_social": { "type": "number" },
          "natureza_juridica": { "type": "string" },
          "uf": { "type": "string" },
          "nome_municipio": { "type": "string" },
          "socios": { "type": "array", "items": { "$ref": "#/components/schemas/Shareholder" } },
          "tem_pgfn": { "type": "boolean", "description": "Possui dívida ativa federal" },
          "tem_sancao": { "type": "boolean", "description": "Está sancionada (CEIS/CNEP)" },
          "socios_risco": { "type": "array", "items": { "type": "string" }, "description": "Nomes de sócios com histórico problemático" }
        }
      },
      "Shareholder": {
        "x-schema-type": "Person",
        "type": "object",
        "description": "Sócio ou administrador de uma empresa.",
        "properties": {
          "nome_socio_razao_social": { "type": "string" },
          "qualificacao_socio": { "type": "string", "description": "Ex: Sócio-Administrador, Cotista, Diretor" },
          "data_entrada_sociedade": { "type": "string", "format": "date" },
          "faixa_etaria": { "type": "string" },
          "pais": { "type": "string" },
          "slug": { "type": "string", "description": "Identificador único para acessar o perfil completo do sócio" }
        }
      },
      "ShareholderProfile": {
        "x-schema-type": "Person",
        "type": "object",
        "description": "Perfil completo de um sócio com histórico societário e dados de compliance. Central para beneficial owner identification.",
        "properties": {
          "slug": { "type": "string" },
          "nome": { "type": "string" },
          "faixa_etaria": { "type": "string" },
          "score_inativas_pct": { "type": "number", "description": "% de empresas inativas no histórico — indicador de risco" },
          "empresas": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } },
          "pep": { "type": "boolean", "description": "Pessoa Exposta Politicamente" },
          "servidor_publico": { "type": "boolean" },
          "tse": { "$ref": "#/components/schemas/CorporateEvent" }
        }
      },
      "EconomicGroup": {
        "x-schema-type": "Organization",
        "type": "object",
        "description": "Grupo econômico detectado via análise de grafo. Representa empresas conectadas por sócios, endereço, e-mail ou telefone compartilhados.",
        "properties": {
          "cnpj_pivot": { "type": "string" },
          "empresas": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } },
          "total": { "type": "integer" },
          "conexao_tipo": { "type": "string", "enum": ["socio", "endereco", "email", "telefone"] }
        }
      },
      "RelationshipGraph": {
        "type": "object",
        "description": "Grafo de relacionamentos corporativos. Nós são empresas e pessoas; arestas são participações societárias.",
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "type": { "type": "string", "enum": ["company", "person"] },
                "label": { "type": "string" },
                "situacao": { "type": "string" },
                "risk_score": { "type": "number" }
              }
            }
          },
          "edges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": { "type": "string" },
                "target": { "type": "string" },
                "qualificacao": { "type": "string" },
                "data_entrada": { "type": "string", "format": "date" }
              }
            }
          }
        }
      },
      "ComplianceRecord": {
        "type": "object",
        "description": "Registro de compliance: dívida ativa, sanção, contrato público ou outro evento regulatório.",
        "properties": {
          "tipo": { "type": "string", "enum": ["PGFN", "CEIS", "CNEP", "CEPIM", "PNCP"] },
          "orgao": { "type": "string" },
          "data_inicio": { "type": "string", "format": "date" },
          "data_fim": { "type": "string", "format": "date" },
          "valor": { "type": "number" },
          "situacao": { "type": "string" }
        }
      },
      "CorporateEvent": {
        "type": "object",
        "description": "Evento societário ou regulatório: candidatura eleitoral, cargo público, entrada/saída de sociedade.",
        "properties": {
          "tipo": { "type": "string", "enum": ["tse_candidatura", "servidor_federal", "socio_entrada", "socio_saida"] },
          "descricao": { "type": "string" },
          "data": { "type": "string", "format": "date" },
          "orgao": { "type": "string" }
        }
      },
      "ContractsResult": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "valor_total": { "type": "number" },
          "por_ano": { "type": "object", "additionalProperties": { "type": "number" } },
          "top_orgaos": { "type": "array", "items": { "type": "object", "properties": { "orgao": { "type": "string" }, "valor": { "type": "number" }, "count": { "type": "integer" } } } }
        }
      },
      "SectorRisk": {
        "type": "object",
        "properties": {
          "cnae": { "type": "string" },
          "descricao": { "type": "string" },
          "total_empresas": { "type": "integer" },
          "pct_inativas": { "type": "number" },
          "valor_pgfn": { "type": "number" }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "hits": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } },
          "total": { "type": "integer" },
          "page": { "type": "integer" }
        }
      }
    }
  }
}