Ventas y transacciones

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

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.

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

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.

tilopay_find_payment

Busca si un cliente ya pagó: revisa los cobros de Tilopay y, si la sesión bancaria está abierta, también las entradas de la cuenta bancaria. Úsala para preguntas como '¿ya me pagó Ana?' o '¿entró el pago de ₡25.000?'.

Parámetros

Devuelve

{ found, bank_checked, payments }

payments = hasta 5 coincidencias con { source: "tilopay" | "baas", at, amount, currency, name, method, reference, email? }.

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

Devuelve

{ total, transactions[], environmentNote }

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

tilopay_get_transaction

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

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

Parámetros

Devuelve

{ result }

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

tilopay_modify_transaction

Modifica una transacción de Tilopay: captura (capture), reembolso (refund) o reversión (reversal) por el monto indicado. El monto nunca puede superar el de la venta original: si el usuario pide más, díselo con el monto real de la venta y pregunta si reembolsa ese monto o una parte; no pidas confirmación de un monto mayor. Solo reembolsa ventas aprobadas, nunca una orden que ya es un reembolso (empieza con «Re-»). Cuando Tilopay confirma el reembolso se genera un comprobante en texto listo para reenviar al cliente. Operación sensible: afecta dinero real y requiere segundo factor. Llámala primero sin `confirmation_code`: se envía un código de 6 dígitos al correo del comercio y la respuesta trae `requires_confirmation`. Repite la misma llamada, con los mismos parámetros, agregando `confirmation_code`. Comunica el resultado exactamente como lo devuelve la herramienta (state): si es pendiente o no confirmado, nunca digas que el reembolso ya se hizo.

Exige confirmación: Confirmaciones que exige Tilopay

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

Parámetros

Devuelve

{ result, state, receipt_code, receipt_url, receipt_text, receipt_whatsapp_url }

state = "approved" | "scheduled" | "unknown" | "failed"; el comprobante (receipt_*) sólo viene en reembolso o reversión aprobados.

tilopay_refunds_list

Reembolsos del comercio. pending=true devuelve los reembolsos pendientes de procesar; si no, el historial. Solo consulta: para reembolsar usa tilopay_modify_transaction.

Parámetros

Devuelve

{ result }

Listado de reembolsos tal como lo entrega Tilopay; con pending: true, sólo los pendientes.

tilopay_cash_close

Cierre de caja diario (se envía por WhatsApp): ventas del día por moneda, rechazos agrupados por motivo y la próxima liquidación de Tilopay. action 'get' muestra la configuración; 'set' la cambia (enabled, time_of_day 'HH:mm' en hora local, days 0=domingo…6=sábado; «de lunes a sábado» = [1,2,3,4,5,6]); 'preview' arma el cierre de hoy ahora. Para «apagá el cierre» usa set con enabled=false. Configurar es solo del dueño.

Parámetros

Devuelve

Sólo texto: la configuración actual, o el cierre de hoy con preview.