API Operações de Crédito - Empréstimos

GET /baas/v1/open/dat/loans/contracts

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

Permission necessária: LOANS_READ

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "contractId": "92792126019929279212650822221989319252576",
      "brandName": "Organização A",
      "companyCnpj": "21128159000166",
      "productType": "EMPRESTIMOS",
      "productSubType": "CREDITO_PESSOAL_COM_CONSIGNACAO",
      "productSubTypeCategory": "CREDITO_PESSOAL_CLEAN",
      "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 contrato de empréstimo (sem máscara). Utilizado para identificar a instituição credora nos casos de portabilidade de crédito.
• data[].productType: Tipo da modalidade de crédito contratada. Enum: EMPRESTIMOS.
• data[].productSubType: Sub tipo da modalidade de crédito empréstimos, conforme circular 4.015 e DOC 3040 do SCR. Enum: HOME_EQUITY, CHEQUE_ESPECIAL, CONTA_GARANTIDA, CAPITAL_GIRO_TETO_ROTATIVO, CREDITO_PESSOAL_SEM_CONSIGNACAO, CREDITO_PESSOAL_COM_CONSIGNACAO, MICROCREDITO_PRODUTIVO_ORIENTADO, CAPITAL_GIRO_PRAZO_VENCIMENTO_ATE_365_DIAS, CAPITAL_GIRO_PRAZO_VENCIMENTO_SUPERIOR_365_DIAS.
• data[].productSubTypeCategory: Categoria de classificação específica relacionada à submodalidade do produto. Enum: CREDITO_PESSOAL_CLEAN (obrigatório para contratos em aberto quando aplicável, a partir da v2.5.0), CONSIGNADO_SIAPE (obrigatório para contratos consignados sob regulamentação Siape a partir do piloto), OUTRO (demais submodalidades ou contratos liquidados antes do go live da v2.5.0).
• 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.
• 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/loans/contracts/{contractId}

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

Permission necessária: LOANS_READ

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "contractNumber": "1324926521496",
    "ipocCode": "92792126019929279212650822221989319252576",
    "productName": "Crédito Pessoal Consignado",
    "productType": "EMPRESTIMOS",
    "productSubType": "CREDITO_PESSOAL_COM_CONSIGNACAO",
    "productSubTypeCategory": "CREDITO_PESSOAL_CLEAN",
    "contractDate": "2018-01-05",
    "disbursementDates": ["2018-01-15"],
    "settlementDate": "2018-01-15",
    "contractAmount": "1000.0400",
    "currency": "BRL",
    "dueDate": "2028-01-15",
    "instalmentPeriodicity": "MENSAL",
    "instalmentPeriodicityAdditionalInfo": "Informações adicionais sobre periodicidade",
    "firstInstalmentDueDate": "2018-02-15",
    "CET": "0.290000",
    "hasInsuranceContracted": true,
    "amortizationScheduled": "SAC",
    "amortizationScheduledAdditionalInfo": "Informações complementares relativa à amortização do tipo OUTROS",
    "cnpjConsignor": "60500998000135",
    "nextInstalmentAmount": "1000.0400",
    "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": "Renovação de cadastro",
        "feeCode": "CADASTRO",
        "feeChargeType": "UNICA",
        "feeCharge": "FIXO",
        "feeAmount": "100000.0400",
        "feeRate": "0.062000"
      }
    ],
    "contractedFinanceCharges": [
      {
        "chargeType": "JUROS_REMUNERATORIOS_POR_ATRASO",
        "chargeAdditionalInfo": "Informações adicionais sobre encargos.",
        "chargeRate": "0.070000"
      }
    ]
  },
  "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. Enum: EMPRESTIMOS.
