Brazil Lease Liability Disclosures API: Track IFRS 16 Obligations from CVM Filings

The problem

Lease surveillance splits into three stacks that English search results often merge:

1. Market data terminals — sometimes show lease-adjusted net debt when vendors parse statements. They rarely store the issuer’s regulatory PDF with maturity buckets, extension options, and CPI indexation clauses.
2. Periodic packages — DFP, ITR, and FRE with CPC 06 / IFRS 16 tables, sensitivity on discount rates, and narrative on store openings or fleet contracts. Essential for retail, logistics, and infrastructure credit work, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes when a material lease renegotiation, impairment tied to closed stores, or sale-and-leaseback 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 lease liability workflows.

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

Which filing type carries lease liability detail?

Brazilian issuers do not expose a dedicated type=LEASE in the apicvm document list. Lease 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 lease keywords, and pull FRE once per year for structural context. After download, search PDF text for arrendamento, leasing, IFRS 16, CPC 06, right-of-use, passivo de arrendamento, locação, or subarrendamento.

Issuer titles vary: some retailers file long name tokens; pure-play industrials may bury lease tables only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove the issuer has no material leases — 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 lease-heavy ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=RADL3&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 (IFRS 16 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 lease-related material facts

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=SMFT3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("arrendamento|leasing|IFRS.?16|CPC.?06|locação|locacao|sale.and.lease|subarrend"; "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 lease-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 = ["RADL3", "SMFT3", "MGLU3", "LREN3"]
LEASE_RE = re.compile(
    r"arrendamento|leasing|IFRS.?16|CPC.?06|locação|locacao|"
    r"sale.and.lease|subarrend|right.of.use|passivo de arrend",
    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 LEASE_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"LEASE {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 lease liabilities sit 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 lease-driven impairments appear, cross-check Brazil asset impairment write-down disclosures API. When leverage covenants reference adjusted EBITDA, see Brazil debt covenant disclosures API. When lease expense sits next to equity incentives in compensation notes, see Brazil stock-based compensation disclosures API.

Current limitations

• Documents, not parsed lease engines — apicvm does not return lease-adjusted net debt, automatic maturity ladders, or discount-rate sensitivity parsed from tables.
• Keyword filters are heuristic — name tokens help on the event layer; many CPC 06 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 debt covenant disclosures API — refinancing and leverage on the event layer
• Brazil segment reporting disclosures API — revenue mix when store footprint shifts
• 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