> 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/cobros/consultar-cobro/consulta-por-parametros.md).

# Consulta por párametros

Esta consulta permite filtrar transacciones 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/transaction/`

## Encabezado

| Name                                                   | Value            |
| ------------------------------------------------------ | ---------------- |
| `Content-Type`                                         | application/json |
| `x-auth-token`*<mark style="color:red;">**\***</mark>* | {token}          |
| `child-id`                                             | {business\_id}   |

{% hint style="info" %}
El child-id es opcional y se usa para las cuentas administradas para conocer más puedes ingresa a este [enlace](/documentation/cobros/terminos-de-relevancia.md#cuentas-administradas).
{% endhint %}

## Párametros

<table><thead><tr><th width="272">Name</th><th width="114">Type<select><option value="HB8bagefBtYM" label="string" color="blue"></option><option value="F2MjieU0aXKR" label="numeric" color="blue"></option><option value="s2TYudCxx6VH" label="date" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>description</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Proporciona detalles clave sobre la transacción y es lo que se refleja en los comprobantes de pago.<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="HB8bagefBtYM">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="F2MjieU0aXKR">numeric</span></td><td>Es el código generado a partir del proceso de autenticació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="F2MjieU0aXKR">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="HB8bagefBtYM">string</span></td><td>Es el estado de la transacción al momento de creación.<br><br><mark style="color:green;"><code>pending | unlimit | scheduled | review | created | 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><br><br><code>reference_five</code><br><br><code>reference_six</code></td><td><span data-option="HB8bagefBtYM">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>fee</code></td><td><span data-option="F2MjieU0aXKR">numeric</span></td><td>Es el valor que se refiere al costo asociado a la transacción.</td></tr><tr><td><code>fee_&#x3C;lt></code></td><td><span data-option="F2MjieU0aXKR">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: 1000</code></mark></em></li></ul></td></tr><tr><td><code>iva</code></td><td><span data-option="F2MjieU0aXKR">numeric</span></td><td>Impuesto que se aplica al fee</td></tr><tr><td><code>payment_method</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Método utilizado para realizar el pago de la transacción.<br><br><mark style="color:green;"><code>cash-hand | card | wallet | bank</code></mark> </td></tr><tr><td><code>source</code></td><td><span data-option="HB8bagefBtYM">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>chat | api</code></mark> </td></tr><tr><td><code>channel</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Es la forma como se realiza el cobro.<br><br><mark style="color:green;"><code>whatsapp | link | email</code></mark></td></tr><tr><td><code>process_id</code></td><td><span data-option="HB8bagefBtYM">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>payment_provider_source</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Se refiere a la fuente proveedora de servicios de pago utilizada para realizar la transacción.<br><br><em><mark style="color:blue;"><code>Ejemplo: Nequi</code></mark></em></td></tr><tr><td><code>merchant_phone</code></td><td><span data-option="HB8bagefBtYM">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="HB8bagefBtYM">string</span></td><td>Correo del cliente 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_doc</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Número del documento de identificación del usuario asignado al cobro.<br><br><em><mark style="color:blue;"><code>Ejemplo: 10000000</code></mark></em></td></tr><tr><td><code>payer_phone</code></td><td><span data-option="HB8bagefBtYM">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>payer_email</code></td><td><span data-option="HB8bagefBtYM">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>payer_doc</code></p><p></p></td><td><span data-option="HB8bagefBtYM">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>affiliate_doc</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Tipo de documento de identificación del afiliado.<br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></td></tr><tr><td><code>affiliate_type_doc</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Número del documento de identificación del afiliado.<br><br><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></td></tr><tr><td><code>invoice_type</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td><p>Elige el tipo de vinculación que quieres realizar para esta transacción con tu software contable.</p><p></p><p><em>Obligatorio para el objeto <strong>invoice</strong>.</em><br><br><mark style="color:green;"><code>link | balance | create</code></mark></p></td></tr><tr><td><code>invoice_id</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Corresponde al identificador de la factura o el cliente según el tipo de vinculación definido.<br><br><em><mark style="color:blue;"><code>Ejemplo: FV-2-1234 | GR1234 |</code></mark></em><mark style="color:blue;"><code> </code><code>41515fb0-d815-40ac-86c0-4081eb642fa2</code></mark></td></tr><tr><td><code>invoice_retentions</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Solo si la vinculación es <code>create</code>, agregar las retenciones aplicables para la creación de la factura. <strong>Tener en cuenta que el valor de la factura será el valor de la transacción mas las retenciones definidas.</strong><br><br><mark style="color:green;"><code>Formato: enviar las retenciones separadas por comas</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: [1,2,3]</code></mark></em></td></tr><tr><td><code>invoice_url</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Enlace para descargar la factura del invoice.</td></tr><tr><td><code>invoice_voucher_id</code></td><td><span data-option="HB8bagefBtYM">string</span></td><td>Identificador del recibo de caja.</td></tr><tr><td><code>created_at_start_date</code></td><td><span data-option="s2TYudCxx6VH">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: 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>created_at_end_date</code></td><td><span data-option="s2TYudCxx6VH">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: 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>updated_at_start_date</code></td><td><span data-option="s2TYudCxx6VH">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: 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>updated_at_end_date</code></td><td><span data-option="s2TYudCxx6VH">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></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
{
    "transactions": [
        {
            "external_reference": "51j54e",
            "process_id": "ecad3a2b-6ef6-4a75-a651-8445c8022b7e",
            "description": "Transacción de ejemplo",
            "status": "SUCCESS",
            "amount": 1000,
            "expected_amount": 1000,
            "channel": "LINK",
            "currency": "COP",
            "reference_one": "BACKEND",
            "reference_two": "UPTIME",
            "reference_three": null,
            "reference_four": null,
            "reference_five": null,
            "reference_six": null,
            "reference_seven": null,
            "reference_eight": null,
            "merchant": {
                "name": "ALEJANDRO PEREZ",
                "phone": "573111112222",
                "email": "trazo@gmail.com",
                "id_number": "1000011111",
                "id_type": "CC"
            },
            "payer": {
                "name": "DIEGO PEREZ",
                "phone": "573110011111",
                "email": "diego@gmail.com",
                "id_number": "34000100",
                "id_type": "CC"
            },
            "affiliate": {
                "name": "CAMILO",
                "id_number": "1000011111",
                "id_type": "CC"
            },
            "limit_date": null,
            "reminder_date": null,
            "expected_date": null,
            "created_at": "2024-08-01T09:34:28.054Z",
            "updated_at": "2024-08-02T10:29:00.470Z"
        }
    ]
}

{
    "transactions": [
        {
            "external_reference": "61BUD1R4A",
            "process_id": "62d61cb6-acec-4ee6-96ba-d3d278b56846",
            "description": "Descripción Transacción (con recargo)",
            "status": "CREATED",
            "amount": 1000,
            "expected_amount": 100000,
            "channel": "WHATSAPP",
            "currency": "COP",
            "reference_one": "Referencia 1",
            "reference_two": "Referencia 2",
            "reference_three": "Referencia 3",
            "reference_four": "Referencia 4",
            "reference_five": "Referencia 5",
            "reference_six": "Referencia 6",
            "reference_seven": "Referencia 7",
            "reference_eight": "Referencia 8",
            "expiration": false,
            "attachment": null,
            "comments": null,
            "payment_method": null,
            "payment_provider_source": null,
            "receipt_image": null,
            "type": "inmediato",
            "source": "api",
            "merchant": {
                "name": "ALEJANDRO PEREZ",
                "phone": "573111112222",
                "email": "trazo@gmail.com",
                "id_number": "1000011111",
                "id_type": "CC"
            },
            "payer": {
                "name": "DIEGO PEREZ",
                "phone": "573110011111",
                "email": "diego@gmail.com",
                "id_number": "34000100",
                "id_type": "CC"
            },
            "affiliate": {
                "name": "CAMILO",
                "id_number": "1000011111",
                "id_type": "CC"
            },
            "invoice": {
                "provider": null,
                "type": null,
                "id": null,
                "retentions": null,
                "url": null,
                "voucher": null
            },
            "fees": {
                "service_fee": null,
                "service_variable": null,
                "service_iva": null,
                "service_saas": null,
                "fee_settled": null,
                "saas_settled": null
            },
            "payout_process_status": false,
            "payout_process_id": null,
            "return_review_reason": null,
            "return_success_reason": null,
            "cash_manual_process_status": false,
            "cash_manual_reason": null,
            "limit_date": "2025-05-22",
            "expected_date": null,
            "created_at": "2025-05-07T21:31:56.503Z",
            "updated_at": "2025-06-17T20:47:45.983Z"
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "No results were found for the search query. Please check the search parameters and try again."
}
```

