> ## 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 facturas

> Obtiene un listado paginado de facturas de tu cuenta.

### Query params

<ParamField query="page" type="number" placeholder="1">
  Número de página. Por defecto 1.
</ParamField>

<ParamField query="filter[id]" type="string">
  Filtra por ID exacto de la factura.
</ParamField>

<ParamField query="filter[status]" type="string" placeholder="CREATED">
  Filtra por estado de la factura.
</ParamField>

<ParamField query="filter[reference]" type="string" placeholder="INV-12345678">
  Filtra por referencia exacta.
</ParamField>

<ParamField query="filter[provider_id]" type="string" placeholder="1321312312">
  Filtra por provider id.
</ParamField>

<ParamField query="sort" type="string" placeholder="-created_at">
  Ordena por fecha de creación. Valores permitidos: created\_at o -created\_at. Por defecto -created\_at.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/invoices?page=1&filter[status]=CREATED&sort=-created_at \
    -H "Authorization: Bearer sk_test_xxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/invoices?page=1&filter[status]=CREATED&sort=-created_at', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk_test_xxx'
    }
  });
  const data = await response.json();
  console.log(data.data); // Array de facturas
  console.log(data.total); // Total de facturas
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.onepay.la/v1/invoices"
  headers = {
      "Authorization": "Bearer sk_test_xxx"
  }
  params = {
      "page": 1,
      "filter[status]": "CREATED",
      "sort": "-created_at"
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  print(data["data"])  # Array de facturas
  print(data["total"])  # Total de facturas
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  $url = "https://api.onepay.la/v1/invoices?" . http_build_query([
      "page" => 1,
      "filter" => ["status" => "CREATED"],
      "sort" => "-created_at"
  ]);

  curl_setopt_array($ch, [
      CURLOPT_URL => $url,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer sk_test_xxx"
      ]
  ]);

  $response = curl_exec($ch);
  $data = json_decode($response, true);

  print_r($data["data"]); // Array de facturas
  echo $data["total"];    // Total de facturas

  curl_close($ch);
  ?>
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
        "name": "Internet plan - Octubre",
        "provider": "biller",
        "provider_id": "987654",
        "reference": "INV-12345678",
        "status": "CREATED",
        "remarks": null,
        "metadata": {
          "key": "value"
        }
      }
    ],
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "per_page": 20,
    "to": 20,
    "total": 21
  }
  ```
</ResponseExample>

Notas

* La respuesta usa un formateador de colección personalizado que expone los datos de paginación en la raíz de la respuesta (current\_page, from, last\_page, per\_page, to, total), además de la clave data.
* El listado no incluye el objeto payment anidado por rendimiento; se expone en el detalle y en la creación.