# Obtenha os movimentos da sua conta

Obtenha um extrato dos movimentos que ocorreram em sua conta.

Endpoint: GET /account_movements
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

  - `from_created_date` (string)
    Filtre movimentos criados nesta data ou após, no formato YYYY-MM-DD.

  - `until_created_date` (string)
    Filtrar movimentos criados nesta data ou antes, no formato YYYY-MM-DD.

  - `type` (string)
    Filtrar movimentos por um destes tipos (credit ou debit).
    Enum: "credit", "debit"

  - `withdrawal_id` (string)
    Filtrar movimentos por este ID de retirada.

  - `reason` (array)
    Filtre movimentos por um ou mais dos seguintes motivos:
- withdrawal
- payments_service_charge
- payments_service_fee
- payments_service_fee_tax
- payments_service_chargeback
- penny_validation_fee
- penny_validation_fee_tax
- adjustment
    Enum: "withdrawal", "payments_service_charge", "payments_service_fee", "payments_service_fee_tax", "payments_service_chargeback", "penny_validation_fee", "penny_validation_fee_tax", "adjustment"

## Response 200 fields (application/json):

  - `items` (array)
    Um array de objetos de movimento.

  - `items.id` (string)
    O identificador único criado pela Belvo usado para referenciar o movimento.
    Example: "38848ec1-79bb-4827-87b1-819f186ad273"

  - `items.createdDate` (string)
    O carimbo de data e hora ISO-8601 quando o movimento foi criado no banco de dados da Belvo.
    Example: "2025-05-14T16:20:00Z"

  - `items.lastUpdatedDate` (string)
    O carimbo de data e hora ISO-8601 quando as informações sobre o movimento foram atualizadas pela última vez.
    Example: "2025-05-14T16:25:00Z"

  - `items.chargebackDate` (string,null)
    O carimbo de data/hora ISO-8601 quando a Belvo marcou a solicitação de pagamento relacionada como chargeback (aplicável apenas se o movimento foi causado por um chargeback (reason = payments_service_chargeback)). Chargebacks registrados antes da introdução de bankChargebackDate mantêm a data relatada pela instituição bancária aqui.

  - `items.bankChargebackDate` (string,null)
    A data que a instituição bancária informou para o estorno, no formato YYYY-MM-DD, para conciliar com seus extratos (aplicável apenas se o movimento foi causado por um estorno (reason = payments_service_chargeback)). null para estornos registrados antes de este campo ser introduzido.

  - `items.type` (string)
    O tipo de movimento. Pode ser:
  - credit (dinheiro depositado na sua conta)
  - debit (dinheiro retirado da sua conta)
    Enum: "credit", "debit"

  - `items.reason` (string)
    A razão para o movimento. Pode ser:

  - withdrawal: O saldo foi transferido para a conta do comerciante.
  - payments_service_charge: Uma cobrança bem-sucedida ocorreu.
  - payments_service_fee: A taxa da Belvo para uma cobrança bem-sucedida ou falha.
  - payments_service_fee_tax: O imposto sobre a payments_service_fee.
  - payments_service_chargeback: Um estorno ocorreu.
  - penny_validation_fee: A taxa da Belvo para uma validação de centavos.
  - penny_validation_fee_tax: O imposto sobre a penny_validation_fee.
  - adjustment: Usado no caso de qualquer outro movimento necessário para ajustar o saldo do comerciante.
    Enum: "withdrawal", "payments_service_charge", "payments_service_fee", "payments_service_fee_tax", "payments_service_chargeback", "penny_validation_fee", "penny_validation_fee_tax", "adjustment"

  - `items.amount` (number)
    O valor do movimento.
    Example: 125.5

  - `items.currency` (string)
    O código de moeda de três letras (ISO-4217).
    Example: "MXN"

  - `items.paymentRequest` (string)
    O ID da solicitação de pagamento associada.
    Example: "136771f0-13d7-4725-ae0b-e25e9055716d"

  - `items.paymentRequestReference` (string,null)
    Uma referência para a solicitação de pagamento.
    Example: "INV-2025-001"

  - `items.paymentRequestDisplayReference` (string,null)
    Uma descrição de referência exibida no extrato bancário do seu cliente.
    Example: "Payment to ACME Corp"

  - `items.customerName` (string)
    O nome do cliente associado ao movimento.
    Example: "Juan Pérez"

  - `items.customerDocumentType` (string)
    O tipo de documento do cliente. Para 🇲🇽 México, pode ser um dos seguintes:
  - mx_rfc: Número de Identificação Fiscal (Registro Federal de Contribuyentes)
  - mx_curp: Código Único de Registro de População (Clave Única de Registro de Población)
    Enum: "mx_rfc", "mx_curp"

  - `items.customerDocumentNumber` (string)
    O número do documento do cliente.
    Example: "HEGJ850506SX1"

  - `items.paymentMethodType` (string)
    O tipo de método de pagamento. Para o México, esse valor é definido como bank_account.
    Enum: "bank_account"

  - `items.accountNumber` (string)
    O número da conta do seu cliente.
    Example: 12345678901234568

  - `items.withdrawalId` (string,null)
    ID Interno da Belvo para movimentos onde o reason é withdrawal.
    Example: "9e637645-efe8-4fb7-a442-fa2eeb5ad606"

  - `items.withdrawalCreatedDate` (string,null)
    O timestamp ISO-8601 para movimentos onde o reason é withdrawal.
    Example: "2025-05-10T14:30:00Z"

  - `items.withdrawalExtra` (object,null)
    Um objeto personalizável contendo pares chave-valor adicionais que você solicitou que a Belvo incluísse para movimentos onde o reason é withdrawal.
    Example: {"reference_id":"ABC123","withdrawal_method":"bank_transfer"}

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

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

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

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

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

  - `metadata.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"