• data.productSubType: Sub tipo da modalidade de crédito (ver enum completo em GET /contracts).
• data.productSubTypeCategory: Categoria de classificação da submodalidade (ver enum e regras em GET /contracts).
• data.contractDate: Data de contratação da operação, no formato YYYY-MM-DD. Para produtos rotativos (CHEQUE_ESPECIAL, CONTA_GARANTIDA) com múltiplas contratações, enviar a última data disponível.
• data.disbursementDates[]: Lista de datas de desembolso do valor contratado (YYYY-MM-DD). A data contábil pode ser D-1 em caso de liberação retroativa.
• data.settlementDate: Data de liquidação da operação (YYYY-MM-DD). Para cancelamento sem saldo devedor, data do cancelamento. Para cancelamento com saldo devedor, data em que o saldo for liquidado.
• 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 último vencimento da operação (YYYY-MM-DD). Para produtos rotativos, representa a data fim da renovação (ativos) ou data de cancelamento (cancelados/vencidos).
• 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). Enviar caso exista.
• data.CET: Custo Efetivo Total expresso como taxa percentual anual (6 casas decimais, ex: 0.290000 = 29%). Incorpora todos os encargos, tarifas, tributos, seguros e despesas. Obrigatório para PF em contratos a partir de 2008 e para PJ a partir de 2011.
• data.hasInsuranceContracted: Indica se há seguro contratado para o empréstimo (true/false). Obrigatório quando productSubTypeCategory for CREDITO_PESSOAL_CLEAN ou CONSIGNADO_SIAPE.
• 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.cnpjConsignor: CNPJ do consignante (sem máscara). Obrigatório enquanto houver vínculo ativo para productSubType igual a CREDITO_PESSOAL_COM_CONSIGNACAO. Pode ser omitido em casos de desconsignação.
• data.nextInstalmentAmount: Valor de face da próxima parcela no vencimento (2 a 4 casas decimais). Para contratos liquidados, retornar zero. Obrigatório quando productSubTypeCategory for CREDITO_PESSOAL_CLEAN ou CONSIGNADO_SIAPE.
• 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. Para contratos em renegociação, manter a taxa do contrato vigente até a conclusão. Para CPC e Consignado Federal, obrigatório conter taxa nominal e efetiva a.a.
• 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. Obrigatório quando postFixedRate for informado. 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%). Obrigatório se postFixedRate não for enviado.
• data.interestRates[].postFixedRate: Taxa pós-fixada aplicada ao contrato (6 casas decimais). Obrigatório se preFixedRate não for enviado. Requer informação do indexador.
• data.interestRates[].additionalInfo: Texto livre com informações adicionais sobre a composição das taxas.
• 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). 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 no contrato (6 casas decimais, ex: 0.070000 = 7%).
• 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/loans/contracts/{contractId}/warranties

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

Permission necessária: LOANS_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, 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/loans/contracts/{contractId}/scheduled-instalments

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

Permission necessária: LOANS_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": "2021-05-21",
        "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. Deve corresponder à soma de paidInstalments + pastDueInstalments + dueInstalments. 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. Para modalidades sem parcelas, o valor é zero.
• data.pastDueInstalments: Quantidade de prestações vencidas (em atraso). Para modalidades sem parcelas, o valor é zero.
• 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/loans/contracts/{contractId}/payments

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

Permission necessária: LOANS_PAYMENTS_READ

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "paidInstalments": 73,
    "contractOutstandingBalance": "1000.0400",
    "lastUpdatedContractOutstandingBalance": "2021-05-21T08:30:03.374Z",
    "totalRemainingAmount": "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": "100000.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.
• 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. Para produtos no escopo de Portabilidade de Crédito via OFB, deve ser atualizado e disponibilizado até às 10h do mesmo dia.
• data.lastUpdatedContractOutstandingBalance: Data e hora da última atualização do contractOutstandingBalance, no formato RFC-3339 UTC com milissegundos. Obrigatório quando productSubTypeCategory for CREDITO_PESSOAL_CLEAN ou CONSIGNADO_SIAPE.
• data.totalRemainingAmount: Valor total restante para liquidar o contrato, incluindo o somatório de parcelas a vencer, vencidas, taxas, tarifas e encargos. Para taxas pós-fixadas, considerar apenas valores pré-fixados. Com 2 a 4 casas decimais. Obrigatório quando productSubTypeCategory for CREDITO_PESSOAL_CLEAN ou CONSIGNADO_SIAPE.
• data.releases[]: Lista dos pagamentos realizados no período.
• 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.
• data.releases[].paidAmount: Valor pago referente ao contrato. Se encargos e taxas foram pagos junto da parcela, a soma total é incluída aqui. Caso tenham sido pagos à parte, devem constar em overParcel. 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.