# 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](#investments-types--subtypes) | Não | Tipo de investimento. |
| subtype | [InvestmentSubType](#investments-types--subtypes) | 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](#rate-types-for-fixed-income-assets) | 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](#investments-status) | Sim | Status atual do investimento. ATIVO, PENDENTE & RETIRADA_TOTAL |
| institution | [InvestmentInstitution](#investments-institution) | Sim | Corretora ou Instituição Financeira detentora do investimento. Isso é retornado apenas no Conector CEI B3. |
| *transactions* **(deprecated)** | [InvestmentsTransaction](/docs/products/investment-transactions) | 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](/reference/investment-transactions-list) em vez disso. |
| metadata | [InvestmentMetadata](#investments-metadata) \| 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. |

## 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 `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 de Índice 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 em 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 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](mailto: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 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

```json title="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"
  }
}
```

```json title="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"
    }
  ]
}
```

```json title="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"
}
```

```json title="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
}
```

```json title="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
}
```

```json title="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 [Investment](/reference/investment) em nossa referência de API para mais informações.