API Operações de Crédito - Financiamento

GET /baas/v1/open/dat/financings/contracts

Obtém a lista de contratos de financiamento mantidos pelo cliente na instituição transmissora e para os quais ele tenha fornecido consentimento.

Permission necessária: FINANCINGS_READ

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "contractId": "92792126019929279212650822221989319252576",
      "brandName": "Organização A",
      "companyCnpj": "21128159000166",
      "productType": "FINANCIAMENTOS",
      "productSubType": "AQUISICAO_BENS_VEICULOS_AUTOMOTORES",
      "ipocCode": "92792126019929279212650822221989319252576"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data[].contractId: Identificador único e imutável do contrato de operação de crédito do cliente na instituição transmissora.
• data[].brandName: Nome da marca reportada pelo participante no Open Finance. Preferencialmente o mesmo nome atribuído no diretório Customer Friendly Server Name.
• data[].companyCnpj: CNPJ completo da instituição responsável pelo cadastro (sem máscara).
• data[].productType: Tipo da modalidade de crédito contratada, conforme circular 4.015 e DOC 3040 do SCR. Enum: FINANCIAMENTOS, FINANCIAMENTOS_RURAIS, FINANCIAMENTOS_IMOBILIARIOS.
• data[].productSubType: Sub tipo da modalidade de crédito contratada. Enum: AQUISICAO_BENS_VEICULOS_AUTOMOTORES, AQUISICAO_BENS_OUTROS_BENS, MICROCREDITO, CUSTEIO, INVESTIMENTO, INDUSTRIALIZACAO, COMERCIALIZACAO, FINANCIAMENTO_HABITACIONAL_SFH, FINANCIAMENTO_HABITACIONAL_EXCETO_SFH.
• data[].ipocCode: Número padronizado do contrato — IPOC (Identificação Padronizada da Operação de Crédito), composto por: CNPJ da instituição (8 posições) + modalidade (4 posições) + tipo do cliente (1 posição) + código do cliente + código do contrato (1 a 40 posições).
• links.self: URI completa que gerou a resposta atual.
• links.first: URI da primeira página. Obrigatório quando não for a primeira página.
• links.prev: URI da página anterior. Obrigatório quando não for a primeira página.
• links.next: URI da próxima página. Obrigatório quando não for a última página.
• links.last: URI da última página. Obrigatório quando não for a última página.
• meta.totalRecords: Número total de registros no resultado.
• meta.totalPages: Número total de páginas no resultado.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/financings/contracts/{contractId}

Obtém os dados do contrato de financiamento identificado por contractId mantido pelo cliente na instituição transmissora.

