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

# Listado de clientes

Obtiene la lista de clientes registrados en tu cuenta de OnePay.

<Note>
  **También disponible vía `QUERY`.** Para que la cédula, el teléfono o el email de búsqueda no queden en la URL, este endpoint acepta el método `QUERY`: los mismos parámetros van en el cuerpo JSON en vez de la query string. Ver la [guía del método QUERY](/guides/metodo-query) para ejemplos. El `GET` sigue funcionando igual.
</Note>

### Query Parameters

<ParamField query="search" type="string" placeholder="1234567890">
  Búsqueda global por nombre, documento, teléfono o correo del cliente (coincidencia parcial).
</ParamField>

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

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

<ParamField query="email" type="string" placeholder="juan@example.com">
  Filtra clientes por correo electrónico.
</ParamField>

<ParamField query="document_number" type="string" placeholder="1234567890">
  Filtra clientes por número de documento.
</ParamField>

<ParamField query="phone" type="string" placeholder="+573001234567">
  Filtra clientes por número de teléfono.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/customers?page=1&limit=20 \
    -H "Authorization: Bearer sk_test_xxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/customers?page=1&limit=20', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk_test_xxx'
    }
  });

  const data = await response.json();
  ```

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

  response = requests.get(
      'https://api.onepay.la/v1/customers',
      params={'page': 1, 'limit': 20},
      headers={
          'Authorization': 'Bearer sk_test_xxx'
      }
  )

  data = response.json()
  ```

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

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/customers?page=1&limit=20",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx"
    ]
  ]);

  $response = curl_exec($curl);
  $data = json_decode($response, true);
  ?>
  ```
</RequestExample>

### Response

<ResponseField name="current_page" type="number">
  Número de la página actual
</ResponseField>

<ResponseField name="first_page_url" type="string">
  URL para acceder a la primera página de resultados
</ResponseField>

<ResponseField name="from" type="number">
  Índice inicial del primer elemento en la página actual
</ResponseField>

<ResponseField name="next_page_url" type="string">
  URL para acceder a la siguiente página de resultados. Será `null` si es la última página
</ResponseField>

<ResponseField name="path" type="string">
  URL base de la API sin los parámetros de paginación
</ResponseField>

<ResponseField name="per_page" type="number">
  Cantidad de elementos por página
</ResponseField>

<ResponseField name="prev_page_url" type="string">
  URL para acceder a la página anterior. Será `null` si es la primera página
</ResponseField>

<ResponseField name="to" type="number">
  Índice final del último elemento en la página actual
</ResponseField>

<ResponseField name="data" type="array">
  Datos de la página actual

  <Expandable title="data" defaultOpen name="Clientes">
    <ResponseField name="id" type="string">
      Identificador único del cliente en formato UUID
    </ResponseField>

    <ResponseField name="name" type="string">
      Nombre del cliente
    </ResponseField>

    <ResponseField name="email" type="string">
      Correo electrónico del cliente
    </ResponseField>

    <ResponseField name="phone" type="string">
      Número de teléfono del cliente
    </ResponseField>

    <ResponseField name="document_number" type="string">
      Número de documento de identidad del cliente
    </ResponseField>

    <ResponseField name="document_type" type="string">
      Tipo de documento de identidad del cliente (ej. DNI, RUC, CE)
    </ResponseField>

    <ResponseField name="created_at" type="date">
      Fecha y hora de creación del cliente
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
     "data":[
        {
           "id":"9da58912-101d-46f8-86c9-20a52119c0bf",
           "first_name":"John",
           "last_name":"Doe",
           "email":"john.doe@example.com",
           "phone":"+573100001020",
           "document_type":"CC",
           "document_number":"1060500333",
           "created_at":"2024-12-04T20:09:08.000000Z"
        }
     ],
     "current_page":1,
     "first_page_url":"https:\/\/api.onepay.la\/v1\/customers?page=1",
     "from":1,
     "next_page_url":null,
     "path":"https:\/\/api.onepay.la\/v1\/customers",
     "per_page":20,
     "prev_page_url":null,
     "to":4
  }
  ```
</ResponseExample>