{% endtab %}
{% endtabs %}

## Ejemplo

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

```bash
curl --location '{{base_url}}/v1/merchant/transaction/?amount_ge=10000' \
--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/transaction/?amount_ge=10000`,
  headers: { 
    'x-auth-token': token //Agregar el 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/transaction/?amount_ge=10000"

payload = {}
headers = {
  'x-auth-token': token #Agregar el 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: \[description, created\_start\_date, channel, amount\_ge]. No obstante, es posible realizar el mismo con todos los filtros necesarios.
{% endhint %}

***

### Casos de uso

<details>

<summary><strong>¿Cuántos cobros 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/transaction/?updated_at_start_date=01/20/2024' \
--header 'x-auth-token: {{token}}'
```

</details>

<details>

<summary><strong>¿Qué cobros tiene por conciliar mi vendedor o repartidor?</strong></summary>

Consulta por parámetros con el filtro de status para identificar los cobros en estado por conciliar y puedes seleccionar el rrepartidor según su número de celular, documento o correo.

```bash
curl --location --request GET '{{base_url}}/v1/merchant/transaction/?merchant_phone=573111111111&status=review' \
--header 'x-auth-token: {{token}}'
```

</details>

<details>

<summary><strong>¿Cuántas veces me ha comprado 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/transaction/?payer_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 transacciones exitosas?</strong></summary>

Usa la consulta por parámetros con filtros como método de pago, estado y fecha.

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

</details>

***