# Catálogo

> Herramientas del MCP para leer el catálogo de productos y servicios del comercio.

- kind: mcp-tool
- status: stable
- access: read
- last_verified: 2026-10-07
- url: https://tilopay.com/developers/agentes/mcp/catalogo

## Qué cubre [#que-cubre]

Sólo lectura: lista los productos o servicios que el comercio ya tiene creados en enlaces de pago y devuelve el detalle de uno.

## Herramientas [#herramientas]

### Listar catálogo de productos o servicios [#tilopay-catalog-list-items]

- `tilopay_catalog_list_items`
- Acceso: Sólo lectura
- Operación del API: `GET /api/v1/getLinkPaymentList/{api_key}/{limit}` — https://tilopay.com/developers/api/links-de-pago/payment-item-list

Lista los productos o servicios del catálogo de Tilopay (título, precio y enlace corto). Permite buscar por nombre o descripción (sin importar acentos ni mayúsculas). El listado de Tilopay puede tardar unos minutos en reflejar cambios hechos en el panel; lo creado desde aquí aparece de inmediato y la respuesta de tilopay_catalog_create_item ya trae el ítem nuevo. Usa refresh=true para forzar lectura fresca.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `limit` | integer | — | Máximo de ítems (por defecto 50) |
| `search` | string | — | Texto a buscar en el nombre del producto |
| `page` | integer | — | Página (por defecto 1) |
| `refresh` | boolean | — | true para ignorar la memoria corta y leer de nuevo |
| `include_qr` | boolean | — | Incluir el QR completo en base64 de cada ítem (por defecto false; el listado devuelve solo el enlace y has_qr) |

**Devuelve**

`{ result }`

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

### Detalle de un ítem del catálogo [#tilopay-catalog-get-item]

- `tilopay_catalog_get_item`
- Acceso: Sólo lectura
- Operación del API: `GET /api/v1/getLinkPaymentById/{link_payment_id}/{api_key}` — https://tilopay.com/developers/api/links-de-pago/payment-by-id

Obtiene el detalle de un producto o servicio del catálogo de Tilopay por su ID. El QR en base64 solo con include_qr=true.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `itemId` | string | sí | ID del ítem del catálogo |
| `include_qr` | boolean | — | Incluir el QR en base64 (por defecto false; úsalo solo si el comercio pide el QR) |

**Devuelve**

`{ result }`

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

### Agregar producto o servicio al catálogo [#tilopay-catalog-create-item]

- `tilopay_catalog_create_item`
- Acceso: Escritura
- Operación del API: `POST /api/v1/createLinkPayment` — https://tilopay.com/developers/api/links-de-pago/create-link-payment

Crea un producto o servicio en el catálogo de Tilopay con su precio y devuelve el enlace corto de pago y el QR como imagen. Si el comercio envió una foto por WhatsApp en los últimos 10 minutos, la usa como imagen del producto.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | string | sí | Nombre del producto o servicio (título del enlace) |
| `amount` | number | sí | Precio |
| `currency` | string | — | Moneda, ej. CRC o USD (por defecto la del comercio) |
| `description` | string | — | Descripción corta |
| `media_ref` | string | — | Referencia exacta de la imagen recibida por WhatsApp, si la conoce |
| `use_last_image` | boolean | — | false para crear el producto sin foto aunque haya una imagen reciente |

**Devuelve**

`{ result, linkId, url }`

result = respuesta del API tal cual; linkId = id del enlace de pago que representa el producto; url = enlace de cobro del producto.

### Editar un producto del catálogo [#tilopay-catalog-update-item]

- `tilopay_catalog_update_item`
- Acceso: Escritura
- Operación del API: `POST /api/v1/createLinkPayment` — https://tilopay.com/developers/api/links-de-pago/create-link-payment

Edita un producto del catálogo de Tilopay (nombre, precio, moneda, descripción o foto) sin cambiar su enlace de pago.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `itemId` | string | sí | ID del ítem del catálogo |
| `name` | string | — | Nuevo nombre |
| `amount` | number | — | Nuevo precio |
| `currency` | string | — | Nueva moneda |
| `description` | string | — | Nueva descripción corta |
| `media_ref` | string | — | Referencia exacta de la imagen recibida por WhatsApp, si la conoce |
| `use_last_image` | boolean | — | false para no cambiar la foto aunque haya una imagen reciente |

**Devuelve**

`{ result, linkId, url, replaced }`

El API no permite editar un enlace: la herramienta crea el producto nuevo y borra el anterior. replaced = id del producto que se reemplazó; linkId y url = los del producto nuevo.

### Borrar un producto del catálogo [#tilopay-catalog-delete-item]

- `tilopay_catalog_delete_item`
- Acceso: Sensible
- Operación del API: `POST /api/v1/deleteLinkPayment` — https://tilopay.com/developers/api/links-de-pago/delete-link-payment

Borra un producto del catálogo de Tilopay. El enlace de pago del producto deja de funcionar. Requiere código de confirmación enviado al correo.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `itemId` | string | sí | ID del ítem del catálogo |
| `confirmation_code` | string | — | Código de 6 dígitos enviado al correo del comercio |

**Devuelve**

`{ result }`

result = respuesta del API al borrar el enlace de pago que representa el producto.

### Sincronizar catálogo con redes y buscadores [#tilopay-catalog-feed]

- `tilopay_catalog_feed`
- Acceso: Escritura

Entrega el enlace del catálogo sincronizado y los pasos para conectarlo en Facebook/Instagram, Google Shopping, TikTok o Pinterest (un canal a la vez, el que pida el comercio). Con send_email=true lo manda al correo del comercio.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `platform` | string (facebook | google | tiktok | pinterest) | — | Canal pedido. Si el comercio no dijo cuál, NO llames: pregúntale primero. |
| `send_email` | boolean | — | true si pidió que se lo mandes por correo |

**Devuelve**