Investimento

A entidade Investment é 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 type 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 do 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. Este valor é retornado para fundos.
lastTwelveMonthsRate	number	Sim	A taxa de desempenho dos últimos 12 meses. Este valor é retornado para fundos.
annualRate	number	Sim	Taxa de desempenho do último ano. Este 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 `date`.
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	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 paginadas 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.
providerId	string	Sim	Identificador interno da instituição fornecedora para o investimento.
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.

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	Identificador numérico para o CNPJ da instituição / Outro.

Tipos e Subtipos de Investimento #

Para entender a natureza de um investimento, você pode contar com os campos type e subtype 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
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 FIP
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 Segurança, 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 de Segurança (pode ser diferente da propriedade `name` do investimento).
insurer	Company	Sim	A empresa seguradora do Fundo de Segurança, quando o número do processo é identificado, a seguradora sempre será retornada.

Produto de Portabilidade de Aposentadoria Este conjunto de dados faz parte do serviço de Portabilidade de Aposentadoria 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 é FIXED_INCOME, recuperamos 3 campos associados ao retorno esperado do investimento. Estes são rate, rateType e 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 #

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"
  },
  "institution": {
    "name": "BANCO BTG PACTUAL S/A",
    "number": "30306294000145",
    "insurer": {
      "cnpj": "51.990.695/0001-37",
      "name": "BRADESCO VIDA E PREVIDÊNCIA S.A."
    }
  }
}

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,
  "providerId": 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,
  "providerId": 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,
  "providerId": null
}

Veja Investment em nossa referência de API para mais informações.

Status do Investimento#

Instituição do Investimento#

Tipos e Subtipos de Investimento#

Metadados do Investimento#