# CNPJ em Lote — Saúde do Fornecedor e Alertas de Mudança (`kodama-data/cnpj-lote-saude-fornecedor`) Actor

Consulta CNPJ em lote (Receita Federal) com veredito APTO/ATENÇÃO/BLOQUEAR, monitor de mudanças e CNPJ alfanumérico. LGPD-safe, sem sócios PF.

- **URL**: https://apify.com/kodama-data/cnpj-lote-saude-fornecedor.md
- **Developed by:** [Guilherme Kodama](https://apify.com/kodama-data) (community)
- **Categories:** Lead generation, Automation, Business
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 cnpjs

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CNPJ em Lote 🇧🇷 — Saúde do Fornecedor e Monitor de Mudanças (LGPD-safe)

> Desenvolvido e mantido por **Guilherme Kodama** · GitHub: [github.com/guilhermeKodama](https://github.com/guilhermeKodama)

> 📬 **Vende para o governo?** O **Radar Vending Público** junta licitações e diários oficiais de máquinas de café, snack e água e manda só o que importa no seu e-mail, todo dia. [Ver amostra e planos](https://guilhermekodama.github.io/radar-vending/) · [Plano Fundador — R$ 29/mês](https://pay.kiwify.com.br/caNaoiF)

Cole uma lista de CNPJs (do jeito que vier: planilha, e-mail, CSV) e receba, para cada empresa, o cadastro da **Receita Federal** + um veredito pronto: **APTO / ATENÇÃO / BLOQUEAR**, com os motivos. Agende e ele avisa **só o que mudou** desde a última vez.

Fonte: dados abertos do CNPJ da Receita Federal via **BrasilAPI** (com fallback automático para **CNPJ.ws pública**). Sem login, sem chave, sem CAPTCHA.

### Pra quem é

- **Compras / suprimentos**: checar fornecedores antes de pagar ou contratar (situação cadastral, falência, empresa recém-aberta, MEI acima do teto, CNAE incompatível).
- **Financeiro / crédito**: triagem de clientes PJ em lote.
- **Contabilidades e BPO**: monitorar a carteira de clientes toda semana.
- **Licitantes e órgãos públicos**: conferir habilitação básica de participantes.

### O que tem de diferente

- **Veredito, não só dados**: `statusFornecedor` + listas `bloqueios` e `alertas` (situação ≠ ATIVA, situação especial, falência/liquidação/recuperação judicial na razão social, idade mínima configurável, MEI, capital < R$ 1 mil, endereço sem número, CNAE fora do esperado).
- **Monitor de mudanças**: com `onlyChanges` + `stateKey`, cada execução compara com a foto anterior e devolve só CNPJs novos ou alterados, com campo `mudancas` (antes → depois). Agende + webhook = alerta automático.
- **Entrada bagunçada OK**: extrai CNPJs de qualquer texto, remove duplicados, **recupera zeros à esquerda que o Excel comeu**, valida dígito verificador e lista os inválidos.
- **Pronto para o CNPJ alfanumérico** (Receita, a partir de jul/2026): validação do novo formato.
- **Fallback de fonte + backoff**: se a BrasilAPI limitar (HTTP 429), espera e/ou usa CNPJ.ws, sem perder linhas.
- **LGPD-safe por padrão**: nomes e CPFs de sócios pessoa física **nunca** são exportados (só `qtdSocios`, `qtdSociosPF` e sócios **PJ**). Em MEI / empresário individual, CPF na razão social é removido e e-mail/telefone do titular não saem.

### Entrada

| Campo | Descrição |
|---|---|
| `cnpjs` | Lista, um por linha, com ou sem pontuação |
| `cnpjText` | Cole qualquer texto; os CNPJs são extraídos |
| `cnpjFileUrls` | URLs públicas de CSV/TXT (ex.: Google Sheets publicado) |
| `expectedCnaePrefixes` | Ex.: `["4721","5620"]` — alerta se nenhum CNAE bater |
| `minCompanyAgeYears` | Idade mínima (padrão 1) |
| `onlyChanges`, `stateKey` | Modo monitor |
| `onlyActive`, `ufs` | Filtros de saída |
| `includeContacts` | Telefone da PJ (nunca para MEI/individual) |
| `maxItems`, `concurrency`, `delaySeconds` | Limites e ritmo |

Exemplo — fornecedores de alimentação, monitor semanal:

```json
{"cnpjText":"12.345.678/0001-95\n98765432000110", "expectedCnaePrefixes":["4721","4729","5620"],
 "minCompanyAgeYears":2, "onlyChanges":true, "stateKey":"fornecedores-alimentacao"}
```

### Saída (exemplo resumido)

```json
{"cnpjFormatado":"92.772.821/0001-64","razaoSocial":"S.A. (VIACAO AEREA RIO-GRANDENSE) - FALIDA",
 "situacaoCadastral":"ATIVA","statusFornecedor":"BLOQUEAR","bloqueios":["Razão social indica FALÊNCIA"],
 "alertas":[],"cnaePrincipal":"5111-1/00","municipio":"PORTO ALEGRE","uf":"RS","qtdSocios":2,
 "mudancas":[],"primeiraVezNoMonitor":true,"fonte":"BrasilAPI"}
```

Campos completos: razão social, nome fantasia, matriz/filial, situação e data, motivo, situação especial, início de atividade, idade, natureza jurídica, porte, capital social, CNAE principal + secundários, Simples/MEI, último regime tributário, endereço completo, código IBGE, telefones (PJ), contagem de sócios, sócios PJ, veredito, mudanças, fonte, data da coleta.
Também há a chave `RESUMO` no key-value store com os totais da execução.

### Limites honestos

- A base aberta da Receita é atualizada **mensalmente**; mudanças aparecem com essa defasagem.
- A BrasilAPI não devolve e-mail; o telefone vem quando a Receita tem.
- Não é consulta oficial de regularidade fiscal (CND/FGTS) — é triagem cadastral.
- Razão social de MEI/empresário individual costuma conter o nome do titular: é dado público do registro, exportado sem CPF.

### Uso responsável

Dados públicos de pessoas jurídicas (Lei 12.527/2011 e política de dados abertos da Receita). Não use para spam nem para tratar dados de pessoas físicas sem base legal (LGPD).

***

### English summary

**Brazil CNPJ Bulk Lookup — Supplier Health & Change Monitor.** Paste any list of Brazilian company tax IDs (CNPJ, including the new 2026 alphanumeric format) and get Receita Federal registry data plus a ready verdict: **APTO (OK) / ATENCAO (warning) / BLOQUEAR (block)** with reasons (inactive status, special status, bankruptcy/liquidation in the legal name, company age, MEI, tiny capital, missing address number, unexpected CNAE). Schedule it with `onlyChanges` to receive only new or changed companies, with before/after diffs. Messy input is fine (dedupe, check-digit validation, Excel leading-zero recovery). Sources: BrasilAPI with automatic CNPJ.ws fallback and 429 backoff. Privacy-first: individual partners' names/CPFs are never exported; individual-owner companies (MEI) never expose contact data.

# Actor input Schema

## `cnpjs` (type: `array`):

Um CNPJ por linha, com ou sem pontuação. Aceita CNPJ alfanumérico (2026).

## `cnpjText` (type: `string`):

Cole qualquer texto (coluna do Excel, e-mail, CSV). O actor extrai os CNPJs sozinho, remove duplicados e recupera zeros à esquerda perdidos pelo Excel.

## `cnpjFileUrls` (type: `array`):

Links públicos (Google Sheets publicado como CSV, Dropbox, etc.).

## `expectedCnaePrefixes` (type: `array`):

Prefixos de CNAE que o fornecedor deveria ter (ex.: 4721 = padaria/laticínios, 5620 = alimentação). Se nenhum CNAE bater, gera alerta.

## `minCompanyAgeYears` (type: `integer`):

Empresas mais novas que isso recebem alerta.

## `onlyChanges` (type: `boolean`):

Retorna apenas CNPJs novos no monitor ou que mudaram (situação, endereço, CNAE, Simples, sócios...) desde a última execução com o mesmo stateKey. Agende diário/semanal + webhook = alerta automático.

## `stateKey` (type: `string`):

Separe carteiras diferentes (ex.: 'fornecedores', 'clientes-sp').

## `onlyActive` (type: `boolean`):

Se marcado, entrega só empresas com situação cadastral ATIVA na Receita.

## `ufs` (type: `array`):

Ex.: SP, MG. Vazio = todas.

## `includeContacts` (type: `boolean`):

Somente para pessoas jurídicas. Para MEI/empresário individual nunca é exportado (LGPD).

## `includeInvalid` (type: `boolean`):

Inclui no resultado os CNPJs com dígito inválido ou não encontrados, marcados como tal.

## `maxItems` (type: `integer`):

Limite de CNPJs processados nesta execução.

## `concurrency` (type: `integer`):

Número de consultas paralelas à base pública (1–5). Mais alto = mais rápido, mas sujeito a limite de taxa.

## `delaySeconds` (type: `string`):

Pausa em segundos entre requisições à base pública (rate limit educado). Ex.: 0.4.

## Actor input object example

```json
{
  "cnpjs": [
    "00.000.000/0001-91",
    "33000167000101",
    "60.746.948/0001-12"
  ],
  "minCompanyAgeYears": 1,
  "onlyChanges": false,
  "stateKey": "padrao",
  "onlyActive": false,
  "includeContacts": true,
  "includeInvalid": true,
  "maxItems": 1000,
  "concurrency": 2,
  "delaySeconds": "0.4"
}
```

# Actor output Schema

## `results` (type: `string`):

Uma linha por CNPJ consultado: cadastro da Receita (dados abertos), veredito APTO/ATENCAO/BLOQUEAR, alertas e mudanças desde a última execução. Sem nomes de sócios pessoa física.

## `resumo` (type: `string`):

JSON com contadores da execução.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cnpjs": [
        "00.000.000/0001-91",
        "33000167000101",
        "60.746.948/0001-12"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kodama-data/cnpj-lote-saude-fornecedor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "cnpjs": [
        "00.000.000/0001-91",
        "33000167000101",
        "60.746.948/0001-12",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("kodama-data/cnpj-lote-saude-fornecedor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cnpjs": [
    "00.000.000/0001-91",
    "33000167000101",
    "60.746.948/0001-12"
  ]
}' |
apify call kodama-data/cnpj-lote-saude-fornecedor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kodama-data/cnpj-lote-saude-fornecedor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ilgZM1VCrgal3up0g/builds/VakgOIvYxiwwe4o5q/openapi.json