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 trustScore del merchant es ≥ 0.70

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.

• 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://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)
curl -X POST https://trusteed.xyz/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://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, ELITE ≥0.95 / VERIFIED ≥0.85 / STANDARD ≥0.70GET 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)	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 (público)	POST	MCP tool	No	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

Cada petición al MCP Gateway descuenta de dos cubos independientes: uno por tier y otro por herramienta. Ambos deben tener capacidad para que la solicitud prospere.

MCP Gateway — límites por tier

Plan	Req / min
FREE	30
STARTER	30
GROWTH	200
PRO	1.000
ENTERPRISE	5.000

Límites por herramienta (adicionales al límite de tier)

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

Endpoints REST públicos (trust score, directorio): 30 req/min por IP.

Headers de respuesta

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1714000800

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 tier (FREE/STARTER 30 req/min, GROWTH 200, PRO 1.000, ENTERPRISE 5.000) y un cubo por herramienta (p.ej. complete_checkout limitado a 10/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 el detalle completo.

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

Shopify, WooCommerce y Odoo 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.

¿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. Los merchants con estado VERIFIED han completado verificaciones KYB y reciben trust scores más altos. Los agentes solo deben proceder al checkout con merchants con score ≥ 0.70.

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