> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar movimientos

> Lista los movimientos (transacciones) de la billetera de tu empresa.

Devuelve la lista paginada de los movimientos de la billetera de tu empresa, ordenados del más reciente al más antiguo. Es un endpoint **solo de consulta**.

<Note>
  El listado **no** incluye el nodo de origen (`node`) de cada movimiento. Para obtenerlo, consulta el [detalle de un movimiento](/client/movimientos/detail).
</Note>

### Query Parameters

<ParamField query="filter[type]" type="string" placeholder="deposit">
  Filtra por tipo de movimiento: `deposit` (entrada de dinero) o `withdraw` (salida de dinero).
</ParamField>

<ParamField query="filter[subtype]" type="string" placeholder="PAYIN">
  Filtra por el código de movimiento específico (ver tabla de `subtype` más abajo), por ejemplo `PAYIN`, `CASHOUT` o `PAYOUT`.
</ParamField>

<ParamField query="filter[confirmed]" type="boolean" placeholder="true">
  Filtra por estado de confirmación: `true` (confirmados) o `false` (reservados / pendientes).
</ParamField>

<ParamField query="filter[wallet_id]" type="string" placeholder="0ced28ec-bd54-42a0-844d-00fde7b03300">
  Filtra los movimientos de una billetera específica. El valor es el `id` (UUID) de la billetera, obtenido en [listar billeteras](/client/movimientos/wallets). Un `id` inexistente o de otra empresa devuelve una lista vacía.
</ParamField>

<ParamField query="filter[from]" type="string" placeholder="2025-01-01">
  Fecha inicial (inclusive) en formato `YYYY-MM-DD`. Devuelve movimientos creados desde esta fecha.
</ParamField>

<ParamField query="filter[to]" type="string" placeholder="2025-01-31">
  Fecha final (inclusive) en formato `YYYY-MM-DD`. Devuelve movimientos creados hasta esta fecha.
</ParamField>

<ParamField query="sort" type="string" default="-created_at">
  Ordenamiento. Valores permitidos: `created_at`, `-created_at`, `amount`, `-amount`. El prefijo `-` indica orden descendente.
</ParamField>

<ParamField query="per_page" type="integer" default="20">
  Cantidad de resultados por página (mínimo 1, máximo 100).
</ParamField>

<ParamField query="page" type="integer" default="1">
  Número de página para paginación.
</ParamField>

### Ejemplos de uso

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.onepay.la/v1/transactions \
      -X GET \
      -H "Authorization: Bearer sk_test_xxx"
    ```

    Con filtros de tipo y rango de fechas:

    ```bash theme={null}
    curl "https://api.onepay.la/v1/transactions?filter[type]=deposit&filter[from]=2025-01-01&filter[to]=2025-01-31" \
      -X GET \
      -H "Authorization: Bearer sk_test_xxx"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```ts theme={null}
    const params = new URLSearchParams({
      'filter[type]': 'deposit',
      'filter[from]': '2025-01-01',
      'filter[to]': '2025-01-31',
    });

    const response = await fetch(`https://api.onepay.la/v1/transactions?${params}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer sk_test_xxx',
      },
    });
    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        'https://api.onepay.la/v1/transactions',
        params={
            'filter[type]': 'deposit',
            'filter[from]': '2025-01-01',
            'filter[to]': '2025-01-31',
        },
        headers={'Authorization': 'Bearer sk_test_xxx'},
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

### Response