Permission necessária: FINANCINGS_READ

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "contractNumber": "1324926521496",
    "ipocCode": "92792126019929279212650822221989319252576",
    "productName": "Crédito Pessoal Consignado",
    "productType": "FINANCIAMENTOS",
    "productSubType": "AQUISICAO_BENS_VEICULOS_AUTOMOTORES",
    "contractDate": "2018-01-05",
    "disbursementDates": ["2018-01-15"],
    "settlementDate": "2018-01-15",
    "contractAmount": "1000.0400",
    "currency": "BRL",
    "dueDate": "2028-01-15",
    "instalmentPeriodicity": "SEMANAL",
    "instalmentPeriodicityAdditionalInfo": "Informações adicionais sobre periodicidade",
    "firstInstalmentDueDate": "2018-02-15",
    "CET": "0.290000",
    "amortizationScheduled": "SAC",
    "amortizationScheduledAdditionalInfo": "Informações complementares relativa à amortização do tipo OUTROS",
    "hasInsuranceContracted": true,
    "interestRates": [
      {
        "taxType": "EFETIVA",
        "interestRateType": "SIMPLES",
        "taxPeriodicity": "AA",
        "calculation": "21/252",
        "referentialRateIndexerType": "PRE_FIXADO",
        "referentialRateIndexerSubType": "TJLP",
        "referentialRateIndexerAdditionalInfo": "Informações adicionais",
        "preFixedRate": "0.600000",
        "postFixedRate": "0.550000",
        "additionalInfo": "Informações adicionais"
      }
    ],
    "contractedFees": [
      {
        "feeName": "Excesso em Conta",
        "feeCode": "EXCESSO_CONTA",
        "feeChargeType": "UNICA",
        "feeCharge": "MINIMO",
        "feeAmount": "1000.0400",
        "feeRate": "0.200000"
      }
    ],
    "contractedFinanceCharges": [
      {
        "chargeType": "JUROS_REMUNERATORIOS_POR_ATRASO",
        "chargeAdditionalInfo": "Informações adicionais sobre encargos.",
        "chargeRate": "0.071200"
      }
    ]
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data.contractNumber: Número do contrato dado pela instituição contratante.
• data.ipocCode: Número padronizado do contrato — IPOC. Mesma estrutura descrita em GET /contracts.
• data.productName: Denominação/identificação do nome da modalidade da operação de crédito divulgado ao cliente.
• data.productType: Tipo da modalidade de crédito (ver enum completo em GET /contracts).
• data.productSubType: Sub tipo da modalidade de crédito (ver enum completo em GET /contracts).
• data.contractDate: Data de contratação da operação de crédito (YYYY-MM-DD), conforme RFC-3339.
• data.disbursementDates[]: Lista de datas de desembolso do valor contratado (YYYY-MM-DD). Em liberação retroativa (D0 com referência a D-1), a data contábil correta é D-1.
• data.settlementDate: Data de liquidação da operação (YYYY-MM-DD).
• data.contractAmount: Valor contratado da operação, sem incluir taxas, tarifas, encargos e seguros. Com 2 a 4 casas decimais. Enviar 0.00 quando não houver valor explícito no contrato.
• data.currency: Moeda do contrato no padrão ISO-4217 (ex: BRL).
• data.dueDate: Data do vencimento final da operação (YYYY-MM-DD), conforme RFC-3339.
• data.instalmentPeriodicity: Periodicidade regular das parcelas. Enum: SEM_PERIODICIDADE_REGULAR, SEMANAL, QUINZENAL, MENSAL, BIMESTRAL, TRIMESTRAL, SEMESTRAL, ANUAL, OUTROS.
• data.instalmentPeriodicityAdditionalInfo: Complemento da periodicidade. Obrigatório quando instalmentPeriodicity for OUTROS.
• data.firstInstalmentDueDate: Data de vencimento da primeira parcela do principal (YYYY-MM-DD).
• data.CET: Custo Efetivo Total expresso como taxa percentual anual (6 casas decimais, ex: 0.290000 = 29%). Incorpora todos os encargos, tarifas, tributos e despesas. Obrigatório para PF em contratos a partir de 2008, para PJ a partir de 2011 e para crédito rural a partir de 2019. Quando indexado dinamicamente, recalcular com o último índice disponível e atualizar na próxima exposição após publicação do novo índice.
• data.amortizationScheduled: Sistema de amortização. Enum: SAC (amortização constante), PRICE (parcelas fixas / sistema francês), SAM (sistema misto), SEM_SISTEMA_AMORTIZACAO, OUTROS.
• data.amortizationScheduledAdditionalInfo: Complemento do sistema de amortização. Obrigatório quando amortizationScheduled for OUTROS.
• data.hasInsuranceContracted: Indica se existe seguro contratado para o financiamento (true/false). O não envio do campo significa que a instituição não oferece este produto.
• data.interestRates[]: Composição das taxas de juros remuneratórios. Lista vazia quando não há taxas. Objeto com valor 0 quando a taxa existe porém é zero.
• data.interestRates[].taxType: Tipo de taxa. Enum: NOMINAL (unidade referencial não coincide com a capitalização), EFETIVA (unidade referencial coincide com a capitalização).
• data.interestRates[].interestRateType: Tipo de juros. Enum: SIMPLES (calculado sempre sobre o capital inicial), COMPOSTO (cada período recalcula sobre capital + juros anteriores).
• data.interestRates[].taxPeriodicity: Periodicidade da taxa. Enum: AM (ao mês), AA (ao ano).
• data.interestRates[].calculation: Base de cálculo. Enum: 21/252, 30/360, 30/365.
• data.interestRates[].referentialRateIndexerType: Tipo de taxa referencial ou indexador. Enum: SEM_TIPO_INDEXADOR, PRE_FIXADO, POS_FIXADO, FLUTUANTES, INDICES_PRECOS, CREDITO_RURAL, OUTROS_INDEXADORES.
• data.interestRates[].referentialRateIndexerSubType: Sub tipo do indexador. Enum: SEM_SUB_TIPO_INDEXADOR, PRE_FIXADO, TR_TBF, TJLP, LIBOR, TLP, OUTRAS_TAXAS_POS_FIXADAS, CDI, SELIC, OUTRAS_TAXAS_FLUTUANTES, IGPM, IPCA, IPCC, OUTROS_INDICES_PRECO, TCR_PRE, TCR_POS, TRFC_PRE, TRFC_POS, OUTROS_INDEXADORES.
• data.interestRates[].referentialRateIndexerAdditionalInfo: Campo livre para complementar o indexador. Obrigatório quando tipo ou subtipo for OUTRO.
• data.interestRates[].preFixedRate: Taxa pré-fixada aplicada ao contrato (6 casas decimais, ex: 0.600000 = 60%).
• data.interestRates[].postFixedRate: Taxa pós-fixada aplicada ao contrato (6 casas decimais, ex: 0.550000 = 55%).
• data.interestRates[].additionalInfo: Texto livre com informações adicionais sobre a composição das taxas. Obrigatório quando a instituição possuir a informação.
• data.contractedFees[]: Lista de tarifas pactuadas no contrato.
• data.contractedFees[].feeName: Denominação da tarifa pactuada.
• data.contractedFees[].feeCode: Sigla identificadora da tarifa pactuada.
• data.contractedFees[].feeChargeType: Tipo de cobrança da tarifa. Enum: UNICA, POR_PARCELA.
• data.contractedFees[].feeCharge: Forma de cobrança da tarifa. Enum: MINIMO, MAXIMO, FIXO, PERCENTUAL.
• data.contractedFees[].feeAmount: Valor monetário da tarifa. Obrigatório quando feeCharge for diferente de PERCENTUAL. Com 2 a 4 casas decimais.
• data.contractedFees[].feeRate: Valor da tarifa em percentual (6 casas decimais, ex: 0.200000 = 20%). Obrigatório quando feeCharge for PERCENTUAL.
• data.contractedFinanceCharges[]: Lista de encargos pactuados no contrato.
• data.contractedFinanceCharges[].chargeType: Tipo do encargo. Enum: JUROS_REMUNERATORIOS_POR_ATRASO, MULTA_ATRASO_PAGAMENTO, JUROS_MORA_ATRASO, IOF_CONTRATACAO, IOF_POR_ATRASO, SEM_ENCARGO, OUTROS.
• data.contractedFinanceCharges[].chargeAdditionalInfo: Campo livre. Obrigatório quando chargeType for OUTROS.
• data.contractedFinanceCharges[].chargeRate: Percentual do encargo pactuado (6 casas decimais, ex: 0.071200 = 7,12%).
• links.self: URI completa que gerou a resposta atual.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/financings/contracts/{contractId}/warranties

