Skip to content
Para Integradores

Documentación para Desarrolladores

Todo lo que necesitas para integrar AgenticMCPStores en tu aplicación

Configuración MCP para agentes — 3 pasos

Configura tu agente de IA para explorar productos, crear carritos e iniciar el checkout a través del protocolo MCP.

1

Añade el servidor MCP a tu agente

Añade AgenticMCPStores a la configuración MCP de tu agente. Sustituye {slug} por el slug de la tienda.

{
  "mcpServers": {
    "agenticmcpstores": {
      "url": "https://agenticmcpstores.com/{slug}/mcp",
      "headers": { "X-Agent-Api-Key": "agnt_tu_clave" }
    }
  }
}

¿Sin clave? Usa la demo pública: https://agenticmcpstores.com/demo-store/mcp (sin auth, solo lectura)

2

Busca productos con filtros

Llama a search_products para explorar el catálogo. Filtra por categoría, rango de precio o disponibilidad.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": { "query": "zapatillas running", "max_price": 200, "in_stock_only": true, "limit": 5 }
  }
}

Recomendado: solo proceder al carrito si el trustScore del merchant es ≥ 0.70

3

Crea el carrito y completa el checkout

Usa create_cart para añadir artículos, luego preview_checkout para revisar totales, y complete_checkout para finalizar. Confirma siempre con el usuario antes del checkout.

// Paso 3a — crear carrito
{ "method": "tools/call", "params": { "name": "create_cart", "arguments": { "items": [{ "product_id": "prod_abc123", "quantity": 1 }] } } }

// Paso 3b — vista previa del checkout
{ "method": "tools/call", "params": { "name": "preview_checkout", "arguments": { "cart_id": "cart_xyz789" } } }

// Paso 3c — completar checkout (devuelve URL, no procesa pago)
{ "method": "tools/call", "params": { "name": "complete_checkout", "arguments": { "cart_id": "cart_xyz789" } } }

complete_checkout devuelve una URL — el pago ocurre en la página segura del comercio. Nunca confirmes automáticamente sin aprobación del usuario.

Inicio Rápido

¿Sin API key? Comienza con el endpoint de demo público. ¿Ya tienes clave? Baja a los ejemplos REST autenticados.

Sin API key — prueba ahoraLive

Sin registro ni clave — funciona ya. Usa protocolo MCP (JSON-RPC 2.0). Límite: 20 peticiones/min por IP.

curl https://agenticmcpstores.com/demo-store/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_products",
      "arguments": { "query": "zapatillas running" }
    }
  }'

API REST autenticada (requiere X-Agent-Api-Key)

curl

curl -X POST https://www.agenticmcpstores.com/api/v1/agent/search \
  -H "X-Agent-Api-Key: agnt_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{"query": "zapatillas running", "limit": 5}'

Python

import requests

response = requests.post(
    "https://www.agenticmcpstores.com/api/v1/agent/search",
    headers={"X-Agent-Api-Key": "agnt_tu_clave"},
    json={"query": "zapatillas running", "limit": 5}
)
data = response.json()

JavaScript

const res = await fetch(
  "https://www.agenticmcpstores.com/api/v1/agent/search",
  {
    method: "POST",
    headers: {
      "X-Agent-Api-Key": "agnt_tu_clave",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query: "zapatillas running", limit: 5 })
  }
);
const data = await res.json();

Autenticación

Dos métodos de autenticación según el tipo de integración.

Agent API Key (Recomendado)

X-Agent-Api-Key: agnt_xxx

Para agentes de IA autónomos. Crea una clave una vez — úsala sin sesión.

  • • agent:read — navegación de catálogo
  • • agent:cart — creación de carrito
  • • agent:checkout — inicio de checkout

JWT Bearer

Authorization: Bearer <token>

Para usuarios autenticados. Obtén el token con POST /api/v1/auth/login.

Crear una Agent API Key

# 1. Primero obtén el JWT
curl -X POST https://www.agenticmcpstores.com/api/v1/auth/login \
  -d '{"email":"tu@email.com","password":"..."}' | jq .token

# 2. Crear Agent API Key (el texto plano se devuelve una sola vez — guárdalo de forma segura)
curl -X POST https://www.agenticmcpstores.com/api/v1/agent-keys \
  -H "Authorization: Bearer <jwt>" \
  -d '{"scopes":["agent:read","agent:cart","agent:checkout"]}'

Prueba sin clave — endpoints de Demo y Health

Live

El endpoint MCP de demo-store es público (catálogo de solo lectura, JSON-RPC 2.0). El health check tampoco requiere autenticación.

cURL listo para ejecutar — copia y pega:

curl https://agenticmcpstores.com/demo-store/mcp \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_products","arguments":{"query":"zapatillas"}}}'
  • Endpoint MCP de demo-store (público, sin auth)POST https://agenticmcpstores.com/demo-store/mcp
  • Health check (GET, sin auth)GET https://www.agenticmcpstores.com/api/v1/health

Herramientas MCP

8 herramientas disponibles vía el endpoint MCP y la API REST. Todas requieren autenticación con X-Agent-Api-Key. Las herramientas de solo lectura (search, detail, compare, availability) no requieren confirmación humana — las de escritura siempre la requieren.

HerramientaMétodoRutaAuth. RequeridaConfirmación Humana
search_products

