> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/dispersiones/consultar-dispersion/consulta-por-parametros.md).

# Consulta por párametros

Esta consulta permite filtrar dispersiones del comercio de acuerdo a los diferentes parámetros definidos en cada solicitud. Es factible combinar más de dos parámetros en una única consulta.

## Ruta

<mark style="color:green;">`GET`</mark> `/v1/merchant/payout/`

## **Encabezado**

<table><thead><tr><th width="238.39996337890625">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>x-auth-token</code><mark style="color:red;">*</mark></td><td><p>Es el código generado a partir del proceso de autenticación.</p><p><em><code>Ejemplo: 8dsa819dj736f1d87fdhd172f12ddw</code></em></p></td></tr><tr><td><code>Content-Type</code><mark style="color:red;">*</mark></td><td><p>Es el tipo de contenido que se está enviando en la solicitud.</p><p><em><code>Ejemplo: application/json</code></em></p></td></tr><tr><td><code>child-id</code></td><td>Es el código de la cuenta que se busca administrar. Es opcional. Más info en el <a href="/pages/cmdh7wawmADehdqeF0JP#user-content-guia-de-uso-paso-a-paso-operar-en-nombre-de-una-cuenta-administrada">link</a><br><em><code>Ejemplo: negociohijo</code></em></td></tr></tbody></table>

## **Párametros**

<table><thead><tr><th width="278">Name</th><th width="114">Type<select><option value="XZqGvvNa8oYs" label="string" color="blue"></option><option value="wLo7zERosWn5" label="numeric" color="blue"></option><option value="5dclxUXhNeoh" label="date" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>description</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Detalles clave sobre la dispersión.<br><br><em><mark style="color:blue;"><code>Ejemplo: Servicio de entrega</code></mark></em></td></tr><tr><td><code>currency</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td><p>Código que identifica la divisa del pago en formato ISO 4217.<br></p><p><mark style="color:green;"><code>COP | USD | MXN</code></mark><br></p></td></tr><tr><td><code>amount</code></td><td><span data-option="wLo7zERosWn5">numeric</span></td><td>Monto exacto de la dispersión.<br><br><em><mark style="color:blue;"><code>Ejemplo: 54000</code></mark></em></td></tr><tr><td><code>amount_&#x3C;gt></code></td><td><span data-option="wLo7zERosWn5">numeric</span></td><td><p></p><ul><li><strong>gt</strong>: Significa "mayor que" (greater than). </li><li><strong>lt</strong>: Significa "menor que" (less than).</li><li><strong>ge</strong>: Significa "mayor o igual que" (greater than or equal to).</li><li><strong>le</strong>: Significa "menor o igual que" (less than or equal to).<br><br><em><mark style="color:blue;"><code>Ejemplo: 50000</code></mark></em></li></ul></td></tr><tr><td><code>status</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Es el estado de la transacción al momento de creación.<br><br><mark style="color:green;"><code>created | pending | scheduled | processing | verifying | success</code></mark></td></tr><tr><td><code>reference_one</code><br><br><code>reference_two</code><br><br><code>reference_three</code><br><br><code>reference_four</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Información adicional de la transacción (número de factura, ordenes de compra, categoría), visible para los usuarios.<br><br><em><mark style="color:blue;"><code>Ejemplo: FAC123</code></mark></em></td></tr><tr><td><code>channel</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Es la forma como se realiza el cobro.<br><br><mark style="color:green;"><code>whatsapp | email | none</code></mark></td></tr><tr><td><code>process_id</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Es el identificador utilizado para hacer referencia a la transacción en el proceso de conciliación.<br><br><em><mark style="color:blue;"><code>Ejemplo: a1a2a-a3a4a</code></mark></em></td></tr><tr><td><code>source</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Hace referencia a la fuente o origen de la transacción, indicando cómo se inició o generó dicha operación.<br><br><mark style="color:green;"><code>dashboard | api | inmediata | automated</code></mark></td></tr><tr><td><code>merchant_phone</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Número de celular del usuario que genera el cobro (incluir el código de área del país).<br><br><em><mark style="color:blue;"><code>Ejemplo: 573112229999</code></mark></em></td></tr><tr><td><code>merchant_email</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Correo del usuario al que se enviarán las notificaciones.<br><br><em><mark style="color:blue;"><code>Ejemplo: usuario@minegocio.com</code></mark></em></td></tr><tr><td><code>merchant_id_number</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Número del documento de identificación del usuario.<br><br><em><mark style="color:blue;"><code>Ejemplo: 10000000</code></mark></em></td></tr><tr><td><code>receiver_phone</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Número de celular del cliente (incluir el código de área del país)<br><br><em><mark style="color:blue;"><code>Ejemplo: 573112223333</code></mark></em></td></tr><tr><td><code>receiver_email</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Correo del cliente al que se enviarán las notificaciones.<br><br><em><mark style="color:blue;"><code>Ejemplo: cliente@minegocio.com</code></mark></em></td></tr><tr><td><p><code>receiver_id_number</code></p><p></p></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Número del documento de identificación del cliente.<br><br><em><mark style="color:blue;"><code>Ejemplo: 10000000</code></mark></em></td></tr><tr><td><code>created_at_start_date</code></td><td><span data-option="5dclxUXhNeoh">date</span></td><td>Es la fecha de creación desde la cual se quiere realizar la consulta.<br><br><mark style="color:green;"><code>Formato: MM/DD/AAAA</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: 10/20/2023</code></mark></em></td></tr><tr><td><code>created_at_end_date</code></td><td><span data-option="5dclxUXhNeoh">date</span></td><td>Es la fecha de creación hasta la cual se quiere realizar la consulta.<br><br><mark style="color:green;"><code>Formato: MM/DD/AAAA</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: 10/20/2023</code></mark></em></td></tr><tr><td><code>updated_at_start_date</code></td><td><span data-option="5dclxUXhNeoh">date</span></td><td>Es la fecha de la última actualización desde la cual se quiere realizar la consulta.<br><br><mark style="color:green;"><code>Formato: MM/DD/AAAA</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: 10/20/2023</code></mark></em></td></tr><tr><td><code>updated_at_end_date</code></td><td><span data-option="5dclxUXhNeoh">date</span></td><td>Es la fecha de la última actualización hasta la cual se quiere realizar la consulta.<br><br><mark style="color:green;"><code>Formato: AAAA/MM/DD</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: 2025/01/30</code></mark></em></td></tr><tr><td><code>bank_account_entity</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td><p>Código que identifica a la entidad bancaria del destinatario. Ver cómo <a href="/pages/ya0rrn5vhnVPFjLNrju9">consultar códigos</a>.</p><p></p><p><em><mark style="color:blue;"><code>Ejemplo: 1007</code></mark></em></p></td></tr><tr><td><code>bank_account_number</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td><p>Número de cuenta a la que se va realizar la dispersión. </p><p></p><p><em><mark style="color:blue;"><code>Ejemplo: 123456789</code></mark></em></p></td></tr><tr><td><code>bank_account_reference</code></td><td><span data-option="XZqGvvNa8oYs">string</span></td><td>Referencia adicional para el pago en la entidad bancaria. Aplica únicamente para <code>agreement</code>.</td></tr></tbody></table>

