Mapa de Filiais por CNPJ — Rede Empresarial
Pricing
from $10.00 / 1,000 mapa de filiais
Mapa de Filiais por CNPJ — Rede Empresarial
Mapeie as filiais de uma empresa pela raiz do CNPJ usando dados abertos oficiais da Receita Federal. Receba CNPJ completo, UF, município, CNAE, situação e data de início por filial, além de totais por UF e status. Aceita CNPJ numérico ou alfanumérico e declara o frescor mensal.
Pricing
from $10.00 / 1,000 mapa de filiais
Rating
0.0
(0)
Developer
Johnn Mottin
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
3 days ago
Last modified
Categories
Share
Mapeie toda a rede de filiais de uma empresa pela raiz do CNPJ
Informe a raiz do CNPJ ou um CNPJ completo e receba o mapa das filiais presentes na fotografia mensal dos dados abertos da Receita Federal.
Cada BRANCH_MAP pode incluir:
- CNPJ completo de cada filial;
- UF;
- código do município;
- CNAE principal;
- situação cadastral;
- data de início;
- total de filiais;
- total de filiais ativas;
- distribuição por UF;
- distribuição por situação cadastral.
O Actor também calcula deterministicamente o CNPJ da matriz como:
e deixa claro que esse CNPJ da matriz foi calculado pela regra, não observado no índice de filiais.
Aceita CNPJ numérico e o novo formato alfanumérico. O frescor mensal é declarado em cada resultado.
Principais recursos
- Mapa de filiais por raiz de CNPJ
- Raiz de 8 posições ou CNPJ completo
- CNPJ numérico e alfanumérico
- Validação de DV para CNPJ completo
- CNPJ completo de cada filial
- CNPJ da matriz calculado pela norma
- Total de filiais
- Filiais ativas
- Distribuição por UF
- Distribuição por situação cadastral
- UF de cada filial
- Código do município
- CNAE principal
- Situação cadastral
- Data de início
- Versão mensal dos dados
- Alerta de índice atrasado
- Entradas inválidas gratuitas
- Deduplicação por raiz dentro da execução
- RUN_SUMMARY gratuito
- Leitura eficiente por shards
- Até 1.000 raízes por execução
- Pay Per Event por mapa entregue
Actor comunitário não-oficial. Sem afiliação com a Receita Federal do Brasil ou qualquer órgão público. A origem são os dados abertos oficiais do CNPJ, pré-processados em um índice mensal mantido pela JM Forge. Este índice lista filiais. Uma raiz sem filiais no índice não deve ser interpretada automaticamente como inexistente.
Para que este Actor serve
A pergunta central é:
Quais filiais esta raiz de CNPJ possui na fotografia mensal, onde elas estão e qual a situação de cada uma?
Casos de uso:
- mapeamento de grupos empresariais;
- homologação de fornecedores;
- pesquisa de redes;
- análise territorial;
- cobertura comercial;
- inteligência de contas;
- auditoria cadastral;
- análise de expansão;
- integração de CRM/ERP;
- pesquisa B2B;
- consolidação por raiz de CNPJ.
Para quem é
Vendas B2B e account intelligence
Descubra a dimensão operacional de uma conta antes de planejar cobertura comercial.
Compliance e procurement
Mapeie estabelecimentos associados à mesma raiz e analise a situação de cada filial como um dado cadastral complementar.
Logística e expansão
Veja a distribuição regional da rede por UF.
Consultorias e pesquisa
Crie análises de redes empresariais sem abrir cada CNPJ individualmente.
Automação e dados
Conecte os resultados a:
- Apify API;
- n8n;
- Make;
- Google Sheets;
- CRM;
- ERP;
- bancos de dados;
- BI;
- aplicações internas.
O que significa "raiz do CNPJ"
A raiz são as primeiras 8 posições do CNPJ.
Exemplo:
Raiz:
A mesma raiz identifica a família de estabelecimentos que compartilha o número básico.
Formatos aceitos
Raiz direta
CNPJ completo
CNPJ alfanumérico completo
O validador interno também suporta as 12 primeiras posições alfanuméricas conforme o formato novo, mantendo os dois DVs finais numéricos.
Quando um CNPJ completo é fornecido, o Actor valida o DV antes de convertê-lo em raiz.
Importante: raiz de 8 posições não tem DV próprio
Uma raiz fornecida diretamente possui apenas 8 posições.
Ela não contém os dígitos verificadores do CNPJ completo.
Por isso o Actor consegue verificar:
- comprimento;
- caracteres aceitos;
mas não consegue confirmar por DV, somente com a raiz, que existe uma matriz real.
O índice de filiais é então consultado para essa raiz.
Importante: o índice contém filiais
O índice mensal usado por este produto foi construído para responder rapidamente:
Quais filiais pertencem a esta raiz?
Ele não é o cadastro completo da matriz.
O BRANCH_MAP possui:
Quando é true
Existe pelo menos uma filial dessa raiz no índice mensal.
Quando é false
Nenhuma filial dessa raiz foi observada no snapshot.
Isso não é o mesmo que provar que a raiz não existe.
Uma empresa pode existir somente com matriz e zero filiais.
Uma raiz estrutural de 8 posições também pode ter sido informada sem um CNPJ completo validado.
Quando você precisa confirmar a existência cadastral da matriz, use um produto independente de consulta CNPJ.
CNPJ da matriz é calculado
O índice de filiais não fornece ao produto os dados cadastrais da matriz.
O Actor calcula:
e retorna:
O campo é deliberadamente chamado de:
para não sugerir que a matriz foi observada no índice.
Situação cadastral das filiais
O Actor traduz os códigos previstos na implementação para:
O registro também preserva:
para auditoria.
Fonte dos dados
A origem é o conjunto de dados abertos do CNPJ administrado pela Receita Federal.
O fluxo do produto é:
O runtime não precisa processar o snapshot bruto inteiro em cada consulta.
Por que existe um índice mensal
A base oficial do CNPJ é grande.
Para tornar consultas por raiz rápidas, a JM Forge constrói mensalmente um índice específico de filiais.
O runtime lê apenas os shards necessários para as raízes solicitadas.
Exemplo:
Se várias raízes do lote começam por 34, o shard correspondente é lido uma única vez e reutilizado.
Frescor mensal
Este produto não é tempo real.
O resultado informa:
para deixar explícita a fotografia usada.
versaoDosDados
O índice pode fornecer:
snapshotMonth
Mês do snapshot oficial usado para construir o índice.
referenceMonth
Mês de referência operacional do índice.
builtAt
Momento de construção do índice.
staleness
O Actor compara o índice disponível com o mês fechado esperado no calendário brasileiro.
Exemplo:
Quando o índice está atrás:
e o RUN_SUMMARY recebe um aviso.
Input
Exemplo recomendado
As duas entradas do exemplo representam a mesma raiz.
Ela será consultada uma única vez.
Campos de input
| Campo | Default | Descrição |
|---|---|---|
cnpjs | obrigatório | Raízes de 8 posições ou CNPJs completos. Máximo 1.000 entradas. |
mes | vazio | AAAA-MM; vazio = mês mais recente disponível. |
maxResults | 100 | Máximo de BRANCH_MAP entregues/cobrados. |
maxRuntimeMs | 300000 | Teto de runtime. |
debug | false | Logs adicionais. |
Deduplicação de entrada
A deduplicação ocorre pela:
Exemplo:
as três entradas representam a mesma raiz.
O Actor processa:
e gera no máximo:
para ela.
Entradas inválidas são gratuitas
Quando um CNPJ completo possui:
- comprimento errado;
- caracteres inválidos;
- DV inválido;
ele é listado nos avisos do resumo e não gera BRANCH_MAP.
Se todas as entradas forem inválidas, o input é rejeitado.
Mês específico
Mês mais recente:
Mês específico, se ainda retido no índice:
O mês precisa estar no formato:
com mês entre:
Output
O Dataset contém:
BRANCH_MAP é o registro cobrado.
RUN_SUMMARY é gratuito.
Exemplo de BRANCH_MAP
O exemplo ilustra o shape do produto.
Os dados reais dependem da raiz e da fotografia mensal usada.
Campos principais de BRANCH_MAP
| Campo | Descrição |
|---|---|
recordType | BRANCH_MAP. |
raiz | Raiz normalizada com 8 posições. |
entradaOriginal | Primeira entrada original associada à raiz. |
cnpjMatrizCalculado | CNPJ da matriz calculado pela regra. |
cnpjMatrizFormatado | Matriz calculada com máscara. |
raizAtestadaPeloIndice | True quando o índice contém pelo menos uma filial dessa raiz. |
totalFiliais | Quantidade de filiais observadas. |
filiaisAtivas | Quantidade de filiais ativas. |
porUf | Contagem por UF. |
porSituacao | Contagem por situação cadastral. |
filiais | Lista completa das filiais. |
versaoDosDados | Versão da fotografia mensal. |
staleness | Diagnóstico do frescor mensal. |
observedAt | Timestamp da entrega. |
Campos de cada filial
Dentro de:
podem aparecer:
Código do município
O Actor retorna:
conforme a codificação usada na base CNPJ.
Esta versão não transforma o código no nome do município.
Faça o mapeamento downstream quando precisar do nome.
Raiz sem filiais
Exemplo de shape:
O exemplo acima é conceitual.
O ponto importante é:
é uma resposta válida do mapa.
Mas:
significa que o índice de filiais não confirmou essa raiz por observação de uma filial.
Uma matriz sem filiais é cobrada?
Sim.
O produto vendido é:
e:
é uma resposta possível.
Por isso um BRANCH_MAP com zero filiais é cobrado.
Se você precisa saber primeiro se a matriz existe, faça validação/lookup cadastral antes de chamar este Actor.
Shards indisponíveis
As raízes são agrupadas por prefixo.
Se um shard sofre falha de rede ou fonte, o Actor não devolve:
para aquelas raízes.
As unidades correspondentes ficam como falha/indisponíveis no resumo.
Isso evita transformar erro de infraestrutura em veredito de negócio.
RUN_SUMMARY
O resumo final é gratuito.
Ele pode incluir:
report
O bloco gratuito pode incluir:
STATS
O Key-Value Store padrão recebe:
com informações como:
- requests HTTP;
- registros entregues;
- cobrança;
- runtime;
- staleness;
- warnings;
- qualidade;
- custo computacional;
- limites.
API da Apify
Execute via API:
Substitua:
pelos seus dados da Apify.
Integrações
Use com:
- Apify API;
- Tasks;
- Schedules;
- webhooks;
- n8n;
- Make;
- Google Sheets;
- CRM;
- ERP;
- bancos de dados;
- BI;
- dashboards;
- aplicações internas.
Agendamento
A fonte é mensal.
Uma cadência natural é:
depois da atualização da fotografia.
O Actor é stateless entre execuções.
Se você rodar a mesma raiz duas vezes no mesmo mês, o mapa pode ser entregue e cobrado novamente.
Comparando redes entre meses
O Actor não gera um evento automático de:
Mas você pode salvar os mapas mensais downstream e comparar:
entre meses.
Para monitoramento cadastral específico, use um Actor independente de mudanças.
Cobrança
Este Actor usa:
O modelo de publicação contém:
apify-actor-start
É o evento sintético de início da própria Apify.
O código não chama um segundo evento customizado de start.
Não configure:
como evento customizado adicional.
branch-map
É cobrado para cada:
entregue.
Isso inclui mapas com:
porque zero filiais é um resultado do produto.
O que é gratuito
Não gera cobrança de branch-map:
- CNPJ completo inválido;
- entrada descartada por deduplicação de raiz;
- raiz não processada depois do cap;
RUN_SUMMARY;- warnings;
- falha de shard que impede a conclusão da raiz.
O evento sintético de início da Apify pode continuar se aplicando à execução.
Controle de custo
Principais controles:
Mais eficiente
Agrupe várias raízes na mesma execução.
Raízes com o mesmo prefixo reutilizam o mesmo shard de dados.
Menor cobrança
Use:
para limitar quantos mapas podem ser entregues.
Health e transparência
O Actor diferencia:
- raiz com zero filiais;
- entrada inválida;
- shard indisponível;
- índice indisponível;
- staleness;
- cap;
- contrato de fonte alterado.
Problemas aparecem em:
e não são convertidos silenciosamente em mapas vazios.
Limites honestos
O índice é de filiais
Não é o cadastro completo da matriz.
raizAtestadaPeloIndice=false não prova inexistência
Significa zero filiais observadas para a raiz no índice.
A matriz é calculada
cnpjMatrizCalculado não é um campo cadastral observado.
Frescor mensal
Não é tempo real.
Código do município, não nome
O Actor retorna municipioCodigo.
CNAE é o principal da filial
Esta versão não lista CNAEs secundários.
Não traz endereço completo
O produto não promete:
- logradouro;
- número;
- bairro;
- CEP;
- telefone;
- e-mail.
Não traz razão social da matriz
Use um Actor de consulta cadastral quando precisar desse dado.
Shard 404 e raiz vazia
O índice é publicado de forma atômica. Um shard opcional ausente representa ausência de filiais naquele prefixo do índice, mas isso ainda não atesta ou nega a existência de uma matriz específica.
Reexecução repete o mapa
Não há deduplicação de cobrança entre runs.
O índice é uma dependência JM Forge
Se o índice mensal estiver indisponível, o Actor não reconstrói o snapshot bruto dentro da mesma execução.
Meses antigos dependem de retenção
Um mes explícito só funciona enquanto aquele índice permanecer disponível.
Perguntas frequentes
De onde vêm os dados?
Dos dados abertos oficiais do CNPJ da Receita Federal, pré-processados em um índice mensal mantido pela JM Forge.
É scraping da Receita?
Não.
Posso informar somente a raiz?
Sim.
Posso informar o CNPJ completo?
Sim.
O CNPJ completo tem DV validado?
Sim.
Aceita CNPJ alfanumérico?
Sim.
O que acontece se eu repetir a mesma raiz?
Ela é processada uma única vez na execução.
Quantas raízes posso enviar?
Até:
entradas no input.
O que significa totalFiliais?
Quantidade de estabelecimentos do tipo filial encontrados para aquela raiz no snapshot mensal.
A matriz entra em totalFiliais?
Não.
O Actor retorna a matriz?
Retorna o CNPJ da matriz calculado pela regra.
Se totalFiliais=0, a empresa não existe?
Não conclua isso.
Leia:
e use um lookup cadastral quando precisar confirmar a matriz.
Retorna filiais baixadas?
Sim, quando elas estão presentes no snapshot.
A situação fica explícita.
Posso filtrar só filiais ativas?
O output fornece filiaisAtivas, mas esta versão entrega a lista completa observada em vez de possuir um filtro de situação no input.
Retorna CNAE da filial?
Sim, o CNAE principal.
Retorna nome do município?
Não nesta versão.
O resumo é cobrado?
Não.
Uma raiz sem filiais é cobrada?
Sim, quando um BRANCH_MAP é entregue.
Entrada inválida é cobrada?
Não como branch-map.
Posso pedir um mês anterior?
Sim, se aquele índice ainda estiver retido.
Posso agendar?
Sim.
Mensal é a cadência natural.
Pelo que eu pago?
Pelo evento branch-map para cada mapa entregue, além do evento sintético de início configurado na Apify.
Este Actor é oficial da Receita Federal?
Não.
É uma ferramenta comunitária independente construída sobre dados públicos oficiais.
Suporte
Para bugs, dúvidas ou solicitação de campos:
Use também a aba Issues na página do Actor.
Parte da suíte JM Forge
Também do mesmo desenvolvedor:
- Consulta CNPJ Brasil e Empresas por CNAE — consulta cadastral e descoberta de empresas.
- Empresas Novas por CNPJ, CNAE, UF e Porte — leads de novas matrizes ativas.
- Inteligência de Mercado por CNAE — Brasil — perfis agregados de mercado.
- Validador de CNPJ Alfanumérico — Lote e Migração — validação estrutural.
- Monitor de Mudanças Cadastrais de CNPJ — mudanças cadastrais.
- Triagem CNPJ — CEIS, CNEP, CEPIM e Leniência — triagem factual de sanções.
Os Actors permanecem ferramentas independentes.
Use este Actor quando precisar do mapa da rede de filiais de uma raiz de CNPJ.
