Investimento

A entidade Investimento é recuperada não apenas de Corretores (XP, Clear), mas também de instituições bancárias de varejo e empresariais.

A lista de investimentos de uma instituição pode ser diferenciada com base no tipo do investimento. Cada tipo de investimento possui um conjunto de campos que se relacionam ao tipo específico de investimento.

Propriedade	Tipo	Opcional	Descrição
name	string	Não	Nome no provedor.
code	string	Sim	Código associado ao investimento. No caso de Fundos de Investimento, é o CNPJ do Fundo.
isin	string	Sim	ISIN de 12 caracteres, um identificador único global.
number	string	Sim	Número do investimento, nem sempre fornecido.
owner	string	Sim	Proprietário/beneficiário associado ao investimento.
currencyCode	CurrencyCode	Sim	Código ISO da moeda da transação, ou seja, USD.
type	InvestmentType	Não	Tipo de investimento.
subtype	InvestmentSubType	Sim	Subtipo do investimento.
lastMonthRate	number	Sim	A taxa de desempenho do último mês. Esse valor é retornado para fundos.
lastTwelveMonthsRate	number	Sim	A taxa de desempenho dos últimos 12 meses. Esse valor é retornado para fundos.
annualRate	number	Sim	Taxa de desempenho do último ano. Esse valor é retornado para fundos.
date	Date	Sim	Data de referência do valor do ativo. ou seja, ao recuperar ativos durante o fim de semana, a data provavelmente será o último dia útil.
value	number	Sim	Valor atual da cota na `data`.
quantity	number	Sim	Quantidade de cotas à disposição.
amount	number	Não	Valor bruto do investimento (impostos incluídos).
taxes	number	Sim	Impostos de renda aplicados ao investimento.
taxes2	number	Sim	Impostos financeiros aplicados ao investimento.
balance	number	Não	O valor líquido atual do investimento. Após a aplicação de taxas e impostos.
dueDate	Date	Sim	Data de vencimento.
rate	number	Sim	Percentual da taxa fixa aplicada ao investimento.
rateType	string	Sim	Tipo de taxa fixa. (um dos `CDI` \| `SELIC` \| `DOLAR` \| `EURO` \| `IGPM` \| `IPCA` \| null)
fixedAnnualRate	number	Sim	Taxa anual de renda fixa (Exemplo: 10,50).
issuer	string	Sim	A entidade que emitiu o investimento.
issueDate	Date	Sim	A data em que a entidade emitiu o investimento.
amountProfit	number	Sim	Lucro líquido até a data sobre o investimento. Se negativo, é perda.
amountWithdrawal	number	Sim	O valor disponível para saque.
amountOriginal	number	Sim	Valor originalmente investido.
status	InvestmentStatus	Sim	Status atual do investimento. ATIVO, PENDENTE & RETIRADA_TOTAL
institution	InvestmentInstitution	Sim	Corretora ou Instituição Financeira detentora do investimento. Isso é retornado apenas no Conector CEI B3.
transactions (deprecated)	InvestmentsTransaction	Sim	Lista de Transações de Investimentos associadas a Aplicações ou Retiradas, que afetam o valor investido. Este campo não estará presente em Aplicações criadas após 21 de março de 2023. Use o endpoint de Transações de Investimentos paginadasAPI em vez disso.
metadata	InvestmentMetadata \| null	Sim	O objeto de metadados contém "Dados de Títulos" para portabilidade de Previdências Privadas. Nota: requer recurso habilitado e assinatura Pro.
gracePeriodDate	Date	Sim	Data em que o período de carência termina. Preenchido para investimentos de renda fixa (CDB, LCI, LCA, CRI, CRA, Debênture). null para todos os outros tipos de investimento.

Investimentos em conectores de Open Finance #

Open Finance define quais dados de investimento uma instituição compartilha, portanto, alguns campos se comportam de maneira diferente dos conectores diretos:

amountProfit, annualRate, lastMonthRate e lastTwelveMonthsRate não fazem parte dos dados que as instituições compartilham através do Open Finance e são retornados como null.
rate, rateType e fixedAnnualRate descrevem a remuneração contratada de posições de renda fixa e tesouraria (por exemplo, 110% do CDI, ou uma taxa fixa de 12,5% ao ano). Eles não são uma taxa de desempenho medida, então não os leia como annualRate.
amountWithdrawal é o valor menos o que a instituição relata como bloqueado: o valor líquido para renda fixa e tesouraria, o valor bruto para fundos e ações.
taxes é o imposto de renda (IR) e taxes2 o imposto sobre transações financeiras (IOF) que a instituição relata. Para fundos, são os valores provisionados.