{% hint style="info" %}
Para los parámetros numéricos, utilizar el punto como separador decimal en caso de ser necesario.
{% endhint %}

## **Respuesta**

{% tabs %}
{% tab title="200" %}

```json
{
    "payouts": [
        {
        "currency": COP,
        "amount": "10000.00",
        "description": "Pago de servicios externos",
        "reference_one": "Octubre",
        "reference_two": "A1234",
        "reference_three": "REF3",
        "reference_four": "REF4",
        "channel": "none",
        "type": "payout",
        "approval": "otp",
        "merchant_phone": "573998887777",
        "merchant_email": "user@data.com",
        "receiver": {
            "phone": "573778889999",
            "email": "receiver@data.com",
            "first_name": "Nombre",
            "last_name": "Apellido",
            "id_type": "CC",
            "id_number": "12345678"
                },
        "bank_account": {
            "entity": "1007",
            "type": "savings",
            "number": "12345678"
                },
        "created_at": "2023-12-21T18:41:48.106Z",
        "updated_at": "2023-12-21T18:41:49.348Z"
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "internalCode": "Q304",
    "message": "Uno o más campos no se encuentran diligenciados correctamente o no son correctos. Por favor revisa los campos [campo_invalido]"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "internalCode": "Q304",
    "message": "No se encontró información para la consulta realizada. Verifica los parámetros de búsqueda e inténtalo nuevamente."
}
```

{% endtab %}
{% endtabs %}

## Ejemplo

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location '{{base_url}}/v1/merchant/payout/?description=Dispersi%C3%B3n%20Prueba&currency=COP&amount_gt=500&amount_ge=800&status=CANCELED&reference_one=REF123' \
--header 'x-auth-token: {{token}}'
```

{% endtab %}

{% tab title="NodeJS (Axios)" %}

```javascript
const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/merchant/payout/?description=Dispersión Prueba&currency=COP&amount_gt=500&amount_ge=800&status=CANCELED&reference_one=REF123`,
  headers: { 
    'x-auth-token': token //Añadir token
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = f"{base_url}/v1/merchant/payout/?description=Dispersión Prueba&currency=COP&amount_gt=500&amount_ge=800&status=CANCELED&reference_one=REF123"

payload = {}
headers = {
  'x-auth-token': token #Añadir token
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
El *request* solo ejemplifica a partir de cuatro párametros. No obstante, es posible realizar el mismo con todos los filtros necesarios.
{% endhint %}

***

### Casos de uso

<details>

<summary><strong>¿Cuántas dispersiones se han completado hoy?</strong></summary>

Usa la consulta por parámetros con filtros de fecha.

```bash
curl --location --request GET '{{base_url}}/v1/merchant/payout/?updated_at_start_date=01/20/2024' \
--header 'x-auth-token: {{token}}'
```

</details>

<details>

<summary><strong>¿Cuántas veces ha dispersado a un usuario específico este mes?</strong></summary>

Consulta con los parámetros de número celular o documento del cliente y fecha la fecha deseada.

```bash
curl --location --request GET '{{base_url}}/v1/merchant/payout/?receiver_phone=573111111111&created_at_start_date=01/20/2024' \
--header 'x-auth-token: {{token}}'
```

</details>

<details>

<summary><strong>¿Cuál ha sido el método de pago más usado en las dispersiones exitosas?</strong></summary>

Usa la consulta por parámetros con filtros como `bank_account_number`,  `bank_account_entity`, entre otros.

```bash
curl --location --request GET '{{base_url}}/v1/merchant/payout/?status=success' \
--header 'x-auth-token: {{token}}'
```

</details>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.qentaz.com/documentation/dispersiones/consultar-dispersion/consulta-por-parametros.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.