<ResponseField name="data" type="array">
  Lista de movimientos.

  <Expandable title="Propiedades de cada movimiento">
    <ResponseField name="id" type="string">UUID del movimiento. Úsalo para consultar el [detalle](/client/movimientos/detail).</ResponseField>
    <ResponseField name="wallet_id" type="string">UUID de la billetera a la que pertenece el movimiento. Coincide con el `id` de [listar billeteras](/client/movimientos/wallets).</ResponseField>
    <ResponseField name="type" type="string">Tipo de movimiento: `deposit` (entrada) o `withdraw` (salida).</ResponseField>
    <ResponseField name="amount" type="number">Monto del movimiento en pesos (COP).</ResponseField>
    <ResponseField name="amount_label" type="string">Monto formateado, por ejemplo `$50.000`.</ResponseField>
    <ResponseField name="concept" type="string">Concepto del movimiento. Puede ser `null`.</ResponseField>
    <ResponseField name="description" type="string">Descripción legible del movimiento. Puede ser `null`.</ResponseField>
    <ResponseField name="subtype" type="string">Código del tipo de movimiento (ver tabla más abajo).</ResponseField>
    <ResponseField name="subtype_label" type="string">Etiqueta legible del `subtype`, por ejemplo `Pago`.</ResponseField>
    <ResponseField name="confirmed" type="boolean">`true` si el movimiento está confirmado; `false` si está reservado o pendiente.</ResponseField>
    <ResponseField name="accredited_at" type="string">Fecha (ISO 8601) en que el saldo se acredita al balance. Puede ser `null`.</ResponseField>
    <ResponseField name="created_at" type="string">Fecha de creación en formato ISO 8601.</ResponseField>
    <ResponseField name="external_id" type="string">Identificador externo asociado al movimiento, si existe. Puede ser `null`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_page" type="integer">Página actual.</ResponseField>
<ResponseField name="from" type="integer">Índice del primer registro en la página actual.</ResponseField>
<ResponseField name="last_page" type="integer">Última página disponible.</ResponseField>
<ResponseField name="per_page" type="integer">Cantidad de registros por página.</ResponseField>
<ResponseField name="to" type="integer">Índice del último registro en la página actual.</ResponseField>
<ResponseField name="total" type="integer">Total de movimientos.</ResponseField>

#### Valores de `subtype`

Los más comunes, agrupados por categoría:

| Categoría  | Código              | Etiqueta                                     |
| ---------- | ------------------- | -------------------------------------------- |
| Entradas   | `PAYIN`             | Pago                                         |
| Entradas   | `PAYIN_KEY`         | Pago con llave                               |
| Entradas   | `PAYIN_INSTANT`     | Pago instantáneo                             |
| Entradas   | `MONETIZATION`      | Abono por monetización                       |
| Salidas    | `CASHOUT`           | Desembolso a cuenta                          |
| Salidas    | `PAYOUT`            | Transferencia                                |
| Salidas    | `BILL_PAYMENT`      | Pago de factura                              |
| Salidas    | `WALLET_TRANSFER`   | Transferencia entre Wallets OnePay           |
| Comisiones | `PAYIN_COMMISSION`  | Comisión pago aprobado con IVA               |
| Comisiones | `PAYOUT_COMMISSION` | Procesamiento de datos transferencia con IVA |
| Impuestos  | `TAX_ICA`           | Impuesto ICA                                 |
| Impuestos  | `TAX_RETE_FUENTE`   | Impuesto Retención en la Fuente              |
| Impuestos  | `TAX_RETE_IVA`      | Impuesto Retención IVA                       |
| Ajustes    | `MANUAL`            | Ajuste manual de balance                     |

### Ejemplo de respuesta

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "0194b42f-5515-7245-b9f4-193c92f37b8c",
        "wallet_id": "0ced28ec-bd54-42a0-844d-00fde7b03300",
        "type": "deposit",
        "amount": 50000,
        "amount_label": "$50.000",
        "concept": "Pago recibido",
        "description": "Pago recibido: f37b8c",
        "subtype": "PAYIN",
        "subtype_label": "Pago",
        "confirmed": true,
        "accredited_at": null,
        "created_at": "2025-01-29T22:29:48.000000Z",
        "external_id": "ORD-9912"
      },
      {
        "id": "0194ad6d-2464-7215-a9a6-8e88d9a5a09d",
        "wallet_id": "0ced28ec-bd54-42a0-844d-00fde7b03300",
        "type": "withdraw",
        "amount": 1000,
        "amount_label": "$1.000",
        "concept": "Transferencia enviada",
        "description": "Transferencia enviada: a5a09d",
        "subtype": "CASHOUT",
        "subtype_label": "Desembolso a cuenta",
        "confirmed": true,
        "accredited_at": null,
        "created_at": "2025-01-28T14:59:58.000000Z",
        "external_id": null
      }
    ],
    "current_page": 1,
    "from": 1,
    "last_page": 65,
    "per_page": 20,
    "to": 20,
    "total": 1291
  }
  ```

  ```json 401 theme={null}
  {
    "message": "No autenticado",
    "code": 10000,
    "code_name": "unauthenticated"
  }
  ```
</ResponseExample>