Brazil Bonus Share Disclosures API: Track Stock Dividends (Bonificação) from CVM Filings

The problem

Brazilian payout research splits into three events that English SERPs often collapse:

1. Cash dividends and JCP — per-share amounts in BRL, record and payment dates.
2. Bonus shares (bonificação) — shareholders receive additional shares at a defined ratio (a stock dividend), not cash.
3. Splits and reverse splits — desdobramento / grupamento change nominal share count without the same legal framing as bonificação.

Market data APIs summarize cash flows and sometimes apply corporate-action factors. They rarely store the filing text that defines whether a event was bonificação versus split. Scraping the CVM portal works for one ticker and breaks on a multi-name 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 — the same pattern as List avisos aos acionistas via API, scoped to stock bonus events.

For treasury repurchases, see Brazil share buyback disclosures API. For the generic poll loop on all material facts, see Brazil material facts monitoring API.

Which filing type carries bonificação?

Brazilian issuers do not expose a dedicated type=BONUS_SHARE in the apicvm document list. Stock dividends usually surface under:

Practical rule: query AVISO_AOS_ACIONISTAS first for each ticker, add FATO_RELEVANTE when you run a broad corporate-actions monitor, then filter rows by name keywords (Bonificacao, bonificação, bonus, stock dividend) before downloading PDFs. After download, search PDF text for bonificação, proporção, crédito, or data do ex.

On VALE3 for calendar year 2026, the demo corpus returned 14 combined FATO_RELEVANTE and AVISO_AOS_ACIONISTAS rows with no bonificacao token in name (demo API, queried 2026-09-15). Other issuers with active bonificação programs follow the same list-and-download workflow when those tokens appear. Zero rows in a given year does not prove no bonus share occurred — see limitations below.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List shareholder notices — GET /v1/documents with type=AVISO_AOS_ACIONISTAS (optionally add FATO_RELEVANTE)
3. Scope with year and optional dateRef; sort with field=dateRef&order=desc
4. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
5. 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 shareholder notices for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=AVISO_AOS_ACIONISTAS&year=2025&perPage=50&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: Narrow to bonificação-related rows

Filename tokens on the CVM IPE feed are predictable enough for a first-pass filter:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=AVISO_AOS_ACIONISTAS&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("Bonificacao|bonificacao|bonus|stock.dividend"; "i")) | {id, dateRef, name}'

Combine with material facts when you already poll earnings-season clusters:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=AVISO_AOS_ACIONISTAS,FATO_RELEVANTE&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("Bonificacao|bonificacao|bonus"; "i")) | {id, type, dateRef, name}'

After download, search PDF text for bonificação em ações or proporção de bonificação for validation. Extraction credits apply only if you use the text-extraction endpoint.

Step 3: Download a bonificação notice PDF

curl -H "Authorization: Bearer $APICVM_KEY" \
  -o bonus-share-notice.pdf \
  "$APICVM_URL/v1/documents/<document-id>/file"

Download does not consume extraction credits.

Example: Python watchlist for bonus share filings

Poll avisos across a payout-focused watchlist. Persist seen in your database in production.

import os, time, requests, re
from datetime import datetime

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}
WATCH = ["PETR4", "VALE3", "ITUB4", "BBDC4", "ABEV3"]
YEAR = datetime.utcnow().year
BONUS_RE = re.compile(
    r"bonificacao|bonificação|bonus|stock.dividend", re.I
)
seen = set()  # load from your store on startup

def list_avisos(ticker):
    r = requests.get(
        f"{BASE}/v1/documents",
        headers=H,
        params={
            "ticker": ticker,
            "type": "AVISO_AOS_ACIONISTAS",
            "year": YEAR,
            "perPage": 50,
            "field": "dateRef",
            "order": "desc",
        },
    )
    if r.status_code == 429:
        time.sleep(5)
        return list_avisos(ticker)
    r.raise_for_status()
    return r.json()["data"]

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

Wire this into GitHub Actions or extend the diff pattern from Brazil material facts monitoring API.

Where bonificação sits in the filings stack

Brazil regulatory filings API explains the full layer map. For quotes versus filings, see Brazil financial data API.

Current limitations

• Documents, not settlement — apicvm does not credit shares to your ledger or return live outstanding share count from the exchange.
• Keyword filters are heuristic — name tokens help; false negatives are possible if issuers use unusual titles.
• Polling, not push — no webhook when CVM publishes a new aviso. 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.

Next steps

• Read the API docs
• Get an API key
• List avisos aos acionistas — focused AVISO_AOS_ACIONISTAS reference

Related guides

• Brazil dividend disclosures API — cash and JCP payouts
• Brazil stock split disclosures API — desdobramento and grupamento
• Brazil IPE disclosures API — all five IPE types
• Extract text from CVM PDFs for AI agents — async markdown extraction