> ## Documentation Index > Fetch the complete documentation index at: https://docs.jusfy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Consulta grupo econômico > Retorna o agregado estatístico do grupo econômico de um **CNPJ** — totais de empresas, faixas de idade/renda/funcionários, distribuições por CNAE, UF e cidade, e os CNPJs do grupo (`company_doc_numbers`). O recorte do grupo é definido por `subtype` — **um por requisição**, e cada requisição conta como uma consulta: `household`, `household_activity`, `rfcontact`, `owners` ou `legal_representative`. Para mais de um recorte, faça uma requisição por subtipo. ## OpenAPI ````yaml /openapi/legado.json post /api/consultas/grupo-economico openapi: 3.0.0 info: title: Calculadoras Jusfy API description: >- Rotas sem versão (`/api/...`). Continuam funcionando, mas a versão atual da API é a v1 (`/api/v1`): para integrações novas, use a v1 e siga o [guia de migração](https://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado). A política de versionamento e depreciação está na [política de versionamento](https://api.jusfy.dev/calculators/api/reference/fundamentos/migracao-do-legado#pol%C3%ADtica-de-versionamento). version: legacy contact: {} servers: - url: https://api.jusfy.dev/calculators security: [] tags: - name: Calculadoras description: >- Execução das calculadoras jurídicas e consulta dos índices de correção. Cada cálculo recebe um payload, retorna o resultado processado e exige API key no header `x-api-key`. - name: Consultas description: >- Consultas de dados (veículos, condutores e documentos). Cada consulta recebe o documento, retorna os dados encontrados e exige API key no header `x-api-key`. A maioria responde na mesma requisição; o **rastreamento veicular** e o **buscador processual** são assíncronos — devolvem `202` com um protocolo e entregam o resultado por webhook e/ou pelo `GET` do protocolo. - name: JusScore description: >- Consulta de processos judiciais por CPF/CNPJ, com score de risco consolidado e a lista detalhada dos processos. É assíncrona: o POST inicia a consulta e o GET devolve o resultado quando pronto. Exige API key no header `x-api-key`. - name: Consumo description: >- Consumo da própria API key: quantas chamadas cada produto recebeu num período, separando as cobradas das não cobradas. Não exige escopo; exige API key no header `x-api-key`. - name: Health description: >- Verificações de disponibilidade do serviço (liveness e readiness). Rotas abertas, sem autenticação. paths: /api/consultas/grupo-economico: post: tags: - Consultas summary: Consulta grupo econômico description: >- Retorna o agregado estatístico do grupo econômico de um **CNPJ** — totais de empresas, faixas de idade/renda/funcionários, distribuições por CNAE, UF e cidade, e os CNPJs do grupo (`company_doc_numbers`). O recorte do grupo é definido por `subtype` — **um por requisição**, e cada requisição conta como uma consulta: `household`, `household_activity`, `rfcontact`, `owners` ou `legal_representative`. Para mais de um recorte, faça uma requisição por subtipo. operationId: QueriesController_grupoEconomico[0] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EconomicGroupQueryDto' responses: '200': description: >- Agregado do grupo econômico no recorte pedido. As faixas (`*_income_range`, `*_employees_range`) são textuais e vêm em minúsculas (ex.: `"empresa isenta"`); já as chaves de `state_distribution` (todas as UFs, zeradas quando não há empresa — inclui `EX`) e `city_distribution` vêm em MAIÚSCULAS, e `cnae_distribution` usa o código numérico puro. O detalhe de cada empresa não vem no agregado — use os CNPJs de `company_doc_numbers` para consultas individuais. content: application/json: schema: type: object example: statusCode: 200 message: Consulta concluída com sucesso timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico result: subtype: owners title: Empresas com o mesmo quadro societário query_id: b7a76771-b788-4ad4-bc1d-32eeddf95f3b query_date: '2026-08-03T19:58:16.9760542Z' elapsed_milliseconds: 99 status_code: 0 status_message: OK group: total_companies: 1 total_branches: 0 total_active_companies: 1 total_inactive_companies: 0 total_simples_companies: 0 total_meis: 0 total_headquarter: 1 min_company_age: 16 max_company_age: 16 average_company_age: 16 min_activity_level: 0.28125 max_activity_level: 0.28125 average_activity_level: 0.28125 total_income_range: empresa isenta min_income_range: empresa isenta max_income_range: empresa isenta average_income_range: empresa isenta total_employees_range: sem informacao min_employees_range: sem vinculos max_employees_range: sem informacao average_employee_range: sem informacao total_declared_value: 0 min_declared_value: 0 max_declared_value: 0 average_declared_value: 0 total_number_of_owners: 0 min_number_of_owners: 0 max_number_of_owners: 0 average_number_of_owners: 0 total_sites: 10 min_sites: 10 max_sites: 10 average_sites: 10 total_marketplace_stores: 0 min_marketplace_stores: 0 max_marketplace_stores: 0 average_marketplace_stores: 0 total_unique_cnaes: 1 total_unique_cities: 1 total_unique_states: 1 total_tax_status_ativa: 1 total_tax_status_baixada: 0 total_regime_isenta_irpj: 1 total_regime_lucro_presumido: 0 total_regime_lucro_real: 0 total_regime_nao_ativa: 0 total_regime_simples: 0 total_regime_mei: 0 total_sociedade_anonima_fechada: 0 total_sociedade_anonima_aberta: 0 total_sociedade_empresaria_limitada: 0 total_sociedade_simples_limitada: 0 total_associacao_privada: 1 total_empresario_individual: 0 cnae_distribution: '6201501': 1 state_distribution: AC: 0 AL: 0 AM: 0 AP: 0 BA: 0 CE: 0 DF: 0 ES: 0 GO: 0 MA: 0 MG: 0 MS: 0 MT: 0 PA: 0 PB: 0 PE: 0 PI: 0 PR: 0 RJ: 0 RN: 0 RO: 0 RR: 0 RS: 0 SC: 0 SE: 0 SP: 1 TO: 0 EX: 0 city_distribution: SAO PAULO: 1 company_doc_numbers: - '11222333000181' '400': description: >- Documento inválido. `message` é a **lista** de erros de validação desta API (campo + motivo), diferente dos demais erros, em que é uma string. content: application/json: schema: example: statusCode: 400 code: invalid_request message: - document deve ser um CNPJ válido requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico '401': description: >- API key ausente ou que não pertence a nenhum cliente (`code: invalid_api_key`). A `message` diz qual dos dois. content: application/json: examples: missing: summary: Key ausente value: statusCode: 401 message: Missing API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} invalid: summary: Key inválida value: statusCode: 401 message: Invalid API key code: invalid_api_key requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} '403': description: >- Acesso negado. Dois motivos, distinguidos pelo `code`: o cliente não está ativo (`inactive_client`), ou a API key não tem o escopo deste produto (`insufficient_scope`, com o escopo na `message`). A liberação de produtos é feita pela equipe Jusfy. content: application/json: examples: inactive_client: summary: Cliente não ativo value: statusCode: 403 message: Client is not active code: inactive_client requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} insufficient_scope: summary: Sem o escopo do produto value: statusCode: 403 message: 'Missing scope: ' code: insufficient_scope requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-10-14T18:00:00.000Z' path: /api/consultas/{consulta} '404': description: >- CNPJ válido, mas sem grupo econômico localizado no recorte pedido. A consulta foi executada — apenas não há grupo a devolver. content: application/json: schema: example: statusCode: 404 code: no_data_found message: >- Nenhum grupo econômico encontrado para o documento informado. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico '422': description: Payload recusado pelo provedor da consulta. content: application/json: schema: example: statusCode: 422 code: payload_rejected message: document inválido requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico '429': description: >- Limite de requisições por minuto do cliente neste produto excedido. `Retry-After` diz em quantos segundos a janela vira. Toda resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. content: application/json: schema: example: statusCode: 429 code: rate_limit_exceeded message: >- Rate limit exceeded for consultas.cnh:execute: 60 requests per minute. Retry in 42s. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-06-22T18:00:00.000Z' path: /api/consultas/cnh '502': description: >- Erro no provedor da consulta. `message` identifica o provedor que falhou quando essa informação está disponível. Diferente do `503`, não há garantia de que repetir a consulta resolva. content: application/json: schema: example: statusCode: 502 code: upstream_error message: Erro ao consultar o fornecedor de grupo econômico. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico '503': description: >- Provedor não respondeu no tempo limite. A consulta **não** foi concluída — pode ser repetida. content: application/json: schema: example: statusCode: 503 code: upstream_unavailable message: >- A consulta de grupo econômico está temporariamente indisponível, tente novamente mais tarde. requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico '504': description: Tempo limite ao falar com o provedor da consulta. content: application/json: schema: example: statusCode: 504 code: upstream_timeout message: Query provider timed out requestId: 9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65 timestamp: '2026-07-28T18:00:00.000Z' path: /api/consultas/grupo-economico security: - api-key: [] components: schemas: EconomicGroupQueryDto: type: object properties: document: type: string description: >- CNPJ da empresa consultada, com ou sem máscara. Separadores (incluindo a barra) são aceitos e ignorados. O dígito verificador é validado antes da consulta. A consulta é de pessoa jurídica — CPF não é aceito. example: '11222333000181' subtype: type: string description: >- Recorte do grupo econômico a consultar — **um por requisição**, cada uma conta como uma consulta: `household` (empresas de qualquer atividade no mesmo endereço), `household_activity` (empresas com atividade semelhante no endereço), `rfcontact` (empresas com o mesmo contato na Receita Federal), `owners` (empresas com o mesmo quadro societário) ou `legal_representative` (empresas com o mesmo representante legal). enum: - household - household_activity - rfcontact - owners - legal_representative example: owners required: - document - subtype securitySchemes: api-key: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.