Brazil Working Capital Disclosures API: Track Receivables, Inventory, and Payables from CVM Filings

The problem

Working-capital surveillance splits into three stacks that English search results often merge:

1. Market data terminals — sometimes show DSO or inventory turns when vendors parse statements. They rarely store the issuer’s regulatory PDF with aging buckets, allowance movements, and inventory obsolescence policies.
2. Periodic packages — DFP, ITR, and FRE with CPC/IFRS notes on receivables, estoques, fornecedores, and liquidity. Essential for retail, agribusiness, and industrial credit work, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes when a material receivables provision, inventory write-down, or supplier-payment program is disclosed outside the normal filing calendar.

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 working capital workflows.

For company-specific walkthroughs, see RADL3 earnings quality on DFP footnotes. This guide focuses on the API list-and-download pattern across periodic and event layers.

Which filing type carries working capital detail?

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

Practical rule: list latest ITR/DFP for each ticker during 3Q ITR season, narrow annex rows with name filters for notes (notas, notes, explicativas), poll FATO_RELEVANTE for receivables/inventory keywords, and pull FRE once per year for structural context. After download, search PDF text for contas a receber, estoques, fornecedores, PDD, perdas esperadas, aging, inventário, receivables, inventory, trade payables, or provisão.

Issuer titles vary: some retailers file long name tokens; agribusiness issuers may bury inventory tables only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove immaterial working capital — see limitations below.

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 explanatory notes — name=Notas or related annex tokens
4. List event filings — GET /v1/documents with type=FATO_RELEVANTE
5. Scope with dateRef; sort with field=dateRef&order=desc
6. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
7. 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 latest ITR package for a working-capital-heavy ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=MGLU3&type=ITR&year=2025&perPage=5&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.

Step 2: Narrow to explanatory notes (receivables and inventory tables live here)

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

Combine with access DFP and ITR notes by section name when your catalog uses English or abbreviated tokens.

Step 3: List working-capital-related material facts

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=SLCE3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("recebível|recebiveis|estoques|inventário|inventario|PDD|perda esperada|provisão|provisao|write.off|contas a receber"; "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.

Step 4: Download the filing PDF

DOC_ID=123456
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/$DOC_ID/file" -o working-capital-notes.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 = ["MGLU3", "RADL3", "SLCE3", "ABEV3"]
WC_RE = re.compile(
    r"recebível|recebiveis|estoques|inventário|inventario|PDD|"
    r"perda esperada|provisão|provisao|write.off|contas a receber|"
    r"fornecedores|inventory|receivables",
    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 WC_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"WC {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 working capital sits in the filings stack

Brazil regulatory filings API explains the full layer map. Pair periodic note pulls with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When inventory or receivables drive impairments, cross-check Brazil asset impairment write-down disclosures API. When mix shifts across segments, see Brazil segment reporting disclosures API. When operating leases inflate balance-sheet liabilities beside receivables, see Brazil lease liability disclosures API. For the broader Brazil financial data API pillar, treat working capital as one note cluster inside periodic filings.

Current limitations

• Documents, not parsed working-capital engines — apicvm does not return DSO, DIO, DPO, or aging ladders parsed from tables.
• Keyword filters are heuristic — name tokens help on the event layer; many receivables tables appear only inside periodic PDF notes without matching keywords.
• 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
• Extract CVM financial footnotes from DFP — broader note workflow

Related guides

• Brazil lease liability disclosures API — IFRS 16 obligations beside current assets
• Brazil asset impairment write-down disclosures API — inventory and receivable write-downs on the event layer
• 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