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

# Método QUERY

> Envía los filtros en el cuerpo de la petición, no en la URL, usando el método HTTP QUERY — sin sacar el GET de servicio.

## ¿Qué es?

`QUERY` es un método HTTP estandarizado en la RFC 10008: es como un `GET`, pero **lleva cuerpo**. Es **seguro** (solo lectura) e **idempotente**, así que se comporta igual que un `GET` — la única diferencia es que los filtros viajan en el cuerpo JSON en lugar de la query string.

Por ahora lo soportan **solo** los endpoints de listado que aparecen en la [tabla de abajo](#endpoints-que-lo-soportan); el resto de la API sigue aceptando únicamente `GET`. Y el `GET` de esos endpoints **sigue funcionando exactamente igual**: `QUERY` es una alternativa opcional, no un reemplazo.

## ¿Por qué usarlo?

Cuando filtras por un identificador del cliente —una **cédula**, un **teléfono**, un **email** o una **llave Bre‑B**— con `GET` ese dato queda en la URL (`?search=1234567890`), y las URLs terminan guardadas en logs de acceso, historiales y proxies intermedios. Con `QUERY` ese mismo filtro va en el **cuerpo**, fuera de la URL:

* **Privacidad**: los identificadores sensibles quedan fuera de la URL, y por tanto fuera de los access logs y del historial del navegador.
* **Sin límite de tamaño**: filtros grandes o anidados no chocan con el límite de longitud de la URL.
* **Semántica correcta**: al ser seguro e idempotente, clientes y proxies pueden reintentarlo sin riesgo de efectos secundarios.

## Endpoints que lo soportan

| Endpoint                                         | Página                                                            |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| `GET \| QUERY /charges`                          | [Listar cargos](/client/charges/list)                             |
| `GET \| QUERY /customers`                        | [Listar clientes](/client/customers/list)                         |
| `GET \| QUERY /utilities/direct-debits`          | [Listar domiciliaciones](/client/utilities/auto-debit-list)       |
| `GET \| QUERY /utilities/direct-debits/payments` | [Pagos de domiciliación](/client/utilities/direct-debit-payments) |

## Cómo se usa

Toma los mismos parámetros que enviarías en la query string (`filter[...]`, `sort`, `page`) y mándalos como JSON en el cuerpo, con el header `Content-Type: application/json`:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/customers \
    -X QUERY \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "search": "1234567890",
      "page": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/customers', {
    method: 'QUERY',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      search: '1234567890', // Cédula del cliente — viaja en el cuerpo, no en la URL
      page: 1
    })
  });
  const data = await response.json();
  console.log(data.data); // Array de clientes
  ```

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

  url = "https://api.onepay.la/v1/customers"
  headers = {
      "Authorization": "Bearer sk_test_xxx",
      "Content-Type": "application/json"
  }
  data = {
      "search": "1234567890",  # Cédula del cliente — viaja en el cuerpo
      "page": 1
  }

  response = requests.request("QUERY", url, headers=headers, json=data)
  data = response.json()
  print(data["data"])  # Array de clientes
  ```

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

  curl_setopt_array($ch, [
      CURLOPT_URL => "https://api.onepay.la/v1/customers",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => "QUERY",
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer sk_test_xxx",
          "Content-Type: application/json"
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "search" => "1234567890", // Cédula del cliente — viaja en el cuerpo
          "page" => 1
      ])
  ]);

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

  print_r($data["data"]); // Array de clientes

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

La respuesta es **idéntica** a la del `GET`: el mismo formato paginado (`data`, `current_page`, `total`, …).

<Note>
  Si un mismo filtro va tanto en la query string como en el cuerpo, **gana el de la query string**.
</Note>

## Compatibilidad de clientes

`QUERY` funciona con cualquier cliente HTTP que permita métodos personalizados: `fetch`, `axios`, `requests` de Python, `curl`, Guzzle, entre otros. Algunas librerías muy antiguas no lo soportan; en ese caso, sigue usando `GET`, que **nunca dejará de funcionar**.