Ventas y transacciones

Irreversible

Qué 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#

Listar transacciones de Tilopay

Sólo lectura

tilopay_list_transactions

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

Operación del API: POST /api/v1/consultTransactions — ver la página de la operación

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

Sólo lectura

tilopay_get_transaction

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

Operación del API: POST /api/v1/consult — ver la página de la operación

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

Sólo lectura

tilopay_sales_summary

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.

Operación del API: POST /api/v1/consultTransactions (y cálculo local) — ver la página de la operación

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

Sólo lectura

tilopay_analyze_sales

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.

Operación del API: POST /api/v1/consultTransactions (y análisis con modelo) — ver la página de la operación

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

Sensible

tilopay_modify_transaction

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

Operación del API: POST /api/v1/processModification — ver la página de la operación

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

Última verificación: 2026-08-29 · Responsable: equipo-integraciones

Ver como Markdown crudo