Obtém a lista de garantias vinculadas ao contrato de financiamento identificado por contractId. Para contratos sem garantias, retorna HTTP 200 com objeto data vazio.

Permission necessária: FINANCINGS_WARRANTIES_READ

Parâmetros de path

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "currency": "BRL",
      "warrantyType": "CESSAO_DIREITOS_CREDITORIOS",
      "warrantySubType": "NOTAS_PROMISSORIAS_OUTROS_DIREITOS_CREDITO",
      "warrantyAmount": "1000.0400"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data[].currency: Moeda referente ao valor da garantia no padrão ISO-4217 (ex: BRL).
• data[].warrantyType: Tipo da garantia que avaliza a operação de crédito (Doc 3040, Anexo 12). Enum: CESSAO_DIREITOS_CREDITORIOS, CAUCAO, PENHOR, ALIENACAO_FIDUCIARIA, HIPOTECA, OPERACOES_GARANTIDAS_PELO_GOVERNO, OUTRAS_GARANTIAS_NAO_FIDEJUSSORIAS, SEGUROS_ASSEMELHADOS, GARANTIA_FIDEJUSSORIA, BENS_ARRENDADOS, GARANTIAS_INTERNACIONAIS, OPERACOES_GARANTIDAS_OUTRAS_ENTIDADES, ACORDOS_COMPENSACAO.
• data[].warrantySubType: Sub tipo da garantia (Doc 3040, Anexo 12). Enum com mais de 50 valores, incluindo: IMOVEIS, IMOVEIS_RESIDENCIAIS, VEICULOS, VEICULOS_AUTOMOTORES, EQUIPAMENTOS, FGTS_FUNDO_GARANTIA_TEMPO_SERVICO, PESSOA_FISICA, PESSOA_JURIDICA, DUPLICATAS, CHEQUES, DEPOSITOS_A_VISTA_A_PRAZO_POUPANCA_OURO_TITULOS_PUBLICOS_FEDERAIS_ART_36, ALIENACAO_FIDUCIARIA, OUTROS, entre outros.
• data[].warrantyAmount: Valor original da garantia, com 2 a 4 casas decimais. Para GARANTIA_FIDEJUSSORIA em que não é possível determinar valor monetário, preencher com 0.00.
• links: Links de navegação entre páginas (ver descrição em GET /contracts).
• meta.totalRecords: Número total de registros no resultado.
• meta.totalPages: Número total de páginas no resultado.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/financings/contracts/{contractId}/scheduled-instalments