Status do Investimento #

Valor	Descrição
ATIVO	Comprado e verificado
PENDENTE	Validando compra
RETIRADA_TOTAL	Vendido ou transferido

Instituição do Investimento #

Propriedade	Tipo	Opcional	Descrição
name	string	Sim	Nome completo da instituição.
number	string	Sim	Número identificador para o CNPJ da instituição / Outro.

Tipos & Subtipos de Investimento #

Para entender a natureza de um investimento, você pode contar com os campos tipo e subtipo do investimento que têm relação precisa com os tipos de investimentos disponíveis no Pluggy.

Tipo	Subtipo	Descrição
RENDA_FIXA	CRI	Certificado de Recebíveis Imobiliários
RENDA_FIXA	CRA	Certificado de Recebíveis do Agronegócio
RENDA_FIXA	LCI	Letra de Crédito Imobiliário
RENDA_FIXA	LCA	Letra de Crédito do Agronegócio
RENDA_FIXA	LC	Letra de Câmbio
RENDA_FIXA	TESOURARIA	Tesouro Nacional
RENDA_FIXA	DEBÊNTURES	Dívida Corporativa
RENDA_FIXA	CDB	Certificado de Depósito Bancário
RENDA_FIXA	LIG	Letra Imobiliária Garantida
RENDA_FIXA	LF	Letra Financeira
TÍTULO	PREVIDÊNCIA	Previdência Privada
TÍTULO	PGBL	Previdência Privada
TÍTULO	VGBL	Previdência Privada
FUNDO_MUTUO	FUNDO_DE_INVESTIMENTO	Fundo de Investimento
FUNDO_MUTUO	FUNDO_DE_AÇÕES	Fundo de Ações
FUNDO_MUTUO	FUNDO_MULTIMERCADO	Fundo Multimercado
FUNDO_MUTUO	FUNDO_CAMBIAL	Fundo Cambial
FUNDO_MUTUO	FUNDO_DE_RENDA_FIXA	Fundo de Renda Fixa
FUNDO_MUTUO	FUNDO_FIP	Fundo FIP
FUNDO_MUTUO	FUNDO_OFFSHORE	Fundo Offshore
FUNDO_MUTUO	FUNDO_ETF	Fundo ETF
AÇÃO	AÇÕES	Ações, Papéis
AÇÃO	BDR	Brazilian Depositary Receipt
AÇÃO	FUNDO_IMOBILIÁRIO	Fundos Imobiliários
AÇÃO	DERIVATIVOS	Derivativos
AÇÃO	OPÇÃO	Opção
ETF	ETF	Fundos Negociados em Bolsa
COE	NOTA_ESTRUTURADA	Nota Estruturada

Tenha em mente

Alguns bancos, como NuBank e PicPay, têm opções de investimento chamadas "Cofrinhos" e "Caixinhas", que se configuram como CDBs. Assim, eles estão cobertos pela conexão e devem aparecer na seção de investimentos também.

Metadados do Investimento #

O objeto de metadados contém as informações de Portabilidade de Investimento relacionadas a ativos de Títulos como Previdência Privada. Esses campos são usados para fornecer, por exemplo, "Portabilidade de Previdência".

Propriedade	Tipo	Opcional	Descrição
taxRegime	string	Sim	Regime do imposto utilizado para o ativo.
proposalNumber	string	Sim	Identificação do número da proposta do ativo.
processNumber	string	Sim	Número de identificação do processo da instituição (`susep`).
fundName	string	Sim	Nome do fundo associado ao investimento em Títulos (pode ser diferente da propriedade `name` do investimento).
insurer	Company	Sim	A empresa seguradora do Fundo de Títulos, quando o número do processo é identificado, a seguradora sempre será retornada.

Produto de Portabilidade de Previdência

Este conjunto de dados faz parte do serviço de Portabilidade de Previdência e não será retornado na resposta do investimento até ser habilitado. Entre em contato com support@pluggy.ai ou converse conosco para testar esse recurso.

Tipos de Taxas para Ativos de Renda Fixa #

Quando o tipo de ativo é RENDA_FIXA, recuperamos 3 campos associados ao retorno esperado do investimento. Estes são rate, rateType & fixedAnnualRate. Abaixo estão alguns exemplos de como os tipos de taxas são analisados.

