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

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

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.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
  }
}

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

Los entornos de beta pública usan límites de uso razonable e incluyen los headers estándar X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. El mayor throughput para despliegues comerciales se gestiona mediante planificación directa, no con tiers públicos autoservicio todavía.

¿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

¿Listo para integrar?

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

Comenzar