Obtém os dados do cronograma de parcelas do contrato de financiamento identificado por contractId.

Permission necessária: FINANCINGS_SCHEDULED_INSTALMENTS_READ

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "typeNumberOfInstalments": "MES",
    "totalNumberOfInstalments": 130632,
    "typeContractRemaining": "MES",
    "contractRemainingNumber": 14600,
    "paidInstalments": 73,
    "dueInstalments": 57,
    "pastDueInstalments": 73,
    "balloonPayments": [
      {
        "dueDate": "2020-01-10",
        "amount": {
          "amount": "1000.0400",
          "currency": "BRL"
        }
      }
    ]
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data.typeNumberOfInstalments: Tipo do prazo total do contrato. Enum: DIA, SEMANA, MES, ANO, SEM_PRAZO_TOTAL.
• data.totalNumberOfInstalments: Prazo total conforme o tipo definido. Obrigatório quando typeNumberOfInstalments for diferente de SEM_PRAZO_TOTAL.
• data.typeContractRemaining: Tipo do prazo remanescente do contrato. Enum: DIA, SEMANA, MES, ANO, SEM_PRAZO_REMANESCENTE.
• data.contractRemainingNumber: Prazo remanescente conforme o tipo definido. Obrigatório quando typeContractRemaining for diferente de SEM_PRAZO_REMANESCENTE.
• data.paidInstalments: Quantidade de prestações pagas. Para modalidades sem parcelas, o valor é zero.
• data.dueInstalments: Quantidade de prestações a vencer. Obrigatório para modalidades que possuam parcelas.
• data.pastDueInstalments: Quantidade de prestações vencidas (em atraso). Obrigatório para modalidades que possuam parcelas.
• data.balloonPayments[]: Lista de parcelas não regulares (balloon payments) do contrato com suas datas de vencimento e valores.
• data.balloonPayments[].dueDate: Data de vencimento da parcela não regular (YYYY-MM-DD).
• data.balloonPayments[].amount.amount: Valor monetário da parcela não regular a vencer. Com 2 a 4 casas decimais.
• data.balloonPayments[].amount.currency: Moeda no padrão ISO-4217.
• links.self: URI completa que gerou a resposta atual.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/financings/contracts/{contractId}/payments

