# Listar todos os snapshots de empréstimos

Liste e filtre os instantâneos do histórico de empréstimos associados à sua conta.

Endpoint: GET /loans
Version: 1.0.0
Security: ApiKeyAuth, ApiKeySecret

## Query parameters:

  - `page` (integer)
    Um número de página dentro do conjunto de resultados paginados.
    Example: 1

  - `limit` (integer)
    Indica quantos resultados retornar por página. Por padrão, retornamos 20 resultados por página.

ℹ️ O número mínimo de resultados retornados por página é 1 e o máximo é 100. Se você inserir um valor maior que 100, nossa API usará o valor máximo (100) por padrão.
    Example: 15

  - `payment_method_id` (string)
    Filtrar pelo ID do método de pagamento associado ao empréstimo.
    Example: "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b"

  - `merchant_customer_id` (string)
    Filtre pelo identificador de cliente atribuído pelo seu comerciante.
    Example: "CUST-001234"

  - `customer_id` (string)
    O identificador único criado pela Belvo usado para referenciar o cliente.
    Example: "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"

  - `default_date` (string)
    Filtrar por data padrão exata no formato YYYY-MM-DD.
    Example: "2026-04-15"

  - `status` (string)
    Filtrar por status do empréstimo. Pode ser active ou inactive.
    Enum: "active", "inactive"

  - `start_date` (string)
    Retorne empréstimos com um defaultDate maior ou igual à data especificada. A data deve estar no formato YYYY-MM-DD.
    Example: "2026-04-01"

  - `end_date` (string)
    Retorne empréstimos com um defaultDate menor ou igual à data especificada. A data deve estar no formato YYYY-MM-DD.
    Example: "2026-04-30"

  - `order` (string)
    Retorne os resultados em ordem ascendente (do mais antigo para o mais recente) ou descendente (do mais recente para o mais antigo), de acordo com o createdDate.