Exemplo	Taxa	Tipo de Taxa	Taxa Anual Fixa
100% CDI + 5%	100	CDI	5
IPC-A + 10%	100	IPCA	10
Pré-Fixado 16,76%			16.76
12% A.A			12

Exemplos de respostas #

Previdência

{
  "id": "ded7d2f1-6b90-44a8-9ace-de747b9f5bfe",
  "number": "123456-2",
  "name": "Pluggy PREVIDÊNCIA",
  "balance": 1359.39,
  "currencyCode": "BRL",
  "type": "SECURITY",
  "subtype": "RETIREMENT",
  "annualRate": 3.24,
  "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
  "code": null,
  "value": 500,
  "quantity": 3,
  "amount": 1500,
  "taxes": 0,
  "taxes2": 0,
  "date": "2020-07-19T18:27:41.802Z",
  "owner": "John Doe",
  "amountProfit": 359.39,
  "amountWithdrawal": 1310.5,
  "status": "ACTIVE",
  "metadata": {
    "taxRegime": "Progressivo",
    "proposalNumber": "000091322061",
    "processNumber": "15414900845201686",
    "insurer": {
      "cnpj": "51.990.695/0001-37",
      "name": "BRADESCO VIDA E PREVIDÊNCIA S.A."
    }
  },
  "institution": {
    "name": "BANCO BTG PACTUAL S/A",
    "number": "30306294000145"
  }
}

Fundo Mútuo

{
  "id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
  "number": null,
  "name": "Bahia AM Advisory FIC de FIM",
  "balance": 1359.39,
  "currencyCode": "BRL",
  "type": "MUTUAL_FUND",
  "subtype": "INVESTMENT_FUND",
  "lastMonthRate": 0.24,
  "annualRate": 3.24,
  "lastTwelveMonthsRate": 3,
  "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
  "code": "12.345.678/0001-00",
  "value": 500,
  "quantity": 3,
  "amount": 1500,
  "taxes": 40.61,
  "taxes2": 100,
  "date": "2020-07-19T18:27:41.802Z",
  "owner": "John Doe",
  "amountProfit": null,
  "amountWithdrawal": 1310.5,
  "amountOriginal": 1000,
  "status": "ACTIVE",
  "transactions": [
    {
      "tradeDate": "2020-10-01T00:00:00.000Z",
      "date": "2020-10-01T00:00:00.000Z",
      "description": "Aplicação Fundo de Investimento Premium",
      "quantity": 1.25,
      "value": 2,
      "amount": 5,
      "type": "BUY"
    }
  ]
}

CDB

{
  "id": "2a96b873-53bb-4d16-a3d8-385a57e78d7e",
  "number": null,
  "name": "CDB1194KL0Z - BANCO MAXIMA S/A",
  "balance": 2000,
  "currencyCode": "BRL",
  "type": "FIXED_INCOME",
  "subtype": "CDB",
  "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
  "code": "0001-02",
  "amount": 2500,
  "taxes": null,
  "taxes2": null,
  "date": "2020-07-19T18:27:41.802Z",
  "owner": "John Doe",
  "rate": 30,
  "rateType": "CDI",
  "fixedAnnualRate": 10.5,
  "amountProfit": null,
  "amountWithdrawal": 2000,
  "amountOriginal": 1000,
  "dueDate": "2030-07-19T18:27:41.802Z",
  "issuer": "Pluggy",
  "issueDate": "2020-07-19T18:27:41.802Z",
  "status": "ACTIVE"
}

Fundo Imobiliário

{
  "id": "5d80be62-d3a3-44e5-aaf7-85d33c7e9a7a",
  "number": null,
  "name": "GGRC11",
  "balance": 118.4,
  "currencyCode": "BRL",
  "type": "EQUITY",
  "subtype": "REAL_ESTATE_FUND",
  "lastMonthRate": null,
  "lastTwelveMonthsRate": null,
  "annualRate": null,
  "itemId": "80c05d1e-0ef7-4939-976d-f1509efd663a",
  "code": "GGRC11",
  "isin": "BRGGRCCTF002",
  "metadata": null,
  "value": 118.4,
  "quantity": 1,
  "amount": 118.4,
  "taxes": null,
  "taxes2": null,
  "date": "2022-06-20T14:43:58.799Z",
  "owner": null,
  "amountProfit": null,
  "amountWithdrawal": 118.4,
  "amountOriginal": 119,
  "transactions": [
    {
      "id": "76689151-2aff-4f32-8308-d9ecffb42254",
      "amount": 134.99,
      "description": null,
      "value": 134.99,
      "quantity": 1,
      "tradeDate": "2021-08-15T00:00:00.000Z",
      "date": "2021-08-15T00:00:00.000Z",
      "type": "BUY",
      "netAmount": null,
      "brokerageNumber": "123456-1",
      "expenses": {
        "serviceTax": 0.1,
        "brokerageFee": 0.04,
        "incomeTax": 0.08,
        "other": 0.04,
        "tradingAssetsNoticeFee": 0.11,
        "maintenanceFee": 0.12,
        "settlementFee": 0.02,
        "clearingFee": 0.1,
        "stockExchangeFee": 0.1,
        "custodyFee": 0.05,
        "operatingFee": 0.03
      }
    }
  ],
  "dueDate": null,
  "issuer": "GGR COVEPI RENDA FDO INV IMOB",
  "issueDate": null,
  "rate": null,
  "rateType": null,
  "fixedAnnualRate": null,
  "status": "ACTIVE",
  "institution": null
}

