Para Integradores

Documentación para Desarrolladores

Todo lo que necesitas para integrar Trusteed 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.

Añade el servidor MCP a tu agente

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

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

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

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 nivel de confianza del merchant está por encima de tu umbral aceptable

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://trusteed.xyz/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://trusteed.xyz/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://trusteed.xyz/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://trusteed.xyz/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.

• search — búsqueda en catálogo
• compare — comparación de productos
• cart — creación de carrito
• checkout — inicio de checkout
• checkout:delegate — checkout delegado
• orders:read — historial de pedidos
• merchants:read — perfiles de comercio
• protocols:discover — descubrimiento de protocolos

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://trusteed.xyz/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)
#    "name" es obligatorio; los permisos fuera de la lista válida dan 400
curl -X POST https://trusteed.xyz/api/v1/agent-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"mi-agente","scopes":["search","compare","cart","merchants:read"]}'

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://trusteed.xyz/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://trusteed.xyz/demo-store/mcp
Health check (GET, sin auth)GET https://trusteed.xyz/api/v1/health
Metodología de trust score (GET, sin auth) — 12 componentes, pesos, verificado vs declarado, y las bandas de puntuación ELITE / VERIFIED / STANDARD / CAUTION / RESTRICTED (bandas, no niveles de verificación de identidad)GET https://trusteed.xyz/api/v1/trust/methodology

Auth & Compliance

Autenticación y cumplimiento normativo de nivel enterprise, verificables y legibles por máquina.

OAuth 2.1 + PKCE (spec MCP 2025-11-25)

Servidor de autorización: Auth0
Discovery: /.well-known/oauth-authorization-server(RFC 8414)

Metadatos de recurso protegido

RFC 9728: declara scopes protegidos y el token endpoint
Legible por máquina: /.well-known/oauth-protected-resource

EU AI Act Art. 50 — Headers de transparencia

X-AI-Agent-Initiated: true en todas las peticiones originadas por agente
X-Human-Confirmation-Required: true en acciones que requieren confirmación humana

Conforme a la spec MCP 2025-11-25

Server card: /.well-known/mcp.json

Herramientas MCP

Hay más de 40 herramientas disponibles vía el endpoint MCP, incluyendo un subconjunto público de discovery que funciona sin autenticación. Las de solo lectura no requieren confirmación humana y las de escritura siempre la requieren.

Herramienta	Método	Ruta	Auth. Requerida	Confirmación Humana
`search_products` Buscar catálogo con filtros (público)	POST	MCP tool	No	Never
`get_product_details` Datos completos de producto (público)	POST	MCP tool	No	Never
`browse_categories` Navegar categorías (público)	POST	MCP tool	No	Never
`compare_products` Comparación de productos (público)	POST	MCP tool	No	Never
`nlweb_ask` Búsqueda semántica IA con NLWeb (público; sólo en tiendas con NLWeb activo)	POST	MCP tool	No	Never
`get_merchant_profile` Trust score, verificación de identidad, políticas (público)	POST	MCP tool	No	Never
`create_cart` Carrito con validación de stock	POST	MCP tool	Yes	Required
`get_shipping_rates` Calcular costes de envío	POST	MCP tool	Yes	Never
`preview_checkout` Resumen del pedido antes del pago — 401 sin token, nunca pide confirmación humana	POST	MCP tool	Yes	Never
`complete_checkout` Devuelve URL de checkout — sin procesar pago	POST	MCP tool	Yes	Required
`onx_get_orders` Consultar pedidos cumplidos (post-checkout)	POST	MCP tool	Yes	Never
`onx_create_return` Iniciar solicitud de devolución	POST	MCP tool	Yes	Required

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 (formato Stripe con protección anti-replay)

Python

import hmac, hashlib, time

# Header: X-Webhook-Signature: t=<unix_ts>,v1=<hex_sig>
# v1 = HMAC_SHA256(secreto, "<unix_ts>.<body>")
def verificar_webhook(body: bytes, header: str, secreto: str, tolerancia: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    ts, v1 = parts.get("t"), parts.get("v1")
    if not ts or not v1: return False
    if abs(int(time.time()) - int(ts)) > tolerancia: return False  # anti-replay
    firmado = f"{ts}.".encode() + body
    esperado = hmac.new(secreto.encode(), firmado, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, v1)

Node.js

import crypto from "crypto";

// Header: X-Webhook-Signature: t=<unix_ts>,v1=<hex_sig>
// v1 = HMAC_SHA256(secreto, "<unix_ts>.<body>")
function verificarWebhook(body: string, header: string, secreto: string, tolSeg = 300): boolean {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=", 2)));
  const ts = Number(parts.t);
  if (!ts || !parts.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > tolSeg) return false; // anti-replay
  const esperado = crypto.createHmac("sha256", secreto).update(`${ts}.${body}`).digest("hex");
  const a = Buffer.from(parts.v1, "hex");
  const b = Buffer.from(esperado, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

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.91,
        "verification_level": "STANDARD"
      },
      "policies": {
        "return_window_days": 30,
        "free_shipping_threshold": 75,
        "shipping_estimate_days": "2-4"
      }
    }
  ],
  "meta": {
    "total": 48,
    "page": 1,
    "limit": 5
  }
}

