Brazil CNPJ Situação Change Monitor (honest monthly lag)

Watch a list of Brazilian CNPJs (suppliers, merchants, customers) and receive typed situação cadastral / material change events when official Receita Federal dados abertos (or an equivalent open-data mirror of the same dump) shows Ativa → Baixada / Inapta / Suspensa / Nula — or optional CNAE / endereço flips. Not another bulk CNPJ enrichment dump. Not paid Serasa / Serpro.

Honest title: official RFB refresh is monthly. Detection latency ≈ your schedule + RFB publish lag. This is not intra-day Serasa Monitora.

Value proposition

• Watchlist × snapshot diff → SITUACAO_ATIVA, SITUACAO_BAIXADA, SITUACAO_INAPTA, SITUACAO_SUSPENSA, SITUACAO_NULA, optional CNAE_CHANGED / ENDERECO_CHANGED.
• Official / public open data only (RFB dados abertos CC-BY layout; live path uses a public open-data–derived per-CNPJ lookup with the same monthly lag). No paid Serasa / Serpro API.
• Pay only for unique delivered change events. First observation stores a baseline (no charge). Quiet months ≈ $0.
• Durable KVS checkpoint + event_uid dedupe. Events carry as_of for honest open-data dating.

PRODUCTION USE (required for real monitoring)

Store default ≠ product. Schema defaults use sourceMode=fixture so Apify Store daily auto-tests leave a non-empty health dataset without calling open-data mirrors. That fixture path only writes a non-billable RUN_STATUS / FIXTURE_HEALTH row. It is not CNPJ monitoring.

For production monitoring you must:

1. Set sourceMode = live
2. Provide your cnpjNumbers watchlist
3. Schedule runs after each monthly RFB publish (or weekly catch-up) with fair-use requestPaceMs
4. Optionally set rfbOpenDataMonth (YYYY-MM) so events / RUN_STATUS document the dump you are aligning to

Official references:

• Cadastro Nacional da Pessoa Jurídica — CNPJ (dados.gov.br) (CC-BY, monthly)
• RFB CNPJ metadados / layout PDF
• RFB open-data file host: arquivos.receitafederal.gov.br (Estabelecimentos*.zip)

Data limitations (read before buying)

• Monthly lag (honest). RFB dados abertos are published about once a month. This Actor does not claim same-day Serasa-class alerts.
• Live lookups use a public open-data–derived HTTP API that mirrors the RFB dump (not paid Serpro Consulta CNPJ). Mirror freshness tracks the monthly dump — document as_of / rfbOpenDataMonth.
• First run stores baselines only — you will not be charged for “current state” snapshots.
• Invalid CNPJs (check digits) are skipped with no charge.
• Fair-use pacing applies; large books need longer maxRunSeconds or chunked runs.
• We cite Receita Federal / dados.gov.br as the data origin. This Actor is not affiliated with or endorsed by RFB.

Apify Store daily auto-test / default input

Field	Default
cnpjNumbers	["00000000000191","60746948000112"]
signalGroups	situacao, cnae, endereco
sourceMode	fixture
emitFixtureDemoEvents	false
maxRunSeconds	55
maxEvents	500

On that path the Actor SUCCEEDS quickly, pushes exactly one RUN_STATUS / FIXTURE_HEALTH row (billable: false), and does not charge situacao-change-delivered.

Input (summary)

Field	Notes
cnpjNumbers	Watchlist (required)
signalGroups	situacao, cnae, endereco
sourceMode	fixture (default) or live
emitFixtureDemoEvents	Default false
rfbOpenDataMonth	Optional YYYY-MM as_of hint
maxRunSeconds / maxEvents	Budgets
resumeFromCheckpoint	Default true
requestPaceMs	Fair-use delay (default 400)

Production example

{
  "cnpjNumbers": ["00000000000191", "60746948000112"],
  "signalGroups": ["situacao", "cnae", "endereco"],
  "sourceMode": "live",
  "rfbOpenDataMonth": "2026-08",
  "maxRunSeconds": 120,
  "requestPaceMs": 400,
  "resumeFromCheckpoint": true
}

Output

Change events (billable under PPE)

Typed rows include: cnpj, razao_social, event_type, event_subtype, changed_fields, previous_value, new_value, effective_date, as_of, evidence, summary, source_url, event_uid, billable: true.

RUN_STATUS (never billed)

Every successful run pushes one health row (FIXTURE_HEALTH | MONITOR_IDLE | CATCHUP_COMPLETE | HEALTH_OK) including as_of when known.

Pricing

Pay-per-event: situacao-change-delivered at $0.02 per delivered unique change event ($20 / 1,000). Single tier (see docs/monetization.md and ADR 0010). Health / baseline / duplicate / fixture rows are never charged.

Local development

cd actors/brazil-cnpj-situacao-change-monitor
npm install
npm test
npm run build
# Store-safe fixture health:
apify run -p
# Demo typed events locally:
# set input emitFixtureDemoEvents=true (still sourceMode=fixture)

Attribution

Data originates from the Receita Federal do Brasil (RFB) CNPJ dados abertos (CC-BY) / dados.gov.br. Live path may use a public open-data–derived mirror of that dump. Not an official RFB product. Not Serasa Experian.