Scraping CVM Portal vs apicvm API: When to Use Each
Developers who need Brazilian regulatory documents often start by trying to scrape CVM filings from the official portal. HTML parsing, session cookies, and brittle selectors are familiar pain. apicvm offers a different path — a versioned REST API over an ingested CVM corpus — but scraping still has a place in some workflows.
This page compares both approaches so you can choose based on coverage needs, maintenance budget, and product requirements.
What scraping the CVM portal involves
Typical scraper architecture:
HTTP client → parse HTML/JS → extract PDF links
→ map to company (CNPJ/ticker join table)
→ store files locally
→ re-run when layout changesPros:
- Access to whatever the portal shows at crawl time
- No API key or subscription
- Full control over crawl schedule
Cons:
| Risk | Impact |
|---|---|
| HTML/JS changes | Scraper breaks without warning |
| Rate limits / blocks | Production jobs fail unpredictably |
| No stable document IDs | Hard to deduplicate or cite filings |
| Ticker mapping | You maintain CNPJ ↔ ticker tables |
| Legal/ToS ambiguity | Scraping policies vary; review CVM terms |
What apicvm provides instead
GET /v1/companies/resolve?query=PETR4&by=ticker
GET /v1/documents?ticker=PETR4&type=DFP&year=2024
GET /v1/documents/:id/file
POST /v1/document-text-extractions| Capability | apicvm |
|---|---|
| Ticker-first lookup | Yes |
Stable document.id (UUID) |
Yes |
| Filter by DFP / ITR / FRE | Yes |
Versioned /v1 contract |
Yes |
| Page-level markdown extraction | Yes (async callback) |
| Immune to portal HTML changes | Yes (for ingested corpus) |
Trade-off: apicvm covers the ingested corpus, not necessarily every page on the CVM site. It optimizes B3 issuer filings (DFP, ITR, FRE), not every CVM dataset.
When to scrape
| Scenario | Scraping may fit |
|---|---|
| One-off academic crawl | Low maintenance cost |
| Need a dataset apicvm does not ingest | Gap filling |
| Zero budget, prototype only | Short-lived scripts |
| Internal tool with dedicated ops team | You can afford breakage |
Even then, consider CVM open data bulk downloads before writing HTML parsers.
When to use apicvm
| Scenario | API fits better |
|---|---|
| Production microservice: "get VALE3 latest ITR" | Stable contract |
| AI agent tools called repeatedly | Predictable errors, auth |
| RAG pipeline with citations | UUID + page callbacks |
| Team without scraper maintenance | Portal changes are externalized |
Side-by-side: same task
Task: List Petrobras DFP filings for 2024.
Scraper path:
- Navigate CVM company search or maintain CNPJ
33000167000101 - Parse filing table HTML
- Extract PDF URLs; handle relative paths and redirects
- Build your own metadata schema
apicvm path:
export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'
curl -H "Authorization: Bearer $APICVM_KEY" \
"$APICVM_URL/v1/documents?ticker=PETR4&type=DFP&year=2024&perPage=20"Pick document.id → download or extract. No HTML parser in your codebase.
Hybrid approach
Many teams scrape or bulk-download once for historical gaps, then use apicvm for ongoing production lookups. Keep scrapers as fallback only if you document the maintenance cost.
Current limitations
- apicvm is a paid API ($9/month) with rate limits — scraping has no subscription but higher ops cost.
- Corpus sync depends on ingestion — not guaranteed same-day as CVM publication.
- Scraping may reach datasets outside apicvm MVP scope (funds, penalties, etc.).
Next steps
Ready to integrate?
Get an API key and start querying Brazilian CVM filings programmatically.