---
title: "Calculadora de Dividend Yield (DY) — Carteira de Renda Passiva"
method: POST
path: "/api/v1/calc/dividend-yield"
tags: ["calc", "financas"]
---

# Calculadora de Dividend Yield (DY) — Carteira de Renda Passiva

`POST /api/v1/calc/dividend-yield`

## Request

- Base URL: `https://api.calculas.com.br`
- URL: `https://api.calculas.com.br/api/v1/calc/dividend-yield`
- Auth: HTTP bearer

Calcule o dividend yield (DY) ponderado de uma carteira inteira (até 50 ativos: ações, FIIs, ETFs) e a renda passiva mensal/anual gerada. Mostra DY por ativo, valor investido por ticker e DY médio ponderado pelo valor investido.

## Request body

- object
  - `ativos` object[], required: Lista de ativos da carteira (1 a 50). Cada item: { ticker, precoAcaoCents, dividendosAnualCents, quantidade }. BREAKING vs v1.x: antes era 1 ativo escalar (precoAcaoCents+dividendosPorAcaoAnualCents+quantidadeAcoes+tipoAtivo). Para 1 ativo só, passe um array com 1 elemento.
    - `ticker` string, required: Código do ativo na B3 (1 a 10 caracteres). Ex: ITUB4, KNRI11, BOVA11.
    - `precoAcaoCents` integer, required: Preço atual da cota/ação em centavos. Ex: R$ 30,00 → 3000.
    - `dividendosAnualCents` integer, required: Total de dividendos por cota nos últimos 12 meses em centavos. Ex: R$ 2,40 → 240.
    - `quantidade` integer, required: Quantidade de cotas/ações desse ticker (1 a 10.000.000).
    - `tipo` 'dividendo' | 'jcp': Tipo de provento (audit fix v2.3). "dividendo" (padrão): isento de IR para PF (Lei 9.249/95 art. 10). "jcp" (Juros sobre Capital Próprio): IRRF 15% retido na fonte (Lei 9.249/95 art. 9º). FIIs use "dividendo" (isento sob 3 condições Lei 11.033/04 art. 3º).
  - `currentDate` string, date-time: ISO-8601 com offset. Default: tempo do servidor. Use pra reprodutibilidade / cache semantico.

## Response `200`

OK

- object
  - `ok` true, required
  - `data` object, required: Resultado dependente da calc — ver schema individual
  - `meta` object

## Other responses

- `422`: Input invalido (Zod parse falhou)
- `500`: Engine error

---

[API](https://skmtc.dev/calculas/apis/contai-api.md) · [All operations](https://skmtc.dev/calculas/apis/contai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculas/apis/contai-api/revisions/26a00749292b?raw)