Búsqueda en todos los comercios

POST/api/v1/agent/searchYesNever
get_product_detail

Datos completos de producto con políticas

GET/api/v1/agent/products/{id}YesNever
compare_products

Comparación de productos

POST/api/v1/agent/compareYesNever
check_availability

Stock y precio en tiempo real

GET/api/v1/agent/availability/{id}YesNever
create_cart

Carrito con validación de stock

POST/api/v1/agent/cartYesRequired
complete_checkout

Devuelve URL de checkout — sin procesar pago

POST/api/v1/agent/checkoutYesRequired
get_merchant_profile

Trust score, nivel de verificación, políticas

GET/api/v1/agent/merchants/{slug}YesNever

Webhooks

Suscríbete a eventos en Ajustes > Webhooks. Todos los payloads incluyen el header X-Webhook-Signature.

order.createdorder.status_changedcheckout.abandoned

Ejemplo de payload — order.created

{
  "event": "order.created",
  "timestamp": "2026-03-19T14:32:00Z",
  "orderId": "ord_xyz123",
  "merchantSlug": "zapatillas-pro",
  "totalAmount": 124.99,
  "currency": "EUR",
  "status": "pending"
}

Verificar firma HMAC-SHA256

Python

import hmac, hashlib

def verificar_webhook(body: bytes, firma: str, secreto: str) -> bool:
    esperado = hmac.new(
        secreto.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperado, firma)

Node.js

import crypto from "crypto";

function verificarWebhook(body: Buffer, firma: string, secreto: string): boolean {
  const esperado = crypto
    .createHmac("sha256", secreto)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(esperado),
    Buffer.from(firma)
  );
}

Formato de Respuesta API

Todos los endpoints de agente devuelven un sobre JSON consistente. Los registros de producto están diseñados para pasarse directamente al contexto de un LLM.

{
  "success": true,
  "data": [
    {
      "id": "prod_abc123",
      "name": "Zapatilla Running Ultra Boost",
      "price": 119.99,
      "currency": "EUR",
      "stock_status": "in_stock",
      "merchant": {
        "slug": "zapatillas-pro",
        "trust_score": 0.82,
        "verification_level": "STANDARD"
      },
      "policies": {
        "return_window_days": 30,
        "free_shipping_threshold": 75,
        "shipping_estimate_days": "2-4"
      }
    }
  ],
  "meta": {
    "total": 48,
    "page": 1,
    "limit": 5
  }
}

Documentación API Interactiva

Explora y prueba todos los endpoints con Swagger UI. Prueba solicitudes directamente desde tu navegador.

Abrir Swagger UI
GET /api/docs
HTTP/1.1 200 OK

Swagger UI - Interactive
API Documentation

Preguntas frecuentes para desarrolladores

Ver FAQ completa

¿Qué método de autenticación usa la API de AgenticMCPStores?

La API usa autenticación Bearer con JWT. Obtén el token llamando a POST /api/v1/auth/login, luego inclúyelo en el header Authorization de las siguientes peticiones.

¿Existe un endpoint MCP al que puedan conectarse los agentes de IA?

Sí. Cada tienda tiene un endpoint MCP único en /mcp/{store-slug}. Los agentes compatibles con MCP pueden conectarse para buscar productos, comprobar disponibilidad e iniciar flujos de checkout.

¿Qué límites de tasa aplica la API?

Tier gratuito: 100 solicitudes/min. Pro: 1.000/min. Enterprise: sin límite. Los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset aparecen en cada respuesta.

¿Qué plataformas de e-commerce están soportadas de forma nativa?

Shopify y WooCommerce tienen soporte nativo con sincronización automática. PrestaShop está soportada en beta vía la API del Webservice. Cualquier otra plataforma se integra mediante nuestra REST API enviando catálogo y pedidos manualmente.

¿Cómo obtengo una Agent API Key para agentes de IA autónomos?

Crea una clave con POST /api/v1/agent-keys usando tu JWT. El texto plano se devuelve una sola vez, guárdalo con seguridad. Las claves usan el formato agnt_xxx y admiten permisos: search, checkout y orders.

¿La API devuelve datos de producto estructurados compatibles con LLMs?

Sí. Las respuestas incluyen campos normalizados: nombre, descripción, precio, moneda, estado de stock, política de devoluciones y estimación de envío, listos para pasar al contexto de un LLM.

¿Cómo gestiono webhooks para actualizaciones de estado de pedidos?

Registra una URL en Ajustes > Webhooks. Enviamos POST con JSON para los eventos: order.created, order.status_changed y checkout.abandoned. Verifica los payloads con la firma HMAC-SHA256 del header X-Webhook-Signature.

¿Hay una spec OpenAPI/Swagger que pueda importar?

Sí. La spec OpenAPI 3.0 completa está en /api/openapi.json. Puedes importarla en Postman o Insomnia.

Recursos relacionados

Matriz de protocolos

ACP, AP2, x402, UCP — comparativa completa

Outlook de mercado

Datos y proyecciones del comercio agéntico

Para agentes IA

Trust scores, rate limits y contratos MCP

¿Listo para integrar?

Comienza gratis hoy y conecta tu tienda a agentes de IA.

Comenzar
Documentación para Integradores | AgenticMCPStores