# Ventas y transacciones

> Herramientas del MCP para consultar transacciones, medir ventas y modificar una transacción.

- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp/ventas

## Qué cubre [#que-cubre]

Este grupo cubre la lectura de transacciones y el análisis de ventas del comercio, más la modificación de una transacción: captura, reembolso o reversión. La modificación mueve dinero real y está marcada como sensible.

## Herramientas [#herramientas]

### Listar transacciones de Tilopay [#tilopay-list-transactions]

- `tilopay_list_transactions`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consultTransactions` — https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

Consulta las transacciones de Tilopay en un rango de fechas. Permite filtrar por moneda, número de orden, correo del cliente y ambiente.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `startDate` | string | sí | Fecha inicial, ej. "2026-08-01 00:00:00" |
| `endDate` | string | sí | Fecha final, ej. "2026-08-31 23:59:59" |
| `onlyAproved` | boolean | — | Solo transacciones aprobadas (por defecto true) |
| `environment` | string (production | test) | — | Ambiente, por defecto production |
| `currency` | array<string> | — | Monedas, ej. ["USD","CRC"] |
| `orderNumber` | string | — | Filtrar por número de orden |
| `email` | string | — | Filtrar por correo del cliente |
| `limit` | integer | — | Máximo de filas a devolver (por defecto 100, máximo 500) |

**Devuelve**

`{ total, transactions[], environmentNote }`

total = filas encontradas antes de aplicar limit; transactions = las filas devueltas; environmentNote avisa si el ambiente consultado no trajo filas.

### Consultar una transacción [#tilopay-get-transaction]

- `tilopay_get_transaction`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consult` — https://www.tilopay.com/developers/api/procesos-operativos/consult

Obtiene el detalle de una transacción específica a partir de su número de orden.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `orderNumber` | string | sí | Número de orden de la transacción |
| `merchantId` | string | — | ID de comercio (opcional) |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

### Resumen y tendencias de ventas [#tilopay-sales-summary]

- `tilopay_sales_summary`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consultTransactions (y cálculo local)` — https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

Calcula métricas de ventas a partir de las transacciones: totales por moneda, ticket promedio, tasa de aprobación, ventas por día, día de la semana y hora, mejores clientes, motivos de rechazo y tendencia.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `startDate` | string | sí | Fecha inicial "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | sí | Fecha final "YYYY-MM-DD HH:mm:ss" |
| `includeDeclined` | boolean | — | Incluir transacciones rechazadas para medir tasa de aprobación (por defecto true) |
| `environment` | string (production | test) | — | — |
| `currency` | array<string> | — | — |

**Devuelve**

`{ summary, trends, environmentNote }`

summary trae range, timezoneNote, totalRows, payments {total, approved, declined, approvalRate}, refunds {total, approved, failed, successRate}, byCurrency por moneda con pagos, costos desglosados (commission, iva_commission, cost, cost_iva, retention_iva, retention_rent, totalDeducted, taxWithholdings, pspCost), netToLiquidate, reconciles y reconciliationDelta; reembolsos; y netForPeriod. Además daily, sample, byWeekday, byHour, topCustomers, declineReasons, refundFailureReasons y transactionTypes. byWeekday, byHour y topCustomers vienen en null si la muestra es insuficiente (menos de 30 filas o menos de 5 días distintos). trends viene en null en ese mismo caso. Las horas y días están en UTC.

### Agente analista de ventas [#tilopay-analyze-sales]

- `tilopay_analyze_sales`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consultTransactions (y análisis con modelo)` — https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

Agente que analiza las transacciones en un rango de fechas y devuelve un informe en lenguaje natural: desempeño, tendencias, estacionalidad, calidad de aprobación, riesgos y recomendaciones accionables.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `startDate` | string | sí | Fecha inicial "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | sí | Fecha final "YYYY-MM-DD HH:mm:ss" |
| `question` | string | — | Pregunta o enfoque específico para el análisis |
| `environment` | string (production | test) | — | — |
| `currency` | array<string> | — | — |

**Devuelve**

`{ report, summary, trends, environmentNote }`

report es el informe en lenguaje natural; summary y trends son los mismos de tilopay_sales_summary. Si no hay transacciones en el rango, devuelve solo un texto avisándolo, sin structuredContent.

### Capturar, reembolsar o reversar [#tilopay-modify-transaction]

- `tilopay_modify_transaction`
- Acceso: Sensible
- Operación del API: `POST /api/v1/processModification` — https://www.tilopay.com/developers/api/procesos-operativos/process-modification

Modifica una transacción: captura, reembolso o reversión por el monto indicado. Operación sensible: afecta dinero real.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `orderNumber` | string | sí | Número de orden de la transacción |
| `action` | string (capture | refund | reversal) | sí | Tipo de modificación |
| `amount` | number | sí | Monto a modificar, mayor que cero |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.