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

***