Brazil Cash Flow Statement Disclosures API: Track Operating, Investing, and Financing Cash from CVM Filings

The problem

Cash-flow surveillance splits into three stacks that English search results often merge:

1. Market data terminals — show price, yield, and sometimes vendor-calculated FCF. They rarely store the issuer’s regulatory PDF with the full DFC, reconciliation to net income, and footnotes on non-cash adjustments.
2. Periodic packages — DFP, ITR, and FRE with operating/investing/financing lines, capex tables, and liquidity risk factors. Essential for commodity, utility, and capex-heavy issuers, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes and shareholder notices when a debt issuance, dividend with leverage impact, or asset sale changes near-term cash.

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 cash flow workflows.

For dividend and buyback cash uses, cross-check Brazil dividend disclosures API and Brazil share buyback disclosures API. This guide focuses on the API list-and-download pattern for DFC and related annexes.

Which filing type carries cash flow detail?

Brazilian issuers do not expose a dedicated type=CASH_FLOW 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 fluxo de caixa / cash flow / DFC, poll FATO_RELEVANTE for debt and asset-sale keywords, and pull FRE once per year for structural liquidity context. After download, search PDF text for fluxo de caixa, DFC, operacional, investimento, financiamento, capex, CAPEX, juros, dividend, amortização, hedge, or caixa e equivalentes.

Issuer packaging varies: some filers embed the DFC 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 DFC — 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 cash-flow annexes — name tokens such as Fluxo, DFC, or Cash
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
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 capex-heavy 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 DFC

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

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

Step 3: List cash-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("caixa|cash|deb[eê]nture|emiss[aã]o|amortiz|capex|investimento|refinanc"; "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 liquidity and capex narrative, list the latest FRE:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=WEGE3&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 cash-flow-statement.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", "WEGE3", "BBAS3"]
CF_RE = re.compile(
    r"caixa|cash|fluxo|dfc|capex|debenture|emiss[aã]o|amortiz|refinanc|"
    r"investimento|dividend|buyback|tesouraria",
    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",
            "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 CF_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"CF {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 cash flow sits in the filings stack

Brazil regulatory filings API explains the full layer map. Pair DFC pulls with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When operating cash ties to receivables and inventory, cross-check Brazil working capital disclosures API. When net income and cash diverge because of revenue timing, see Brazil revenue recognition disclosures API. For the broader Brazil financial data API pillar, treat cash flow as one statement cluster inside periodic filings.

Current limitations

• Documents, not parsed cash engines — apicvm does not return operating, investing, or financing line items parsed from tables or compute FCF.
• Annex naming varies — name filters are heuristic; some DFC 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 working capital disclosures API — balance-sheet drivers of operating cash
• Brazil revenue recognition disclosures API — non-cash earnings vs cash collection
• Brazil dividend disclosures API — financing cash outflows to holders
• Access DFP and ITR notes by section name — annex filters before download
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction