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 atual do saldo líquido 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	Data de emissão do ativo. Para `FIXED_INCOME` e `COE`, corresponde à data em que a posição foi aberta. Para ações e outros ativos de `EQUITY`, fundos (`MUTUAL_FUND`) e `ETF`, é a data em que o ativo foi criado, não a data em que o usuário o comprou. Não há campo com a data de aquisição do usuário.
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 Investimento paginadasAPI em vez disso.
metadata	InvestmentMetadata \| null	Sim	O objeto de metadados contém "Dados de Valores Mobiliários" 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 reporta 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 reporta. 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 do CNPJ da instituição / Outro.

Tipos e 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
FIXED_INCOME	CRI	Certificado de Recebíveis Imobiliários
FIXED_INCOME	CRA	Certificado de Recebíveis do Agronegócio
FIXED_INCOME	LCI	Letra de Crédito Imobiliário
FIXED_INCOME	LCA	Letra de Crédito do Agronegócio
FIXED_INCOME	LC	Letra de Câmbio
FIXED_INCOME	TREASURY	Tesouro Nacional
FIXED_INCOME	DEBENTURES	Dívida Corporativa
FIXED_INCOME	CDB	Certificado de Depósito Bancário
FIXED_INCOME	LIG	Letra Imobiliária Garantida
FIXED_INCOME	LF	Letra Financeira
SECURITY	RETIREMENT	Previdência Privada
SECURITY	PGBL	Previdência Privada
SECURITY	VGBL	Previdência Privada
MUTUAL_FUND	INVESTMENT_FUND	Fundo de Investimento
MUTUAL_FUND	STOCK_FUND	Fundo de Ações
MUTUAL_FUND	MULTIMARKET_FUND	Fundo Multimercado
MUTUAL_FUND	EXCHANGE_FUND	Fundo Cambial
MUTUAL_FUND	FIXED_INCOME_FUND	Fundo de Renda Fixa
MUTUAL_FUND	FIP_FUND	Fundo de Investimento em Participações
MUTUAL_FUND	OFFSHORE_FUND	Fundo Offshore
MUTUAL_FUND	ETF_FUND	Fundo ETF
EQUITY	STOCK	Ações, Papéis
EQUITY	BDR	Brazilian Depositary Receipt
EQUITY	REAL_ESTATE_FUND	Fundos Imobiliários
EQUITY	DERIVATIVES	Derivativos
EQUITY	OPTION	Opção
ETF	ETF	Fundos Negociados em Bolsa
COE	STRUCTURED_NOTE	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 Valores Mobiliários, 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 Valores Mobiliários (pode ser diferente da propriedade `name` do investimento).
insurer	Company	Sim	A empresa seguradora do Fundo de Valores Mobiliários, quando o número do processo é identificado, a seguradora sempre será retornada.

Produto de Portabilidade de Previdência

Esse 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. Por favor, 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 é FIXED_INCOME, recuperamos 3 campos associados ao retorno esperado do investimento. Esses são rate, rateType e fixedAnnualRate. Abaixo estão alguns exemplos de como os tipos de taxa 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 #

Previdencia

{
  "id": "ded7d2f1-6b90-44a8-9ace-de747b9f5bfe",
  "number": "123456-2",
  "name": "Pluggy PREVIDENCIA",
  "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"
  }
}

Mutual Fund

{
  "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"
}

Real Estate Fund

{
  "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 e Subtipos de Investimento#

Metadados do Investimento#

Tipos de Taxas para Ativos de Renda Fixa#

Exemplos de respostas#