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#

Resumen y tendencias de ventas

Sólo lectura

tilopay_sales_summary

Calcula métricas de ventas a partir de las transacciones de Tilopay: 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 de Tilopay 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 (opcional)
`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.

Listar transacciones de Tilopay

Sólo lectura

tilopay_list_transactions

Lista transacciones de Tilopay en un rango de fechas. Usa status para aprobadas/rechazadas y sort=newest para 'los últimos N' o 'la última'. Una sola llamada basta: no acortes el rango para buscar filas.

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"
`status`	string (approved \| declined \| all)	—	approved = solo aprobadas, declined = solo rechazadas, all = todas
`sort`	string (newest \| oldest)	—	newest = más recientes primero
`onlyAproved`	boolean	—	Compatibilidad: false equivale a status: "all"
`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

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

Capturar, reembolsar o reversar

Sensible

tilopay_modify_transaction

Modifica una transacción de Tilopay: captura (capture), reembolso (refund) o reversión (reversal) por el monto indicado. Operación sensible: afecta dinero real y requiere segundo factor. Llámela primero sin `confirmation_code`: se envía un código de 6 dígitos al correo del comercio y la respuesta trae `requires_confirmation`. Repita la misma llamada, con los mismos parámetros, agregando `confirmation_code`.

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
`confirmation_code`	string	—	Código de 6 dígitos recibido por correo para autorizar la operación

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