# Recetas
> Catorce flujos de punta a punta con el servidor MCP: dashboard de insights, ventas por WhatsApp, recuperación de cobros recurrentes fallidos, cobranza B2B, proyección de caja con datos bancarios, detección de anomalías, cierre de mes, reembolsos, suscripciones recurrentes, optimización de planes, cobros a tarjetas almacenadas, depuración de integraciones y Tilopay como herramienta de otros agentes.
- kind: guide
- status: stable
- last_verified: 2026-09-04
- url: https://www.tilopay.com/developers/agentes/mcp/recetas
## Construir un dashboard de insights en tiempo real [#dashboard-insights]
1. `tilopay_sales_summary` trae los totales, costos y neto del período que querés monitorear.
2. `tilopay_analyze_sales` convierte esos números en un resumen narrativo con tendencias y
observaciones.
3. `tilopay_list_transactions` lista las transacciones recientes para completar el tablero.
4. `tilopay_get_transaction` abre el detalle de cualquier operación que necesite revisión.
El resumen usa UTC, no hora local. Si el comercio tiene poco volumen, las tendencias y los clientes
destacados pueden venir vacíos.
### Ejemplos de preguntas para el dashboard [#ejemplos-dashboard]
- “¿Cómo me fue hoy?” → `tilopay_sales_summary` + `tilopay_analyze_sales`.
- “¿Cuáles son mis productos o servicios más vendidos esta semana?” → `tilopay_analyze_sales`
sobre el rango de los últimos 7 días.
- “¿Tengo transacciones fallidas o sin liquidar?” → `tilopay_list_transactions` filtrando por
estado, luego `tilopay_get_transaction` para cada caso.
- “¿Cómo evolucionan mis ingresos netos respecto al mes pasado?” → comparar dos llamadas a
`tilopay_sales_summary` con ventanas de fechas distintas.
## Vender por WhatsApp desde el catálogo [#cobrar-por-whatsapp]
1. `tilopay_catalog_list_items` lista los productos o servicios del comercio para responder la
consulta del cliente con nombres y precios reales.
2. `tilopay_catalog_get_item` abre el detalle del ítem elegido cuando hay que confirmar precio,
moneda o descripción antes de armar el pedido.
3. El agente arma el pedido, calcula el total y se lo confirma al cliente antes de cobrar.
4. `tilopay_save_contact` guarda al comprador (nombre, correo, teléfono) para asociarlo al cobro y
reutilizarlo en ventas futuras.
5. `tilopay_create_payment_link` crea el enlace por el total del pedido, con una descripción que
identifique la orden.
6. `tilopay_send_payment_link_whatsapp` prepara el envío al cliente.
7. `tilopay_get_payment_link` consulta el estado del enlace para confirmar el pago y cerrar la
conversación con el comprobante.
`tilopay_send_payment_link_whatsapp` no envía el mensaje: devuelve un enlace `wa.me` con el texto
listo para enviar con un toque. Si no hay teléfono ni contacto guardado con ese nombre, la
herramienta lo pide. El agente puede quedarse consultando `tilopay_get_payment_link` cada cierto
tiempo para avisarle al comercio en cuanto el enlace pase a pagado.
Con esta receta un comercio sin tienda en línea vende de punta a punta dentro del chat: catálogo,
pedido, cobro y confirmación, sin intervención humana salvo la que el propio comercio quiera exigir.
## Recuperar cobros recurrentes fallidos (dunning inteligente) [#dunning-inteligente]
1. `tilopay_recurring_list_plans` lista los planes activos del comercio.
2. `tilopay_recurring_subscriber_payments` recorre los pagos de los suscriptores de cada plan y
separa los cobros rechazados del período.
3. `tilopay_get_transaction` abre cada rechazo para leer el código de respuesta y clasificar la
causa: fondos insuficientes, tarjeta vencida, tarjeta bloqueada, sospecha de fraude.
4. Según la causa, el agente decide la acción y se la propone al comercio: esperar el reintento del
plan cuando el rechazo es transitorio (fondos insuficientes), o pedirle al cliente un nuevo medio
de pago cuando el rechazo es definitivo (tarjeta vencida o bloqueada).
5. `tilopay_create_payment_link` crea un enlace por el saldo por cobrar cuando hay que pedirle al
cliente que pague la cuota con otra tarjeta.
6. `tilopay_send_payment_link_whatsapp` o `tilopay_send_payment_link_email` prepara el mensaje al
cliente con un texto adaptado al motivo del rechazo.
7. `tilopay_get_payment_link` confirma cuando el cliente pagó, y `tilopay_recurring_get_subscriber`
verifica el estado del suscriptor después de la recuperación.
Un agente que corre esta receta cada mañana convierte la lista de rechazos en dos colas: la que se
resuelve sola con el reintento del plan y la que necesita un mensaje al cliente. El comercio recibe
solo el resumen: cuántos cobros se recuperaron y cuáles siguen sin recuperarse.
No uses `tilopay_recurring_manage_subscriber` para "castigar" un rechazo: `pause` y `delete`
afectan cobros futuros y `delete` no se deshace. Pausar o dar de baja a un suscriptor es una
decisión del comercio, con confirmación humana explícita, nunca una reacción automática a un cobro
fallido.
## Cobranza B2B con cuentas por cobrar [#cobranza-b2b]
1. `tilopay_list_contacts` trae los clientes empresariales del comercio; `tilopay_save_contact`
registra los que falten con nombre, correo y teléfono de la persona que paga.
2. `tilopay_create_payment_link` crea un enlace por cada factura sin pagar, con el número de
factura en la descripción y una fecha de vencimiento.
3. `tilopay_send_payment_link_email` prepara el primer envío; `tilopay_send_payment_link_whatsapp`
prepara el recordatorio cuando la factura sigue sin pagar.
4. `tilopay_get_payment_link` revisa el estado de cada enlace para actualizar la lista de cuentas
por cobrar sin entrar al panel.
5. `baas_search_payment` o `baas_list_payments` buscan en las cuentas bancarias del comercio una
transferencia directa (SINPE o transferencia bancaria) que coincida con el monto y el cliente,
para marcar como pagada una factura que el cliente liquidó fuera del enlace.
6. `tilopay_delete_payment_link` elimina el enlace de una factura que ya se pagó por transferencia,
para evitar un cobro doble.
Esta receta responde el "¿ya me pagaron?" que consume horas administrativas en negocios que
facturan a empresas: una sola lista con facturas, enlaces, estado y pagos recibidos por cualquier vía.
Las herramientas `baas_*` son de solo consulta y requieren que soporte haya registrado las
credenciales del API bancario del comercio. Si no están configuradas, la herramienta lo indica y la
receta sigue funcionando solo con los enlaces de pago.
## Proyectar la caja con datos de la pasarela y del banco (CFO de bolsillo) [#cfo-de-bolsillo]
1. `tilopay_sales_summary` trae las ventas de las últimas semanas para estimar los ingresos
esperados del período siguiente.
2. `tilopay_recurring_list_plans` y `tilopay_recurring_get_plan` cuantifican los cobros recurrentes
comprometidos y sus fechas.
3. `baas_list_balances` o `baas_get_balance` traen el saldo real de cada cuenta bancaria del
comercio.
4. `baas_list_payments` lista las transferencias de los últimos meses para detectar las salidas
recurrentes: planilla, alquiler, proveedores.
5. `baas_analyze_payments` resume esos movimientos en lenguaje natural para identificar patrones y
fechas pico.
6. El agente combina saldo, entradas previstas y salidas previstas en una proyección diaria, señala
los días con saldo mínimo o negativo y propone acciones.
7. `tilopay_create_payment_link` y `tilopay_send_payment_link_email` ponen a cobro facturas
sin pagar cuando el comercio aprueba esa acción.
El valor está en cruzar dos fuentes que normalmente viven separadas: la pasarela sabe qué va a
entrar y el banco sabe qué hay y qué sale. Una rutina semanal produce un briefing corto con la
proyección y las alertas, antes de que abra el negocio.
Las herramientas `baas_*` nunca inician, aprueban ni revierten transferencias. Si la proyección
sugiere mover fondos entre cuentas, esa acción la ejecuta una persona en el banco; el agente solo la
recomienda y la registra. La proyección es una estimación, no un estado financiero.
## Detectar anomalías y actuar [#detector-anomalias]
1. `tilopay_sales_summary` compara la ventana actual (por ejemplo la última hora o el día) contra
el mismo período de referencia para detectar caídas de aprobación, picos de rechazos o cambios
bruscos en el ticket promedio.
2. `tilopay_list_transactions` filtra por estado para ver si los rechazos se concentran en un
método de pago, una moneda o un patrón de intentos repetidos.
3. `tilopay_get_transaction` abre casos representativos para leer los códigos de respuesta.
4. `tilopay_diagnostics` verifica credenciales y disponibilidad de los endpoints para separar un
problema de la integración del comercio de un problema de los clientes o del emisor.
5. `tilopay_help_guides` busca en las guías oficiales la explicación y los pasos de corrección que
correspondan al código de respuesta o al síntoma.
6. El agente abre la alerta con el diagnóstico ya hecho: qué cambió, desde cuándo, causa probable y
acción sugerida.
El resumen de ventas usa UTC. Al comparar ventanas cortas, alineá las horas; una "caída" a
medianoche local puede ser solo el corte del día en UTC. Muchos intentos rechazados en pocos minutos
con montos pequeños y tarjetas distintas pueden indicar pruebas de tarjetas robadas: reportalo a
soporte en vez de reintentar.
## Cerrar las ventas del mes [#cierre-de-mes]
1. `tilopay_sales_summary` devuelve los totales, costos y neto del período.
2. `tilopay_analyze_sales` produce el informe en lenguaje natural.
3. `tilopay_get_transaction` trae el detalle de las transacciones que haya que revisar.
Las horas y los días del resumen están en UTC, no en hora local. Las tendencias y los clientes
destacados vienen vacíos si la muestra es chica.
## Reembolsar con confirmación humana [#reembolso]
1. `tilopay_list_transactions` localiza la transacción en el rango de fechas.
2. `tilopay_get_transaction` muestra el detalle para confirmar que es la correcta.
3. El agente le pide confirmación al usuario. Este paso lo impone el cliente MCP, no Tilopay.
4. `tilopay_modify_transaction` ejecuta la modificación con la acción y el monto.
## Revisar una suscripción recurrente [#suscripcion-recurrente]
1. `tilopay_recurring_list_plans` lista los planes de cobro recurrente del comercio.
2. `tilopay_recurring_get_plan` abre el plan que interesa por su ID.
3. `tilopay_recurring_get_subscriber` muestra el detalle del suscriptor.
4. `tilopay_recurring_subscriber_payments` lista los pagos de ese suscriptor para ver cuáles
pasaron y cuáles no.
Sirve para responder "¿por qué este cliente aparece sin cobrar este mes?" sin entrar al panel.
## Optimizar los planes de suscripción [#optimizar-planes]
1. `tilopay_recurring_list_plans` lista los planes activos con su precio y periodicidad.
2. `tilopay_recurring_get_plan` abre cada plan para conocer la cantidad de suscriptores y su
configuración.
3. `tilopay_recurring_subscriber_payments` recorre los pagos por suscriptor para calcular, por plan,
la tasa de cobros exitosos, el mes en que más suscriptores dejan de pagar y la antigüedad promedio.
4. `tilopay_recurring_get_subscriber` revisa los casos atípicos que el análisis señale.
5. El agente presenta el comparativo entre planes: retención, ingreso por suscriptor y punto de
abandono, y propone cambios de precio, periodicidad o contenido.
6. `tilopay_create_payment_link` permite probar una oferta nueva con un segmento pequeño de
contactos antes de modificar un plan.
Es análisis de precios con datos reales de cobro. El agente no modifica planes: propone, y el
comercio decide en el panel.
## Pausar o dar de baja a un suscriptor [#pausar-suscriptor]
1. `tilopay_recurring_get_subscriber` confirma que el suscriptor es el correcto.
2. El agente le pide confirmación al usuario, con el nombre y el plan a la vista.
3. `tilopay_recurring_manage_subscriber` ejecuta `pause`, `reactivate` o `delete`.
`tilopay_recurring_manage_subscriber` está marcada como sensible: afecta cobros futuros y `delete`
no se deshace. Nunca la ejecutés sin confirmación humana explícita.
## Cobrar a un grupo con tarjetas almacenadas [#cobro-masivo]
1. `tilopay_saved_cards_list_groups` lista los grupos de cobro.
2. `tilopay_saved_cards_list_affiliates` muestra los afiliados del grupo elegido, para saber a
cuántas tarjetas se le va a cobrar.
3. El agente resume monto, moneda, motivo y cantidad de afiliados, y pide confirmación.
4. `tilopay_saved_cards_create_payments` crea los cobros.
5. `tilopay_saved_cards_list_collections` y `tilopay_saved_cards_collection_detail` revisan el
resultado: la segunda necesita el `code` que devuelve la primera.
`tilopay_saved_cards_create_payments` mueve dinero real de las tarjetas almacenadas. Tratala como
una operación de un solo intento: confirmá antes, y verificá después con el detalle del cobro.
## Depurar una integración y acompañar a un desarrollador [#depurar-integracion]
1. `tilopay_diagnostics` prueba las credenciales y un endpoint de cada grupo del API, para separar
un problema de credenciales de un problema de la petición.
2. `tilopay_debug_code` recibe el fragmento de código, el log o el stack trace y devuelve
diagnóstico, causa raíz, corrección y riesgos.
3. `tilopay_help_guides` responde las dudas de uso del panel con las guías oficiales.
4. `tilopay_list_transactions` y `tilopay_get_transaction` confirman si la operación que el
desarrollador cree fallida en realidad llegó a Tilopay y con qué resultado.
`tilopay_debug_code` no lee el repositorio ni ejecuta el código: analiza sólo lo que le pasás. Antes
de mandarlo, quitá credenciales del fragmento; la herramienta oculta lo que reconoce como secreto,
pero no reemplaza esa revisión.
Con estas cuatro herramientas un agente de soporte atiende el onboarding técnico completo: verifica
la cuenta, encuentra la causa del error, entrega la corrección con la guía oficial y confirma contra
las transacciones reales. Las preguntas que se repiten son la señal de qué guía o ejemplo debe agregarse al
portal.
Las tarjetas de prueba del modo sandbox están en la guía de pruebas del portal. El modo sandbox se
alterna desde la cuenta; no existe un host separado.
## Tilopay como herramienta de otros agentes [#tilopay-como-herramienta]
1. El comercio solicita acceso al servidor MCP con el formulario del portal (nombre de la persona
responsable, correo del comercio y nombre del comercio); soporte confirma la aprobación y las
condiciones de uso.
2. El agente externo (el asistente de un ERP, un bot de tienda en línea, un agente contable)
conecta el servidor MCP con esas credenciales y ejecuta `tilopay_diagnostics` para verificar la
conexión.
3. Con el catálogo de herramientas cargado, el agente externo usa las herramientas de consulta
(`tilopay_sales_summary`, `tilopay_list_transactions`, `tilopay_recurring_*`, `baas_*`) para
responder preguntas del negocio dentro de su propia conversación.
4. Para acciones que crean o mueven dinero (`tilopay_create_payment_link`,
`tilopay_modify_transaction`, `tilopay_saved_cards_create_payments`,
`tilopay_recurring_manage_subscriber`) el agente externo aplica la política de confirmación
descrita en la página de permisos antes de ejecutar.
Esta receta cambia la posición del MCP: no es solo un asistente dentro de Tilopay, es la capa de
pagos que cualquier agente puede invocar. Las demás recetas de esta página funcionan igual cuando
las ejecuta un agente de terceros.
El consumo del MCP puede tener costos adicionales según el volumen; soporte lo detalla al validar el
volumen transaccional del comercio. Las herramientas marcadas como sensibles exigen confirmación
humana en el cliente MCP que las ejecute, sea de Tilopay o de un tercero.