Límites de Tasa

Una petición atraviesa hasta cuatro límites independientes, cada uno aplicado por una capa distinta. Todos deben tener capacidad para que la llamada prospere, y el que muerde primero no suele ser el que uno tenía en mente.

MCP Gateway — cubo por clave

Plan	Configurado	En vigor hoy
STARTER (alias: FREE)	30 / min	30 / min
GROWTH	200 / min	30 / min
PRO	1000 / min	30 / min
ENTERPRISE	5000 / min	30 / min

Las claves MCP de tienda no llevan información de tier, así que el gateway aplica el cubo STARTER (30 req/min) a todas por igual, sea cual sea el plan. Dimensiona tu backoff contra ese número, no contra la fila de tu plan. La diferenciación por tier sí es real en la API REST agéntica de más abajo.

Límites por herramienta (además del cubo por clave)

Herramienta	Límite
`search_products`	20 / min
`search_products_enriched`	15 / min
`complete_checkout`	10 / min
`create_cart`	20 / min
`ucp_create_checkout`	20 / min

Las otras tres capas

Global, por IP o usuario autenticado: 500 peticiones por 15 minutos — ojo a la ventana, no es por minuto. El tráfico anónimo choca primero con este.
Demo store (/demo-store/mcp, sin clave): 20 req/min por IP.
API REST agéntica (/api/v1/agent/*, X-Agent-Api-Key): por clave y minuto, según el tier real — STARTER 100, GROWTH 500, PRO 2000, ENTERPRISE 10.000.
Endpoints REST públicos (trust score, directorio): 30 req/min por IP.

Headers de respuesta

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1714000800
Retry-After: 60  // sólo en 429

Retry logic para agentes

1Al recibir 429, lee X-RateLimit-Reset (Unix timestamp en segundos).
2Espera hasta ese timestamp antes de reintentar.
3Usa backoff exponencial: 1 s → 2 s → 4 s → 8 s.
4No reintentas más de 4 veces por cadena de llamada.

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 Trusteed?

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 /{store-slug}/mcp. 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?

El MCP Gateway aplica dos límites independientes: un cubo por clave y otro por herramienta (p.ej. complete_checkout limitado a 10/min). El cubo por clave está configurado por tier (30/200/1000/5000 req/min), pero las claves MCP de tienda no llevan tier, así que hoy todas reciben el cubo STARTER de 30 req/min — dimensiona tu backoff contra ese número. La diferenciación por tier aplica a la API REST agéntica (100/500/2000/10000 req/min). Ante un 429, lee X-RateLimit-Reset y espera hasta ese timestamp Unix antes de reintentar. Consulta la sección Límites de Tasa para las cuatro capas.

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

Cinco plataformas tienen integración construida: Shopify, WooCommerce, PrestaShop y Magento están en beta guiada —te acompañamos en el alta en vez de dejarte solo— y Odoo está en sandbox, en validación con comercios piloto. Cualquier otra plataforma se integra mediante nuestra REST API enviando catálogo y pedidos. El estado vigente de cada una se publica en /es/integrations y en .well-known/agent-commerce.json.

¿Qué es la verificación de identidad del comercio y cómo afecta al trust score?

La verificación de identidad del comercio es el proceso por el que confirmamos la identidad legal de una empresa. Hay cinco niveles — UNVERIFIED, BASIC (control de correo y dominio), STANDARD (revisión del negocio), PREMIUM (revisión más historial operativo) y QUALIFIED (contrastado con registros mercantiles oficiales vía un QTSP eIDAS). No los confundas con las bandas del trust score (ELITE, VERIFIED, STANDARD, CAUTION, RESTRICTED), que miden otra cosa. Los agentes solo deben proceder al checkout con comercios por encima de su umbral aceptable en ambos ejes.

¿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. Los permisos válidos son search, compare, cart, checkout, checkout:delegate, orders:read, merchants:read, protocols:discover; una clave nueva recibe search, compare, cart, merchants:read salvo que pidas más. Cualquier otro valor se rechaza con un 400.

¿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/v1/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

SDK Quickstarts

Conecta desde OpenAI Agents, Claude o Vercel AI SDK en minutos

¿Listo para integrar?

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

Comenzar