ETF

{
  "id": "5af0bd99-b74f-440a-bab3-6ed9155283ee",
  "number": null,
  "name": "ISUS11 STOCK",
  "balance": 2000,
  "currencyCode": "BRL",
  "type": "ETF",
  "subtype": "ETF",
  "lastMonthRate": 0.2,
  "lastTwelveMonthsRate": null,
  "annualRate": null,
  "itemId": "80c05d1e-0ef7-4939-976d-f1509efd663b",
  "code": "ISUS11",
  "isin": "BRISUSCTF003",
  "metadata": null,
  "value": null,
  "quantity": 1,
  "amount": 2000,
  "taxes": null,
  "taxes2": null,
  "date": "2022-06-20T14:43:58.799Z",
  "owner": "John Doe",
  "amountProfit": 0,
  "amountWithdrawal": 2000,
  "amountOriginal": 2000,
  "transactions": [
    {
      "id": "7a102141-b04a-490e-83db-42f09d39c421",
      "amount": 1499.99,
      "description": null,
      "value": 1499.99,
      "quantity": 1,
      "tradeDate": "2021-08-15T00:00:00.000Z",
      "date": "2021-08-15T00:00:00.000Z",
      "type": "BUY",
      "netAmount": null,
      "brokerageNumber": null,
      "expenses": {}
    }
  ],
  "dueDate": null,
  "issuer": "IT NOW ISE FUNDO DE ÍNDICE",
  "issueDate": null,
  "rate": null,
  "rateType": null,
  "fixedAnnualRate": null,
  "status": "ACTIVE",
  "institution": null
}

COE

{
  "id": "be7d7a0d-b411-4b88-b0a8-ede1a05aedbb",
  "number": null,
  "name": "SP 500 Ganho Garanti",
  "balance": 5021.2,
  "currencyCode": "BRL",
  "type": "COE",
  "subtype": "STRUCTURED_NOTE",
  "lastMonthRate": null,
  "lastTwelveMonthsRate": null,
  "annualRate": null,
  "itemId": "ed10736c-5330-4242-8a85-204397edb0cc",
  "code": null,
  "isin": null,
  "metadata": null,
  "value": 5027.35,
  "quantity": 1,
  "amount": 5027.35,
  "taxes": null,
  "taxes2": null,
  "date": null,
  "owner": "John Doe",
  "amountProfit": null,
  "amountWithdrawal": null,
  "amountOriginal": 5000,
  "transactions": [
    {
      "id": "b266fcda-b5ee-4181-80b5-273ecb4ff721",
      "amount": 5000,
      "description": null,
      "value": 5000,
      "quantity": 1,
      "tradeDate": "2022-01-21T00:00:00.000Z",
      "date": "2022-01-21T00:00:00.000Z",
      "type": "BUY",
      "netAmount": null,
      "brokerageNumber": null,
      "expenses": {}
    }
  ],
  "dueDate": "2027-01-27T00:00:00.000Z",
  "issuer": null,
  "issueDate": "2022-01-21T00:00:00.000Z",
  "rate": null,
  "rateType": null,
  "fixedAnnualRate": null,
  "status": "ACTIVE",
  "institution": null
}

Veja InvestimentoAPI em nossa referência da API para mais informações.

Investimentos em conectores de Open Finance#

Status do Investimento#

Instituição do Investimento#

Tipos & Subtipos de Investimento#

Metadados do Investimento#

Tipos de Taxas para Ativos de Renda Fixa#

Exemplos de respostas#