Obtém os dados de pagamentos do contrato de financiamento identificado por contractId.

Permission necessária: FINANCINGS_PAYMENTS_READ

Observação: A paginação neste endpoint ocorre sobre os registros do campo releases.

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "paidInstalments": 73,
    "contractOutstandingBalance": "1000.0400",
    "releases": [
      {
        "paymentId": "XlthLXpBLVowLTldW2EtekEtWjAtOVwtXXswLDk5fSQ",
        "isOverParcelPayment": true,
        "instalmentId": "WGx0aExYcEJMVm93TFRsZFcyRXRla0V0V2pBdE9Wd3RYWH",
        "paidDate": "2021-05-21",
        "currency": "BRL",
        "paidAmount": "1000.0400",
        "overParcel": {
          "fees": [
            {
              "feeName": "Reavaliação periódica do bem",
              "feeCode": "aval_bem",
              "feeAmount": "1000.0400"
            }
          ],
          "charges": [
            {
              "chargeType": "JUROS_REMUNERATORIOS_POR_ATRASO",
              "chargeAdditionalInfo": "Informações adicionais",
              "chargeAmount": "1000.0400"
            }
          ]
        }
      }
    ]
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data.paidInstalments: Quantidade total de parcelas pagas do contrato. Obrigatório para modalidades que possuam parcelas.
• data.contractOutstandingBalance: Valor necessário para o cliente liquidar a dívida (saldo devedor atualizado conforme DDC — Documento Descritivo de Crédito). Com 2 a 4 casas decimais.
• data.releases[]: Lista dos pagamentos realizados no período. A paginação deste endpoint ocorre sobre este campo.
• data.releases[].paymentId: Código ou identificador único do pagamento individual prestado pela instituição.
• data.releases[].isOverParcelPayment: Identifica se o pagamento é avulso (true) ou pactuado/regular (false).
• data.releases[].instalmentId: Identificador da parcela de responsabilidade de cada instituição transmissora. Obrigatório quando isOverParcelPayment for false.
• data.releases[].paidDate: Data efetiva do pagamento (YYYY-MM-DD).
• data.releases[].currency: Moeda do pagamento no padrão ISO-4217 (ex: BRL).
• data.releases[].paidAmount: Valor do pagamento referente ao contrato. Com 2 a 4 casas decimais.
• data.releases[].overParcel: Objeto de tarifas e encargos pagos fora da parcela. Enviar caso exista.
• data.releases[].overParcel.fees[]: Lista das tarifas pagas fora da parcela (somente para pagamento avulso).
• data.releases[].overParcel.fees[].feeName: Denominação da tarifa paga.
• data.releases[].overParcel.fees[].feeCode: Sigla identificadora da tarifa paga.
• data.releases[].overParcel.fees[].feeAmount: Valor monetário da tarifa paga. Com 2 a 4 casas decimais.
• data.releases[].overParcel.charges[]: Lista dos encargos pagos fora da parcela.
• data.releases[].overParcel.charges[].chargeType: Tipo do encargo. Enum: JUROS_REMUNERATORIOS_POR_ATRASO, MULTA_ATRASO_PAGAMENTO, JUROS_MORA_ATRASO, IOF_CONTRATACAO, IOF_POR_ATRASO, SEM_ENCARGO, OUTROS.
• data.releases[].overParcel.charges[].chargeAdditionalInfo: Campo livre. Obrigatório quando chargeType for OUTROS.
• data.releases[].overParcel.charges[].chargeAmount: Valor do encargo pago fora da parcela. Com 2 a 4 casas decimais.
• links.self: URI completa que gerou a resposta atual.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.