Vendé con Mercado Pago en tu sitio de Framer

# Mercado Framer: contexto para agentes

Vas a ayudar a una persona que vende (o quiere vender) en su sitio de Framer con **Mercado Framer**. Tomá este documento como fuente de verdad. Si algo no está acá, decilo en lugar de suponer y remitite a la documentación: https://mercadoframer.com/docs

## Qué es
Mercado Framer permite cobrar con Mercado Pago Checkout Pro en un sitio de Framer, sin código. Tiene tres partes:
1. **Panel web** (https://mercadoframer.com/dashboard): se crean y editan los productos, y se ven pedidos, clientes y ajustes. Es la fuente de verdad del catálogo.
2. **Plugin de Framer** (Mercado Framer): conecta la cuenta de Mercado Pago, crea y sincroniza la colección del CMS «Productos» e inserta los componentes de la tienda en el proyecto.
3. **Componentes de la tienda**: componentes de código (archivos «MP …») que corren en el sitio publicado: botones de compra, carrito, precio, galería, etc.

El dinero de cada venta va directo a la cuenta de Mercado Pago del vendedor. Cada proyecto de Framer conectado es una tienda.

## Reglas clave
- Los productos se crean y editan **sólo en el panel**, nunca en el CMS de Framer.
- «Productos» es una colección administrada por el plugin: refleja el panel. Cualquier edición manual (ítems o campos nuevos) se pisa en el próximo Sync.
- **Precio y stock se validan en vivo en el checkout.** El servidor recalcula el total con los precios del panel y verifica stock y estado. Los valores del CMS son para mostrar y diseñar: una venta nunca depende de sincronizar.
- Después de cambiar productos en el panel hay que tocar **Sync** en la colección (o «Sincronizar ahora» en el plugin) y **publicar** el sitio para que el CMS publicado se actualice.
- Conectar Mercado Pago lo hace siempre la persona, desde el plugin, con la autorización oficial de Mercado Pago. Nunca pidas ni manejes contraseñas, tokens, claves ni datos de tarjeta.
- Los archivos de los productos digitales son privados: nunca van al CMS ni a una página.

## Flujo
Panel (productos) → Sync → colección «Productos» en el CMS → páginas de Framer con los componentes → el comprador paga en Mercado Pago → vuelve a la página de gracias → con el pago aprobado se descuenta el stock, se envían los emails y se habilitan las descargas.

## El panel
- Entrar: desde el plugin (pestaña Inicio o Productos → «Gestionar productos») o en https://mercadoframer.com/login con «Entrar con Mercado Pago» (la misma cuenta del plugin; muestra todas sus tiendas y la sesión dura 30 días) o con un link por email.
- Campos de un producto:
  - Nombre (obligatorio).
  - Descripción: texto plano; párrafos separados por una línea en blanco.
  - Imágenes: la primera es la principal. JPG, PNG, WebP o GIF; hasta 20.
  - Precio y Precio anterior: si el anterior es mayor, se muestra tachado con el % de descuento.
  - Stock: con «Controlar stock» se descuenta en cada venta aprobada; sin control, no hay límite.
  - Estado: Activo (visible y comprable) o Borrador (oculto y no comprable).
  - Tipo: Físico (peso en g y medidas «alto x ancho x largo» en cm, para Mercado Envíos) o Digital (archivo de hasta 50 MB).
  - Slug: la URL del producto termina en /slug; es único en la tienda.
- Archivar saca el producto de la tienda, y de la colección en el próximo Sync. Los pedidos anteriores lo conservan.
- Secciones: Resumen (30 días, más vendidos, productos con 5 unidades o menos), Pedidos (todos los checkouts: Aprobado, Pendiente, En proceso, Rechazado, Cancelado, Reembolsado), Clientes (compradores con pago aprobado) y Ajustes (moneda ARS, BRL, MXN, CLP, COP, PEN o UYU; entrega digital por email y/o en la página de gracias, al menos una; Mercado Envíos; comisión de la plataforma).

## La colección «Productos»
- La crea el plugin: pestaña Productos → «Crear colección y sincronizar» (si el nombre está tomado, se llama «Productos 2»). Después se actualiza con el botón **Sync** de la colección en el CMS.
- Un ítem por producto no archivado. Los borradores llegan como borradores del CMS (no se publican). El slug del ítem es el slug del producto.
- Las imágenes subidas al panel se pasan a Framer al sincronizar.
- IDs de campo (estables; los nombres visibles cambian con el idioma del plugin):

| id | nombre visible | tipo | contenido |
|---|---|---|---|
| `title` | Nombre | texto | nombre del producto |
| `price` | Precio | número | precio actual |
| `compareAtPrice` | Precio anterior | número | 0 si no hay |
| `discount` | Descuento % | número | % redondeado; 0 si no hay |
| `description` | Descripción | texto con formato | párrafos |
| `image` | Imagen | imagen | imagen principal |
| `gallery` | Galería | lista de imágenes | todas, en orden |
| `stock` | Stock | número | unidades; 0 si no controla stock |
| `inStock` | Hay stock | sí/no | sí si hay unidades o no controla stock |
| `tracksStock` | Controla stock | sí/no | stock limitado |
| `isDigital` | Digital | sí/no | producto digital |
| `productId` | ID de producto | texto | ID público del producto |
| `weight` | Peso (g) | número | 0 si no aplica |
| `dimensions` | Medidas (cm) | texto | «alto x ancho x largo» |

## Componentes de la tienda
Se agregan desde el plugin, pestaña **Componentes**: de a uno (secciones Producto, Carrito y Pago → «Agregar») o en bloque desde **Páginas** («Detalle de producto», «Caja de compra» y «Página de gracias», que se arman en la página abierta). Cada uno crea en el proyecto un archivo de código ya configurado con la tienda y con el estilo de la pestaña **Estilo**. No edites el código de esos archivos ni los reemplaces por componentes propios; para actualizarlos, en Componentes está el botón ↻ de cada uno y «Actualizar todo».

Comportamiento común:
- En una página de detalle, los componentes de producto detectan el producto por el **último tramo de la URL** (el slug) y leen precio, stock e imágenes en vivo. Por eso van en la página de detalle de «Productos» (por ejemplo /tienda/:slug).
- Propiedades de precio en 0 e imágenes vacías = detección automática en vivo. Vinculalas a campos del CMS sólo en listados (Collection List), donde la URL no identifica a un producto.
- En el lienzo muestran un producto real de la tienda (o uno de ejemplo). Carrito, resultado de pago, indicador de stock y selector de variante tienen una propiedad Preview (sólo lienzo) para diseñar cada estado.
- Todos tienen la propiedad Language (English / Español).

| Archivo | Qué hace | Propiedades clave |
|---|---|---|
| MP Add to Cart / MP Buy Now | Botón de compra (el mismo componente con otra Action). Agrega al carrito sin pasar el stock, o va directo a Mercado Pago pidiendo el email del comprador. Muestra «Sin stock» o, si no encuentra el producto, «No disponible». | Action (Add to cart / Buy now / Both), Return page, Email (On click / Always), Quantity, Show stock, Low stock at, Product ID + Title/Price/Image (vacío = por URL), Cart label, Buy label, apariencia |
| MP Product Gallery | Imagen principal, miniaturas y pantalla completa (teclado, deslizar, Esc) | Image 1–4 (vacías = imágenes del producto), Fit, Ratio, Thumbnails, Lightbox, apariencia |
| MP Price | Precio con el formato de la moneda de la tienda; no muestra nada si no encuentra el producto | Price (0 = en vivo), Currency (vacío = la de la tienda, también con Price vinculado), Show ($ 1.990 / ARS 1.990 / número), Language (formato), Color, Font |
| MP Compare-at Price | Precio anterior tachado; se oculta si no hay descuento | Compare at (0 = en vivo), Currency, Show, Strikethrough, Hide if empty |
| MP Discount Badge | Píldora «{n}% OFF»; se oculta en 0% | Percent (0 = automático; en listados ← `discount`), Price, Compare at, Label, Hide if 0%, Style (Solid / Soft) |
| MP Stock Badge | «En stock», «Últimas N unidades» o «Sin stock», en vivo | Low stock at, Untracked (In stock / Hide), Style (Dot / Pill), textos por estado, colores |
| MP Variant Selector | Desplegable o píldoras de opciones (talle, color). La opción viaja al carrito y al pedido como texto; no cambia precio ni stock | Options (separadas por comas; por defecto S, M, L), Style (Dropdown / Pills), Label, Placeholder, apariencia |
| MP Quantity Selector | − / + limitado al stock | Style (Split / Joined), apariencia |
| MP Cart | Botón con la cantidad que abre el carrito (productos, subtotal, email y «Pagar con Mercado Pago»). El carrito vive en el navegador del comprador | Trigger (Floating = fijo en una esquina / Inline = ícono, por ejemplo en la navbar), Opens as (Drawer / Popover), Side, Return page, Open on add, Hide if empty, apariencia |
| MP Checkout Result | En la página de gracias: lee el pedido de la URL y muestra el resultado con número de pedido y total (aprobado, en proceso, no completado, reembolsado, no encontrado). Si se aprobó vacía el carrito y muestra descargas (si están activadas); si no, los productos siguen en el carrito; en proceso se actualiza sola | Store link (botón «Volver a la tienda»), Link label, Align, apariencia |

Notas:
- Cantidad y variante se conectan solas con el botón de la misma página.
- Return page (botones y carrito): la ruta de la página de gracias, por ejemplo /pedido. Vacía, el comprador vuelve a la misma página. Mercado Pago agrega el pedido a la URL al volver.
- La colección no tiene campo de variantes: las opciones del Variant Selector se escriben en la propiedad y son las mismas para todos los productos de esa página. Sin variantes, no lo uses.
- Botón de compra en un listado: vinculá Product ID ← `productId` y Title, Price, Image ← `title`, `price`, `image` para que el carrito los muestre. El checkout cobra siempre el precio del panel.
- Currency del carrito sólo aplica a ítems viejos: los nuevos usan la moneda de la tienda.

## Estructura de una tienda
1. **Listado** (/tienda): Collection List de «Productos». Por tarjeta: `image`, `title`, precio (`price`), badge (MP Discount Badge con Percent ← `discount`), etiqueta «Sin stock» visible cuando `inStock` es falso y link a la página de detalle del ítem (opcional: MP Add to Cart con Product ID ← `productId`).
2. **Detalle** (/tienda/:slug, página de detalle CMS de «Productos»): MP Product Gallery, `title`, MP Price, MP Compare-at Price, MP Discount Badge, MP Stock Badge, MP Variant Selector (opcional), MP Quantity Selector, MP Add to Cart y/o MP Buy Now, y `description` en un texto con formato. Valores automáticos en 0 o vacíos.
3. **Gracias** (/pedido): MP Checkout Result con Store link = /tienda.
4. **Carrito**: MP Cart una sola vez en un elemento compartido (Trigger Inline dentro de la navbar, o Floating en un footer o layout). El bloque «Detalle de producto» de Componentes → Páginas también agrega uno: dejá uno solo.
Return page de botones y carrito → /pedido.

## Productos digitales
Archivo privado (hasta 50 MB) subido en el panel. Con el pago aprobado, el comprador recibe links de descarga por email y/o en la página de gracias (Ajustes → Entrega digital). Los links son por pedido y vencen (los del email, a los 30 días). No llevan envío.

## Envíos (Mercado Envíos)
Opcional: Ajustes → Envíos, y Mercado Envíos activado en la cuenta de Mercado Pago. Cada producto físico necesita peso (g) y medidas (cm, por ejemplo 10x20x30); si faltan, se usan 500 g y 10 × 10 × 10 cm. Mercado Pago pide la dirección y cotiza en el checkout. Si no acepta el envío para esa cuenta, el checkout sigue sin envío.

## Stock
Se descuenta cuando el pago se aprueba. Al iniciar el checkout se verifica que alcance. Las ventas actualizan el panel al instante; `stock` e `inStock` del CMS cambian en el próximo Sync (la página de detalle muestra siempre el valor en vivo).

## Errores comunes
- Componentes de producto fuera de la página de detalle: no encuentran el producto.
- URL de detalle con un slug viejo (se cambió en el panel y no se sincronizó).
- Price vinculado en la página de detalle: muestra el valor del CMS en lugar del valor en vivo. Dejalo en 0.
- Return page vacía: el comprador vuelve a la página del producto y no ve el resultado.
- Abrir /pedido directo: muestra «No encontramos tu pedido». Es normal sin pedido en la URL.
- Sincronizar sin publicar: el sitio sigue mostrando el CMS anterior.
- Editar «Productos» a mano o agregarle campos: se pisa en el Sync.
- Crear componentes de pago propios: usá siempre los del plugin.

## Diagnóstico
- Botón en «No disponible» o precio vacío: ¿página de detalle de «Productos»? ¿producto Activo? ¿slug actual? ¿Sync y publicación hechos?
- Precio viejo en el sitio: Sync y publicar. El checkout ya cobra el precio nuevo.
- Imágenes que no suben en el Sync: repetir el Sync.
- Pago «en proceso»: esperar la confirmación de Mercado Pago; el pedido se actualiza solo.
- No se pueden insertar componentes: el plan o modo de Framer no permite componentes de código, o falta permiso de edición.
- Email no recibido: revisar spam y Ajustes → Entrega digital.

## MCP de Mercado Framer (opcional)
Si la persona conectó el MCP de Mercado Framer (clave creada en el panel → Ajustes → Agentes de IA), tenés herramientas para su tienda: `get_store`, `list_products`, `get_product`, `create_product`, `update_product`, `bulk_update_products`, `duplicate_product`, `archive_products` y, si la clave lo permite, `list_orders`, `get_order`, `list_customers`, `sales_overview`. Creá productos como borrador, pedí confirmación antes de activar o archivar, y recordá que después hay que tocar Sync en «Productos» y publicar. Los archivos digitales se suben sólo desde el panel.

## Qué no hacer
- No pidas ni manejes credenciales, tokens, contraseñas ni datos de pago.
- No inventes propiedades, campos ni pasos que no estén acá.
- No publiques el sitio sin la confirmación de la persona.