Grana - IR da bolsa automático: API integration & OpenFinance Brasil

1. Login & consent flow

Reproduce the Grana account binding flow plus the B3 Investor Area consent step. Outputs a long-lived refresh token, a short-lived access token and a consent record (B3 CPF binding, scope, expiry). Used to keep portfolio sync alive without prompting users every day.

2. Portfolio & trades export

Daily snapshot of every open position, plus the underlying trade tape from B3 (data, ticker, quantity, preço médio, corretora, mercado). Includes options strikes and futures contracts (IND, WIN, DOL, WDO, BIT, CCM). Used by reconciliation engines and risk dashboards.

3. DARF & IRPF artifacts

Monthly DARF JSON (lucro tributável, alíquota, valor devido, vencimento, código de receita), retroactive recalculation since 2020, and the binary file Grana generates for the Receita Federal IRPF program. Used by tax bureaus and accounting SaaS.

4. Dividend & performance feed

Per-ticker dividend events, JCP withholding, FII rendimentos, amortizations, and consolidated rentabilidade vs IBOV / CDI / IPCA. Used to drive yield-on-cost cards, peer-benchmark widgets and "rentabilidade vs outros investidores" comparisons.

5. Tax Optimizer signals

Webhook stream emitting suggested operations that legally reduce taxable profit without changing target allocation — the same logic exposed in Grana's premium plan. Used to power tax-aware rebalancing inside robo-advisors and family-office platforms.

6. Pix DARF settlement bridge

Generate the Pix QR / copia-e-cola for a given DARF and confirm settlement. Used by financial-control teams that want to settle taxes from an enterprise account rather than per-employee.

Scenario A — Accounting SaaS for active investors

Context: A Brazilian accounting platform serves day traders and FII investors. Manually transcribing notas de corretagem is slow and error-prone.

Data & APIs: Trade tape + DARF API + dividend feed; OAuth refresh per investor.

OpenData mapping: The trade tape mirrors OpenFinance Brasil's investment resource (operação, tipo, preço, quantidade), so the same pipeline can later ingest brokerage data via the BCB-mandated APIs.

Scenario B — Robo-advisor with tax-aware rebalancing

Context: A wealth-tech platform wants to suggest rebalances that respect the user's monthly taxable position.

Data & APIs: Tax-Optimizer webhook + DARF endpoint + custody snapshot. Each rebalance proposal carries an estimated DARF delta.

OpenData mapping: Decision metadata (sugestão_codigo, ticker, quantidade) is structured to plug into OpenFinance Brasil "Investimentos – posição" responses without schema drift.

Scenario C — Bank's annual IRPF concierge

Context: A bank wants to offer "one-click IRPF" to its private clients during the March–May filing window.

Data & APIs: IRPF auto-fill generator + Pix DARF settlement bridge. The bank pre-fills Bens e Direitos, Rendimentos Isentos and Rendimentos Sujeitos à Tributação and offers Pix to settle every pending DARF.

OpenData mapping: Output adheres to the Receita Federal IRPF import schema; downstream systems treat it as a normalised tax artifact.

Scenario D — Family office consolidated reporting

Context: A family office consolidates multiple individuals' B3 portfolios for quarterly reporting.

Data & APIs: Bulk login orchestration, performance feed, dividends, IBOV/CDI/IPCA benchmarks, peer-cohort percentile.

OpenData mapping: Each individual's consent token is stored centrally; data normalises into a single OpenFinance-style "investments" namespace shared across reports.

Scenario E — Compliance retrobackfill since 2020

Context: A brokerage migrating clients to a new platform needs to verify there are no missing DARFs or unreported gains since January 2020.

Data & APIs: Pendency map + retroactive DARF recalculation + trade tape; results land in a CSV/JSON pack ready for compliance review.

OpenData mapping: Output cross-references B3 custody history, so the same evidence pack can be sent to the broker, the client and the tax bureau.

API example: B3 portfolio snapshot

// GET portfolio snapshot for a connected investor
GET /api/v1/grana/portfolio?cpf_hash=<HASHED_CPF>&date=2026-04-30
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

200 OK
{
  "as_of": "2026-04-30",
  "positions": [
    {"ticker":"PETR4","qty":300,"avg_price":33.21,"broker":"XP","market":"BOVESPA"},
    {"ticker":"HGLG11","qty":80,"avg_price":162.40,"broker":"Itaú","market":"BOVESPA"},
    {"ticker":"WINJ26","qty":2,"avg_price":133250,"broker":"Clear","market":"BMF"}
  ],
  "currency":"BRL"
}

API example: monthly DARF retrieval

// POST month-end DARF computation
POST /api/v1/grana/darf/compute
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "cpf_hash":"<HASHED_CPF>",
  "year":2026,
  "month":4,
  "asset_class":["acoes","fii","day_trade"]
}

200 OK
{
  "month":"2026-04",
  "darfs":[
    {"asset_class":"acoes","lucro":1820.55,"aliquota":0.15,"valor":273.08,"codigo":"6015","vencimento":"2026-05-31"},
    {"asset_class":"day_trade","lucro":640.10,"aliquota":0.20,"valor":128.02,"codigo":"6015","vencimento":"2026-05-31"}
  ],
  "pix_qrcode":"00020126..."
}

API example: Tax-Optimizer webhook

// Webhook payload pushed when a saving opportunity is detected
POST https://your-domain.com/webhooks/grana/optimizer
X-Grana-Signature: sha256=...
Content-Type: application/json