Pode ser:
  - asc para ordem ascendente
  - desc para ordem descendente
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `items` (array)
    Um array de objetos de instantâneo do histórico de empréstimos.

  - `items.id` (string, required)
    O identificador único criado pela Belvo usado para referenciar este instantâneo do histórico de empréstimos.

  - `items.loanId` (string)
    O identificador único criado pela Belvo usado para referenciar a entidade de empréstimo pai.

  - `items.customerId` (string, required)
    O identificador único criado pela Belvo usado para referenciar o cliente.

  - `items.paymentMethodId` (string)
    O identificador único criado pela Belvo usado para referenciar o método de pagamento associado a este empréstimo.

  - `items.merchantCustomerId` (string, required)
    Seu identificador de cliente atribuído pelo comerciante.

  - `items.status` (string, required)
    O status do empréstimo. Pode ser:
  - active
    O empréstimo está atualmente sendo monitorado para cobrança.
  - inactive
    O empréstimo não está mais ativo.
    Enum: same as `status` (2 values)

  - `items.principalAmount` (string, required)
    O valor principal.

  - `items.totalBalance` (string, required)
    O saldo total pendente.

  - `items.targetCollectionDate` (string, required)
    A data em que a Belvo tentará coletar o pagamento, no formato YYYY-MM-DD. Esta data é definida como o dia em que a solicitação foi inicialmente feita ou para o próximo dia útil.

  - `items.defaultDate` (string, required)
    A data em que o cliente inadimpliu o empréstimo, no formato YYYY-MM-DD.

  - `items.daysOverdue` (integer)
    O número de dias em que o empréstimo está em atraso.

  - `items.issueDate` (string)
    A data de emissão original, no formato YYYY-MM-DD.

  - `items.loanAmount` (string)
    O valor original do empréstimo.

  - `items.interestAmount` (string)
    O valor acumulado de juros.

  - `items.feesAmount` (string)
    As taxas associadas ao empréstimo.

  - `items.latePaymentInterestAmount` (string)
    Os juros acumulados devido a pagamentos atrasados.

  - `items.openingCommissionAmount` (string)
    A comissão de abertura cobrada pelo empréstimo.

  - `items.yearlyOrdinalInterestRate` (string)
    A taxa de juros anual, com até 4 casas decimais.

  - `items.customerSalary` (string)
    O salário do cliente.

  - `items.customerAddress` (string)
    O endereço do cliente.

  - `items.creditStatus` (string)
    O status de crédito do empréstimo. Pode ser:

  - past_due
    O pagamento está atrasado.
  - restructured
    O empréstimo foi reestruturado.
  - canceled
    O empréstimo foi cancelado.
  - in_arrears
    O empréstimo está em atraso.
    Enum: "past_due", "restructured", "canceled", "in_arrears"

  - `items.paidInstallments` (integer)
    O número de parcelas já pagas.

  - `items.paidAmount` (string)
    O valor total já pago.

  - `items.lastPaymentDate` (string)
    A data do último pagamento.

  - `items.lastPaymentAmount` (string)
    O valor do último pagamento.

  - `items.mainPhoneNumber` (string)
    O número de telefone principal do cliente.

  - `items.reference` (string)
    Sua referência para o empréstimo.

  - `items.createdDate` (string, required)
    O carimbo de data e hora ISO-8601 quando a captura do empréstimo foi criada no banco de dados da Belvo.

  - `items.lastUpdatedDate` (string, required)
    O carimbo de data e hora ISO-8601 quando a captura do empréstimo foi atualizada pela última vez no banco de dados da Belvo.

  - `meta` (object)
    Metadados adicionais sobre o conjunto de resultados paginados.

  - `meta.totalItems` (integer)
    O número total de itens no conjunto de resultados paginados.
    Example: 100

  - `meta.itemCount` (integer)
    O número de itens na página atual.
    Example: 10

  - `meta.itemsPerPage` (integer)
    O número de itens solicitados por página.
    Example: 10

  - `meta.totalPages` (integer)
    O número total de páginas no conjunto de resultados paginados.
    Example: 10

  - `meta.currentPage` (integer)
    O número da página atual.
    Example: 1

  - `links` (object)
    Links para navegar no conjunto de resultados paginados.

  - `links.first` (string)
    A URL para a primeira página do conjunto de resultados paginados.
    Example: "/{resource}?limit=20"

  - `links.last` (string)
    A URL para a última página do conjunto de resultados paginados.
    Example: "/{resource}?page=4&limit=20"

  - `links.next` (string)
    A URL para a próxima página do conjunto de resultados paginados.
    Example: "/{resource}?page=3&limit=20"

  - `links.previous` (string)
    A URL para a página anterior do conjunto de resultados paginados.
    Example: "/{resource}?page=2&limit=20"

## Response 400 fields (application/json):

  - `statusCode` (integer)
    O código de status HTTP para este erro.
    Example: 400

  - `error` (string)
    A descrição do código de status HTTP para este erro.
    Example: "Bad Request"

  - `message` (any)
    Uma breve descrição do erro, indicando o que está errado com a solicitação.
> Nota: Retornamos uma string ou um array de strings, dependendo do(s) erro(s) de validação.

A descrição pode ser (entre outras):

  - id must be a UUID
  - Not enough balance
  - amount is not a valid decimal number.
  - currency must be one of the following values: cop, mxn, usd
  - reference must be a string
  - Customer not found for merchant
  - documentType is a required field
    Example: "id must be a UUID"

## Response 401 fields (application/json):

  - `statusCode` (integer)
    O código de status HTTP para este erro.
    Example: 401

  - `error` (string)
    A descrição do código de status HTTP para este erro.
    Example: "Unauthorized"

  - `message` (string)
    Uma breve descrição do erro, indicando o que está errado com a solicitação. No caso de um erro 401 Unauthorized, a mensagem é:

  - Unauthorized credentials
    Example: "Unauthorized credentials"