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.
{
"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
}
}{
"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. | 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.
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.
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 retorna os montantes da instituição sem esse ajuste.
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.
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. |
| 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:
balanceCloseDatenão é fornecido por conectores de Open Finance; énulllá.balanceDueDateeminimumPaymentgeralmente 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:
{
"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 ContasAPI em nossa referência da API para mais informações.
