Guía de uso para el comercio

Documentación

Con el panel te das de alta solo, creás una o varias extensiones, cargás tus credenciales de Mercado Pago y empezás a cobrar. El recorrido tiene tres etapas: preparar tu cuenta de Mercado Pago, configurar todo en el panel, y llamar a la API desde tu extensión.

Importante: cuando crees tu cuenta en el panel, usá el mismo email que el de tu cuenta de Mercado Pago. Así ambas cuentas quedan vinculadas y se evitan confusiones al cobrar y en el soporte.

Nota: el panel está en https://foundersvault.xyz/panel. La base del servicio es https://foundersvault.xyz; en los ejemplos la abreviamos como BASE.

1 · Preparar tu cuenta de Mercado Pago

1.1 Tu cuenta (mercadopago.com.ar)

Si no tenés cuenta, creá una en mercadopago.com.ar. Anotá el email: lo vas a reusar en el panel.
Completá tu perfil y la validación de identidad. Sin esto, Mercado Pago bloquea el cobro real de pagos.

1.2 La integración (mercadopago.com.ar/developers)

Entrá al panel de desarrolladores con esa misma cuenta y creá una aplicación de Pagos online.
Si te pide activar la aplicación para producción, completá los requisitos.
Abrí Credenciales de producción y copiá el Access Token (empieza con APP_USR-...). Ese es el dato que vas a pegar en el panel.

Nota: el Access Token es secreto, tratalo como una contraseña. Lo cargás una sola vez en el panel y queda guardado de forma protegida; el panel nunca lo vuelve a mostrar.

2 · Configurar en el panel

2.1 Crear tu cuenta

Abrí foundersvault.xyz/panel, elegí Crear cuenta, e ingresá el mismo email de tu cuenta de Mercado Pago y una contraseña de al menos 8 caracteres.

2.2 Crear una extensión

Una misma cuenta puede tener varias extensiones (por ejemplo, un plugin para cada producto). En Tus extensiones, escribí un nombre en Crear una extensión y confirmá. Después tocá Abrir para entrar a su panel.

2.3 Configurar los cobros (Mercado Pago)

Dentro de la extensión, en la tarjeta Cobros con Mercado Pago, elegí el modo:

Modo	Qué tenés que hacer
Manual	(por defecto) Pegás tu Access Token de producción (`APP_USR-...`) y guardás. El dinero entra directo a tu cuenta de Mercado Pago.
Split (OAuth)	El cobro se divide automáticamente entre vos y la plataforma. Requiere que la plataforma lo habilite; cuando está habilitado, aparece Conectar con Mercado Pago y autorizás con un clic.

Nota: el campo del token está enmascarado y nunca se muestra el valor guardado. Si lo renovás en Mercado Pago, lo volvés a pegar; si dejás el campo vacío, se conserva el que tenías.

2.4 Configurar precios, freemium y planes

En la tarjeta Configuración definís: moneda y precio por crédito; créditos y días gratis al registrarse; funciones base (separadas por coma); URL de retorno tras pagar; y los planes de créditos y de tiempo (los de tiempo pueden ser por única vez o recurrentes). Tocá Guardar configuración.

2.5 Copiar tus credenciales

En Credenciales de la extensión vas a ver tu Clave de API (phk_...), con la que tu servidor llama a la API (es secreta), y tu URL de webhook.

2.6 Suscripciones: webhook en Mercado Pago

Si usás cobros recurrentes, configurá en tu aplicación de Mercado Pago (Webhooks / Notificaciones) la URL de webhook que te dio el panel, con los eventos Pagos y Suscripciones. Para los pagos de una sola vez no hace falta: ya avisan solos.

3 · Usar la API

Todas las llamadas van contra BASE y, salvo el health, llevan tu Clave de API en el encabezado X-Api-Key: phk_....

3.1 Probar que el servicio responde

curl BASE/health

Respuesta: { "status": "ok", "utc": "..." }.

3.2 Los tres modos: créditos, tiempo o mixto

Modo	Cómo funciona
Créditos	El usuario tiene un saldo y gasta créditos por acción. Recibe créditos gratis al registrarse y compra más cuando se le acaban.
Tiempo	El usuario tiene acceso hasta una fecha (un abono). Recibe días gratis y compra paquetes de días, semanas o meses, por única vez o con renovación automática.
Mixto	Combina ambos: saldo de créditos y acceso por tiempo a la vez. Tu extensión decide, por acción, si exige créditos, acceso vigente, o ambos.

3.3 Registrar un usuario

curl -X POST BASE/users -H "X-Api-Key: phk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "usuario-123", "email": "usuario@correo.com" }'

3.4 Antes de una acción paga: consumir o verificar

Créditos (200 sigue; 402 sin saldo; 403 función no habilitada):

curl -X POST BASE/users/usuario-123/consume -H "X-Api-Key: phk_TU_CLAVE" \
  -H "Content-Type: application/json" -d '{ "amount": 5, "feature": "exportar" }'

Tiempo (mirá el campo hasAccess):

curl BASE/users/usuario-123/access -H "X-Api-Key: phk_TU_CLAVE"

3.5 Cobrar: obtener el checkout y redirigir

Pedís el enlace de pago y redirigís el navegador del usuario a ese enlace.

# Comprar creditos
curl -X POST BASE/users/usuario-123/topup -H "X-Api-Key: phk_TU_CLAVE" \
  -H "Content-Type: application/json" -d '{ "credits": 50 }'

# Comprar / suscribir tiempo
curl -X POST BASE/users/usuario-123/access/subscribe -H "X-Api-Key: phk_TU_CLAVE" \
  -H "Content-Type: application/json" -d '{ "planCode": "mensual" }'

Ambas respuestas traen un checkoutUrl: mandá ahí al usuario.

Nota: tras pagar, Mercado Pago lo devuelve a tu URL de retorno. No consultás nada a Mercado Pago: nosotros acreditamos los créditos o extendemos el acceso por detrás. Te alcanza con volver a leer el usuario.

3.6 Leer el estado del usuario

curl BASE/users/usuario-123 -H "X-Api-Key: phk_TU_CLAVE"

Devuelve, entre otros: balance, features, hasAccess y accessExpiresAt.

3.7 El flujo típico

El usuario se registra → POST /users.
Antes de una acción paga → consume (créditos) o access (tiempo).
Si falta saldo o acceso → topup o access/subscribe, y redirigís al checkoutUrl.
El usuario paga y vuelve a tu URL de retorno.
Volvés a leer el usuario: el saldo o el acceso ya están actualizados.

4 · Integración con IA (MCP)

Tu extensión expone un endpoint MCP (Model Context Protocol), el estándar para conectar asistentes de IA a herramientas. Con esto, un modelo puede consultar y operar tu sistema (ver usuarios, créditos, accesos, generar checkouts) a través de lenguaje natural.

Endpoint: POST BASE/mcp
Autenticación: tu Clave de API, en el encabezado X-Api-Key: phk_...
Protocolo: JSON-RPC 2.0. El cliente descubre las herramientas disponibles llamando a tools/list.

Para conectarlo desde un cliente MCP (por ejemplo, un asistente compatible), agregás un servidor remoto con la URL BASE/mcp y el encabezado X-Api-Key con tu clave. Desde la API de Anthropic, se conecta como servidor MCP por URL con tu clave como token de autorización.

Nota: la Clave de API da acceso completo a tu extensión. Conectá el MCP solo a asistentes en los que confíes, y preferí exponer únicamente herramientas de lectura si no necesitás que el modelo ejecute cobros o cambie configuración.