{
  "event":"optimizer.suggestion.created",
  "cpf_hash":"<HASHED_CPF>",
  "as_of":"2026-04-29",
  "suggestion":{
    "code":"OPT-2026-04-A",
    "ticker":"ITSA4",
    "side":"SELL",
    "qty":150,
    "estimated_tax_saving_brl":412.70,
    "rationale":"realize loss to offset accumulated taxable profit"
  }
}

// Errors return RFC 7807 problem+json with 4xx/5xx

Auth, retries and rate limits

OAuth 2.0 / FAPI-style authorization on top of the consent flow; rotating refresh tokens scoped per investor. Idempotency keys on every write endpoint, exponential backoff on B3 ingestion errors, and a hard 5 req/sec ceiling per CPF to stay within B3 Investor Area quotas. Webhook signatures are HMAC-SHA256 with rotating secrets.

Regulatory alignment

Integrations align with the Banco Central do Brasil OpenFinance Brasil framework — now five years old, with over 800 institutions, more than 70 million users and 91 million active authorisations as of mid-2025. Investment data is in scope under Phase 4 of the rollout, and the same FAPI 1.0, mTLS and consent-receipt patterns apply to Grana ingestion.

For tax artifacts, output respects the Receita Federal IRPF import schema; for personal data, processing is governed by Brazil's LGPD (Lei Geral de Proteção de Dados) with explicit user authorisation, purpose limitation and short retention windows.

Privacy controls

• CPFs hashed at rest; never stored in clear in our pipelines.
• Consent receipts per investor: scope, expiry, IP, user-agent, timestamp.
• Per-customer KMS-backed token vault; tokens rotate on every refresh.
• Audit log of every B3 pull and every DARF/IRPF artifact emission.
• "Right to be forgotten" endpoint that purges history within 30 days.

Kinvo

Multi-broker portfolio aggregator with B3, BTG Pactual, Itaú, XP and Órama imports. Holds consolidated positions across fixed and variable income; users who track Grana's tax view often also need Kinvo's broader allocation feed.

Status Invest

Equity research and screener app focused on fundamentals and FII metrics. Holds price history, dividend yield and indicator data — typically combined with Grana's tax history for "after-tax yield" dashboards.

Investidor 10

Stock-research app with detailed company sheets, dividend history and ranking tools. Frequently sits alongside Grana when investors compare expected dividend cash flow to taxable distributions.

Gorila

Portfolio tracker covering fixed income, stocks, FIIs and crypto. Keeps allocation and performance data; integrators sometimes mirror Gorila exports next to Grana DARFs to feed unified reporting.

TradeMap

Market-data and news app with more than 3 million users. Holds quotes, news and watchlists — paired with Grana for a "news → position → tax" view across the same set of tickers.

Bússola do Investidor

Portfolio and IR-calculation app oriented at variable-income investors. Users often migrate between Bússola and Grana, so unified transaction exports across both platforms are a recurring ask.

IRPFbolsa

Manual IR calculator for stock-market operations. Holds normalised trade and cost-basis records; a common "before Grana" workflow that integrators sometimes need to migrate into Grana-style auto-fill files.

ReVar (B3 + Receita Federal)

Official tax-calculation tool from the B3 / Receita Federal partnership. Holds variable-income tax computations directly from B3; pairs well with Grana for cross-check reconciliations.

Mobills

Personal-finance app with budgeting and investment tracking modules. Holds bank, card and basic investment data; users sometimes route Grana DARFs into Mobills as scheduled bills to pay.

Toro Investimentos

Brokerage app holding orders, custody and account statements. Connects with Grana indirectly via B3; useful when integrators need raw nota de corretagem data alongside Grana's tax view.

About our studio

OpenFinance Lab is an independent technical studio focused on App interface integration and authorized API integration, with a strong emphasis on Latin-American fintech and OpenFinance Brasil. Our engineers come from brokerages, payment service providers and B3-aware infrastructure teams.

• Brazil-focused track record: B3 ingestion, IRPF artifacts, Pix/DARF flows.
• OpenFinance Brasil expertise: FAPI 1.0, mTLS, dynamic client registration.
• Custom Python / Node.js / Go SDKs, OpenAPI specs, CI-ready harnesses.
• Source code delivery from $300 — runnable API source plus full documentation; pay after delivery upon satisfaction.
• Pay-per-call hosted API — access our endpoints and pay only per call, no upfront fee.

Contact

For quotes, sandbox access or to submit your target app and requirements, open our contact page:

Contact page

Send us the app name (Grana - IR da bolsa automático already counts), your specific data needs, and any sandbox or test-account credentials you can provide.

Engagement workflow

1. Scope confirmation: which Grana data streams (B3 portfolio, DARF, IRPF, dividends, optimizer) and which OpenFinance Brasil endpoints you need.
2. Protocol analysis and API design: B3 + Grana flows mapped, consent and token strategy locked (2–5 business days).
3. Build and internal validation: against staging CPF, with golden-file fixtures for DARF and IRPF outputs (3–8 business days).
4. Documentation, code samples, OpenAPI spec, automated tests (1–2 business days).
5. Delivery and runbook handover: typical first delivery in 5–15 business days; B3 / Receita Federal approvals may extend timelines.

FAQ

What data can be extracted from Grana via API integration?

Does Grana follow OpenFinance Brasil standards?

How long does delivery take?

How do you handle compliance with LGPD and Receita Federal?