# Conta

O produto **conta** é a lista de contas bancárias, como Conta Corrente ou Conta Poupança e Cartão de Crédito, que estavam disponíveis no conector selecionado.

A resposta variará dependendo do Tipo de Contas, fornecendo um objeto `data` relacionado ao seu tipo `bankData` ou `creditData`.

```json title="Bank"
{
  "id": "a658c848-e475-457b-8565-d1fffba127c4",
  "type": "BANK",
  "subtype": "CHECKING_ACCOUNT",
  "number": "0001/12345-0",
  "name": "Conta Corrente",
  "marketingName": "GOLD Conta Corrente",
  "balance": 120950,
  "itemId": "a0922d6f-2007-4169-a181-b961500608db",
  "taxNumber": "333.333.333-33",
  "owner": "John Doe",
  "currencyCode": "BRL",
  "bankData": {
    "transferNumber": "123/0001/12345-0",
    "closingBalance": 120950,
    "automaticallyInvestedBalance": 100,
    "overdraftContractedLimit": 0,
    "overdraftUsedLimit": 0,
    "unarrangedOverdraftAmount": 0
  }
}
```

```json title="Credit"
{
  "id": "4f61bd6d-e6fc-44b2-9c4b-5609058de7ab",
  "type": "CREDIT",
  "subtype": "CREDIT_CARD",
  "name": "Itau Uniclass 2.0 Mastercard Platinum",
  "marketingName": "Itau Uniclass 2.0 Mastercard Platinum",
  "taxNumber": "***.***.123-22",
  "owner": "FEDERICO MIRAS",
  "number": "1234",
  "balance": 142.41,
  "itemId": "fc214524-4725-4974-9f7a-0f1b50ea39e0",
  "currencyCode": "BRL",
  "creditData": {
    "level": "PLATINUM",
    "brand": "MASTERCARD",
    "brandAdditionalInfo": null,
    "balanceCloseDate": "2020-07-08",
    "balanceDueDate": "2020-07-17",
    "availableCreditLimit": 51300,
    "creditLimit": 51800,
    "isLimitFlexible": false,
    "balanceForeignCurrency": 500,
    "minimumPayment": 100,
    "status": "ACTIVE",
    "holderType": "MAIN"
  }
}
```

