Brazil Balance Sheet Disclosures API: Track Assets, Liabilities, and Equity from CVM Filings

The problem

Balance-sheet surveillance splits into three stacks that English search results often merge:

1. Market data terminals — show vendor-calculated net debt, enterprise value, and leverage. They rarely store the issuer’s regulatory PDF with the full BP, debt footnotes, and equity reconciliation in one place.
2. Periodic packages — DFP, ITR, and FRE with assets, liabilities, equity, and explanatory notes on borrowings, leases, and contingencies. Essential during earnings season and credit reviews, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes and investor presentations when management announces a refinancing, asset sale, capital injection, or covenant waiver that changes the balance sheet before the next periodic filing.

Scraping the CVM portal works for one ticker and breaks on a diversified watchlist. Bulk open-data ZIPs are dataset-oriented, not ticker-first. You want GET /v1/documents with stable document.id, then GET /v1/documents/:id/file for the original PDF — scoped to balance sheet workflows.

For receivables and inventory detail inside assets, cross-check Brazil working capital disclosures API. For covenant language tied to leverage tests, see Brazil debt covenant disclosures API. For IFRS 16 lease lines on the liability side, see Brazil lease liability disclosures API. This guide focuses on the API list-and-download pattern for BP and related annexes.

Which filing type carries balance sheet detail?

Brazilian issuers do not expose a dedicated type=BALANCE_SHEET in the apicvm document list. Detail usually appears under:

Practical rule: list latest ITR/DFP for each ticker during 3Q ITR season, filter annex rows whose name mentions patrimônio / balanço / balance / ativo / passivo, poll FATO_RELEVANTE for debt and refinancing keywords, and pull FRE once per year for structural leverage context. After download, search PDF text for balanço patrimonial, ativo, passivo, patrimônio líquido, dívida, empréstimo, debênture, caixa, liquidez, alavancagem, or net debt.

Issuer packaging varies: some filers embed the BP inside a single financial-statements PDF; others split balance sheet, income statement, and cash flow into separate annex rows. Zero rows with a name filter does not mean the issuer omitted a BP — broaden the list before download.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List periodic packages — GET /v1/documents with type=ITR or type=DFP and year
3. Narrow to balance-sheet annexes — name tokens such as Patrimônio, Balanço, or Balance
4. Optional section prefixes — GET /v1/document-prefixes when you need a named slice inside a large PDF (filter by section name)
5. List event filings — GET /v1/documents with type=FATO_RELEVANTE or APRESENTACAO_INVESTIDORES
6. Scope with dateRef; sort with field=dateRef&order=desc
7. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
8. Optional (Pro): page-level markdown — POST /v1/document-text-extractions with async callback

Auth: Authorization: Bearer or X-API-Key. Try VALE3 without a key via the demo API.

Setup

export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'

Step 1: List quarterly filings for a leverage-sensitive ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=ITR&year=2025&perPage=10&field=dateRef&order=desc"

Response rows include stable id, dateRef, name, and nested company metadata. Use id as your cache key — not name, which can be long and encoding-sensitive.

Paginate with page= when meta.lastPage > 1. perPage maxes at 50.

Step 2: Filter annex rows that likely contain the balance sheet

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=ITR&year=2025&perPage=50&name=Patrim" \
  | jq '.data[] | {id, type, dateRef, name}'

If that returns few rows, retry with name=Balan or name=Demonstra or list without name and inspect titles manually.

Step 3: List balance-sheet-related material facts

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("dívida|divida|empréstimo|debênture|refinanc|caixa|liquidez|alavanc|net debt|patrimônio"; "i")) | {id, type, dateRef, name}'

On the public demo (VALE3 only), swap the host path to /v1/demo/documents with the same query parameters for smoke tests.

For annual leverage narrative, list the latest FRE:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=BBDC4&type=FRE&year=2025&perPage=5&field=dateRef&order=desc" \
  | jq '.data[] | {id, dateRef, name}'

Step 4: Download the filing PDF

DOC_ID=123456
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/$DOC_ID/file" -o balance-sheet.pdf

Store document.id in your warehouse. Re-download when the issuer replaces a filing; do not assume name alone is a stable key.

Step 5: Watchlist poll (Python sketch)

import os, re, requests

BASE = os.environ["APICVM_URL"]
KEY = os.environ["APICVM_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
WATCH = ["PETR4", "VALE3", "BBDC4", "WEGE3"]
BS_RE = re.compile(
    r"dívida|divida|empréstimo|debênture|refinanc|caixa|liquidez|alavanc|"
    r"patrimônio|balanço|ativo|passivo|net debt|covenant|amortiza",
    re.I,
)
seen = set()

def list_events(ticker):
    r = requests.get(
        f"{BASE}/v1/documents",
        headers=HEADERS,
        params={
            "ticker": ticker,
            "types": "FATO_RELEVANTE,COMUNICADO_AO_MERCADO,APRESENTACAO_INVESTIDORES",
            "year": 2025,
            "perPage": 50,
            "field": "dateRef",
            "order": "desc",
        },
        timeout=60,
    )
    r.raise_for_status()
    return r.json().get("data") or []

for ticker in WATCH:
    for doc in list_events(ticker):
        if doc["id"] in seen:
            continue
        if not BS_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"BS {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions CVM filings monitor or extend the diff pattern from Brazil material facts monitoring API. For NLP over downloaded PDFs, see extract text from CVM PDFs for AI agents.

Where the balance sheet sits in the filings stack

Brazil regulatory filings API explains the full layer map. Pair BP pulls with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When impairments hit asset lines, cross-check Brazil asset impairment write-down disclosures API. When operating profit and balance-sheet leverage diverge from cash, reconcile via Brazil income statement disclosures API and Brazil cash flow statement disclosures API. For the broader Brazil financial data API pillar, treat the balance sheet as one statement cluster inside periodic filings.

Current limitations

• Documents, not parsed balance-sheet engines — apicvm does not return total assets, net debt, or equity parsed from tables or compute leverage ratios.
• Annex naming varies — name filters are heuristic; some BP PDFs share a generic financial-statements title.
• Polling, not push — no webhook when CVM publishes a new fact. Schedule polls and diff document.id.
• Ingestion lag — sync is not real-time. A notice may appear on the portal before it is in the corpus.
• Corpus coverage — not every issuer or period is present. Validate against the portal for production compliance use cases.
• Demo scope — /v1/demo/* is limited to VALE3. Other tickers need a production key.
• ITR disambiguation — Informações Trimestrais (CVM quarterly financials), not US income tax return software.

Next steps

• Read the API docs
• Get an API key
• Brazil financial statements API — DFP and ITR package overview

Related guides

• Brazil income statement disclosures API — link earnings to equity changes
• Brazil cash flow statement disclosures API — reconcile cash on the BP to the DFC
• Brazil working capital disclosures API — receivables and inventory inside current assets
• Brazil debt covenant disclosures API — tests tied to reported leverage
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction