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

***


---

# 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/cobros/consultar-cobro/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.