Investimentos

Documentação dos endpoints para consulta de investimentos vinculados a um item, incluindo posições históricas (snapshots) e movimentações.

Endpoints Disponíveis

• Listar Investimentos - Lista todos os investimentos vinculados a um item
• Listar Snapshots - Lista as posições históricas (fotos) dos investimentos de um item
• Listar Movimentações - Lista as movimentações de um investimento específico

O que guardamos sobre investimentos

Campos obrigatórios (sempre preenchidos)

• Vínculo (itemId) — a qual conexão (instituição) o investimento pertence
• Nome (name) — nome do investimento
• Tipo (type) — a categoria (renda fixa, previdência, fundos, ações, ETF, COE)
• Status (status) — ativo, pendente ou resgatado
• Moeda (currency) — moeda do investimento
• Valor líquido atual (currentNetAmount) — quanto vale já descontando taxas e impostos
• Datas de controle (createdAt, updatedAt) — criação e última atualização do registro

Campos opcionais (nem sempre vêm da instituição)

Identificação

• code — código (no caso de fundos, o CNPJ do fundo)
• isin — identificador global (ISIN)
• number — número do investimento
• owner — titular/dono
• issuer — emissor

Classificação

• subtype — subtipo (CDB, LCI, previdência, ações, fundo imobiliário, etc.)

Rentabilidade (vem principalmente de fundos)

• lastMonthRate — rentabilidade do último mês
• lastTwelveMonthsRate — rentabilidade dos últimos 12 meses
• annualRate — taxa anual

Posição atual (uma "foto" do investimento numa data de referência)

• currentDate — data de referência
• currentValue — valor da cota
• currentQuantity — quantidade de cotas
• currentGrossAmount — valor bruto (com impostos)
• incomeTaxes — imposto de renda aplicado
• financialTaxes — imposto financeiro aplicado

Condições de renda fixa

• rate / rateType — taxa contratada e seu tipo (CDI, Selic, IPCA, etc.)
• fixedAnnualRate — taxa anual fixa
• issuedAt — data de emissão
• expiresAt — data de vencimento

Lucro e movimentações

• amountProfit — lucro líquido até o momento (pode ser negativo, indicando prejuízo)
• amountWithdrawal — valor disponível para resgate
• amountOriginal — valor originalmente investido

Tipos de Dados

Status (status)

• ACTIVE: Ativo
• PENDING: Pendente
• TOTAL_WITHDRAWAL: Resgatado totalmente
• UNKNOWN: Desconhecido

Tipo de Taxa (rateType)

Indexador da taxa contratada. Pode ser null quando não informado.

• CDI: Certificado de Depósito Interbancário
• SELIC: Taxa Selic
• DOLAR: Dólar
• EURO: Euro
• IGPM: Índice Geral de Preços do Mercado
• IPCA: Índice de Preços ao Consumidor Amplo

Tipo de Movimentação (type em transações)

• BUY: Compra/aplicação
• SELL: Venda/resgate
• TRANSFER: Transferência
• TAX: Cobrança de imposto
• INTEREST_ACCRUAL: Rendimento / Juros
• MATURITY: Vencimento
• MARK_TO_MARKET: Marcação a Mercado
• COME_COTAS: Come-Cotas

Tipos e Subtipos de Investimento

O campo type indica a categoria do investimento e subtype o detalhamento dentro da categoria.

Renda Fixa (type: FIXED_INCOME)

Previdência (type: SECURITY)

Fundos (type: MUTUAL_FUND)

Ações e similares (type: EQUITY)

ETF (type: ETF)

COE (type: COE)

Outros (type: OTHER)

Observações

• Valores monetários são retornados como string formatada na moeda do investimento (currency).
• As taxas de rentabilidade (lastMonthRate, lastTwelveMonthsRate, annualRate, rate, fixedAnnualRate) são percentuais com até 4 casas decimais.
• O campo amountProfit pode ser negativo, indicando prejuízo.
• Os campos de posição atual (currentValue, currentQuantity, currentGrossAmount, impostos) representam uma "foto" numa data de referência (currentDate); o histórico dessas fotos está disponível no endpoint de snapshots.