| Propriedade | Descrição | Obrigatório |
|-------------|-----------|-------------|
| id | Identificador único do modelo de Conta, usado para recuperar transações relacionadas | Sim |
| type | Tipo de conta (BANK / CREDIT). | Sim |
| subtype | O subtipo de conta (`CHECKING_ACCOUNT` / `SAVINGS_ACCOUNT` / `CREDIT_CARD`). | Sim |
| number | Para tipo **BANK**, este campo retorna o número da conta. Ex: 12345-6 (ou 12345-6/500 em algumas contas poupança). Para tipo **CREDIT**, este campo retorna os últimos quatro dígitos do cartão de crédito. Ex: 1234. Para conectores com tipo **PAYMENT_ACCOUNT**, o número representa o número da conta de destino do fundo. | Sim |
| balance | Para tipo **BANK**, este campo retorna o saldo disponível atual da conta. Para tipo **CREDIT**, este campo retorna o valor do saldo atual da fatura em aberto ainda não paga. Para conectores com tipo **PAYMENT_ACCOUNT**, o saldo só pode ser retornado em contas digitais, não em contas externas. Mais detalhes [aqui](#balance). | Sim |
| currencyCode | Código ISO da moeda da conta, ex: USD ou EUR | Sim |
| name | Nome da conta, ex: Conta Poupança 1234 ou Mastercard Gold. | Sim |
| marketingName | O nome extra fornecido para algumas contas que estão relacionadas ao nível da conta. Nem sempre fornecido. | |
| owner | Nome do proprietário da conta. | |
| taxNumber | Número de identificação fiscal formatado do proprietário da conta (CPF ou CNPJ). Para conectores com tipo **PAYMENT_ACCOUNT**, taxNumber representa o CNPJ da empresa conectada. A disponibilidade varia de acordo com o conector. Para alguns conectores de negócios (por exemplo, Bradesco PJ), contas sob o mesmo itemId podem retornar diferentes valores de `taxNumber`, uma vez que o valor vem da empresa selecionada ou diretamente da API da instituição. | |
| bankData | Dados específicos para tipos de contas bancárias. | |
| creditData | Dados específicos para tipos de contas de crédito. | |

### Saldo

Os saldos das Contas Bancárias (Corrente e Poupança) representam o montante que o titular atualmente possui disponível para gastar. Se esse valor for negativo, representa uma dívida que o titular tem com a instituição financeira, um exemplo disso seria um cheque especial.

Os saldos dos Cartões de Crédito são o montante devido à instituição, isso significaria o saldo em aberto do mês atual do usuário. Se a fatura anterior foi paga com um valor excedente, o saldo retornaria um valor negativo.

Para conectores de Open Finance, o saldo do Cartão de Crédito é o limite utilizado para aquele cartão de crédito.

<Callout variant="info" title="Calculando saldos de cartões de crédito">
Contas do tipo crédito podem aproveitar o `availableCreditLimit` para consolidar uma visão 360 dos cartões de crédito.

`creditLimit` = `availableCreditLimit` (ainda a gastar) + `balance` (saldo em aberto) + dívida do saldo anterior.
</Callout>

### Saldos de contas bancárias em Open Finance

Para conectores de Open Finance, a instituição relata o montante disponível de uma conta bancária e, quando os possui, o montante bloqueado e o montante automaticamente investido. Nem toda instituição relata os dois últimos, então trate-os como opcionais. A Pluggy os mapeia assim:

| Campo | Valor |
|-------|-------|
| `balance` | O montante disponível. |
| `bankData.closingBalance` | `balance` + o montante bloqueado (o saldo contábil). `null` se a instituição não relatar um montante bloqueado. |
| `bankData.automaticallyInvestedBalance` | O montante automaticamente investido, inalterado. `null` se a instituição não o relatar. |

A soma em `closingBalance` é a mesma para cada conector de Open Finance. O que muda para algumas instituições é qual montante é usado como `balance`.

**Itaú, Banco do Brasil e Banrisul.** No Itaú PF (601), Itaú PJ (618), Banco do Brasil PF (611), Banco do Brasil PJ (662), Banrisul PF (659) e Banrisul PJ (660) (Banrisul desde novembro de 2026), quando o montante automaticamente investido é maior que zero, ele é usado como `balance` em vez do montante disponível, e `closingBalance` é calculado a partir disso. Essas instituições relatam o dinheiro mantido no investimento automático (por exemplo, o investimento automático do Itaú ou o Rende Fácil do Banco do Brasil) separadamente do montante disponível: algumas enviam o mesmo valor em ambos, outras enviam zero como disponível e o montante total como automaticamente investido. Em ambos os casos, o titular da conta vê esse montante como seu saldo no aplicativo do banco, então é isso que `balance` retorna. `automaticallyInvestedBalance` ainda retorna o montante exatamente como relatado.

Em resumo: nesses seis conectores, `balance` já inclui o dinheiro automaticamente investido, então não adicione `automaticallyInvestedBalance` a ele. Esse dinheiro também não é retornado como uma posição separada em `/investments`.

**Cheque especial.** Se `balance` for zero e a conta tiver cheque especial em uso (`overdraftUsedLimit` maior que zero), `balance` é retornado como o negativo do cheque especial utilizado. Isso se aplica ao saldo coletado quando o item é sincronizado; o [endpoint de saldo em tempo real](/docs/products/real-time-balance) retorna os montantes da instituição sem esse ajuste.

<Callout variant="success" title="Qual campo usar">
Use `balance` para o montante que o titular pode gastar. Use `closingBalance` quando precisar do saldo contábil incluindo montantes bloqueados. Não adicione `automaticallyInvestedBalance` a `balance` no Itaú, Banco do Brasil ou Banrisul: quando for maior que zero, já é o `balance`.
</Callout>

## Dados bancários

| Propriedade | Descrição |
|-------------|-----------|
| transferNumber | Este campo retorna a informação mais importante da conta, no formato `<compe>/<agência>/<conta>`: o código COMPE da instituição, a agência e o número da conta. Ex.: `123/1234/12345-6` |
| closingBalance | Saldo contábil da conta. Para conectores de Open Finance, é sempre `balance` + o montante bloqueado relatado pela instituição, e é `null` quando a instituição não relata um montante bloqueado. Não é o saldo de fechamento do dia anterior. Veja [Saldos de contas bancárias em Open Finance](#bank-account-balances-on-open-finance). |
| automaticallyInvestedBalance | Montante que a instituição automaticamente investiu da conta (por exemplo, o investimento automático do Itaú ou o Rende Fácil do Banco do Brasil), retornado exatamente como a instituição o relata. |
| overdraftContractedLimit | Montante do limite de cheque especial contratado. |
| overdraftUsedLimit | Montante total utilizado do limite especial de cheque e do adiantamento ao depositante. |
| unarrangedOverdraftAmount | Valor da operação contratada de forma emergencial para cobrir saldo pendente em conta de depósito à vista e excesso sobre o limite de cheque especial acordado. |

### Contas de mais de uma instituição no mesmo item

Alguns conectores retornam contas mantidas em diferentes instituições do mesmo grupo financeiro em um único item. Por exemplo, um item XP pode retornar duas contas `BANK` / `CHECKING_ACCOUNT`, ambas nomeadas "XP": uma no Banco XP (COMPE 348) e uma na XP Investimentos CCTVM (COMPE 102). Elas são contas diferentes, então não trate uma como duplicata da outra.

Para diferenciá-las, leia o código COMPE no início de `bankData.transferNumber` (a parte antes da primeira `/`): `348/...` é a conta do Banco XP e `102/...` é a conta da XP Investimentos.

## Dados de Crédito

| Propriedade | Descrição |
|-------------|-----------|
| minimumPayment | Pagamento mínimo do saldo para o período atual. Geralmente retornado apenas enquanto há uma fatura em aberto. |
| balanceForeignCurrency | Saldo em moeda estrangeira para o período atual. |
| availableCreditLimit | O limite de crédito disponível para a conta ainda a gastar. |
| creditLimit | O limite de crédito para a conta. |
| isLimitFlexible | Se o cartão de crédito é ilimitado. |
| balanceDueDate | Data de Vencimento do saldo para a conta do cartão. (aaaa-mm-dd). Geralmente retornado apenas enquanto há uma fatura em aberto. |
| balanceCloseDate | Data de fechamento quando o saldo foi calculado. (aaaa-mm-dd). Não fornecido por conectores de Open Finance, onde é sempre `null`. |
| level | Nível do tipo de cartão (Black, Signature, etc). |
| brand | Marca do cartão (Mastercard, Visa, Elo, etc). |
| brandAdditionalInfo | Texto livre especificando a categoria da marca quando `brand` é `OTHER`. *Disponível apenas em conectores de Open Finance.* |
| status | Status do cartão (ACTIVE, BLOCKED, CANCELLED). Para *conectores regulamentados* retornamos apenas **ACTIVE**, significando que o status do cartão ainda está sendo recuperado da FI. |
| holderType | Tipo de titular do cartão (MAIN ou ADDITIONAL) |

Quais campos `creditData` podem ser `null` depende do conector, então trate `null` em cada campo que sua integração lê. Em particular:

- `balanceCloseDate` não é fornecido por conectores de Open Finance; é `null` lá.
- `balanceDueDate` e `minimumPayment` geralmente vêm apenas enquanto o cartão tem uma fatura em aberto.

## Limites de Crédito Desagregados

Alguns cartões de crédito podem ter múltiplas linhas de crédito ou diferentes modalidades de operação. O campo `disaggregatedCreditLimits` fornece informações detalhadas sobre cada linha de crédito para ajudá-lo a identificar corretamente o cartão principal e calcular saldos precisos.

### Quando Usar Limites Desagregados

Use este recurso quando você encontrar:

- Saldos de cartões de crédito incorretos
- Múltiplas linhas de crédito no mesmo cartão
- Diferentes modalidades de operação com limites separados

### Estrutura

`disaggregatedCreditLimits` vive dentro de `creditData` e é um array de objetos, um por linha de crédito:

```json
{
  "creditData": {
    "disaggregatedCreditLimits": [
      {
        "creditLineLimitType": "LIMITE_CREDITO_TOTAL",
        "consolidationType": "INDIVIDUAL",
        "identificationNumber": "1000",
        "isLimitFlexible": false,
        "usedAmount": 149.84,
        "usedAmountCurrencyCode": "BRL",
        "lineName": "CREDITO_A_VISTA",
        "limitAmount": 1000.0,
        "limitAmountCurrencyCode": "BRL",
        "customizedLimitAmount": 2000.0,
        "customizedLimitAmountCurrencyCode": "BRL",
        "availableAmount": 850.16,
        "availableAmountCurrencyCode": "BRL"
      }
    ]
  }
}
```

### Campos Chave

| Campo | Tipo | Descrição | Exemplo |
|-------|------|-----------|---------|
| `creditLineLimitType` | string | Tipo de limite de crédito | `"LIMITE_CREDITO_TOTAL"` ou `"LIMITE_CREDITO_MODALIDADE_OPERACAO"` |
| `consolidationType` | string | Indica se o limite é consolidado ou individual | `"INDIVIDUAL"` ou `"CONSOLIDATED"` |
| `identificationNumber` | string | Número de identificação adicional do cartão de crédito | `"1000"` |
| `isLimitFlexible` | boolean | Indica se o limite é flexível | `false` |
| `usedAmount` | number | Montante utilizado do cartão de crédito adicional | `149.84` |
| `usedAmountCurrencyCode` | string | Código da moeda do montante utilizado | `"BRL"` |
| `lineName` | string | Nome da linha de limite de crédito. Um dos `CREDITO_A_VISTA`, `CREDITO_PARCELADO`, `SAQUE_CREDITO_BRASIL`, `SAQUE_CREDITO_EXTERIOR`, `EMPRESTIMO_CARTAO_CONSIGNADO`, `OUTROS` | `"CREDITO_A_VISTA"` |
| `lineNameAdditionalInfo` | string | Texto livre descrevendo a linha quando `lineName` é `OUTROS` | `"SAQUE_CREDITO"` |
| `limitAmount` | number | Montante de limite adicional do cartão de crédito | `1000.00` |
| `limitAmountCurrencyCode` | string | Código da moeda do limite | `"BRL"` |
| `limitAmountReason` | string | Razão pela qual o montante total do limite relatado é zero | `"Limite zerado após análise"` |
| `customizedLimitAmount` | number | Montante total do limite personalizado pelo cliente através dos canais eletrônicos da instituição | `2000.00` |
| `customizedLimitAmountCurrencyCode` | string | Código da moeda do montante do limite personalizado | `"BRL"` |
| `availableAmount` | number | Montante disponível do cartão de crédito adicional | `850.16` |
| `availableAmountCurrencyCode` | string | Código da moeda do montante disponível | `"BRL"` |

Veja [Contas](/reference/account) em nossa referência da API para mais informações.