De 0 a agent-ready: guía para desarrolladores de Trusteed

Esta guía te lleva paso a paso por cada etapa de conectar tu tienda e-commerce con agentes IA via Trusteed. Al final, tendrás un endpoint MCP en vivo, un catálogo de productos sincronizado, herramientas listas para agentes (search_products, create_cart, complete_checkout), un trust score visible para agentes, y un dashboard de merchant mostrando sesiones en tiempo real y analíticas. Tiempo requerido: unos 10 minutos para setup básico, unos 30 minutos para configuración completa. Prerequisitos: una tienda activa en Shopify, WooCommerce u Odoo con al menos un producto publicado.

Trusteed actua como un puente entre tu plataforma e-commerce existente y los agentes IA. Sincroniza tu catálogo de productos a una base de datos normalizada (cache de 30 minutos), expone herramientas MCP estandarizadas que cualquier agente puede llamar, gestiona rate limiting, autenticación y trust scoring, y no es procesador de pagos ni merchant of record: cuando hay cargo, se hace en tu propia cuenta de pago. En una tienda Shopify, complete_checkout le da al comprador un enlace a tu checkout nativo. Los agentes navegan y crean carritos; los clientes completan el pago en tu checkout.

Registrate en trusteed.xyz/dashboard. La autenticación usa magic links: introduce tu email, haz clic en el enlace, y estas dentro. Sin contraseñas que gestionar. El acceso público actual se gestiona como beta gratuita con protecciones de fair use, suficiente para probar end-to-end los flujos de búsqueda, navegación, carrito y checkout antes de cualquier despliegue comercial posterior.

Para Shopify: haz clic en Añadir Tienda, introduce tu dominio mitienda.myshopify.com, y autoriza via OAuth. La plataforma sincroniza tu catálogo automaticamente usando paginación basada en cursor (maneja 10K+ productos). Usa Shopify GraphQL Admin API con tokens OAuth que se auto-refrescan. Para WooCommerce: instala el plugin WordPress de Trusteed, copia tu Consumer Key y Consumer Secret desde WooCommerce Ajustes REST API. El plugin envia cambios via hooks de WordPress (on_product_save, on_stock_change, on_product_delete). Usa REST API v3 con HTTP Basic Auth. Para Odoo: introduce la URL de tu instancia (SaaS o self-hosted), autentícate con API key (recomendado sobre contraseña), y selecciona categorías de producto. Usa Odoo XML-RPC API. Tras conectar, tu tienda obtiene un slug único y tu endpoint MCP queda activo.

Tu endpoint esta disponible inmediatamente para herramientas de solo lectura sin autenticación. 11 herramientas son públicas (sin auth): search_products, get_product_details, browse_categories, get_merchant_profile, search_global_products, get_store_policies, check_availability, compare_products, get_deals, get_reviews, search_knowledge. Las herramientas de checkout (create_cart, preview_checkout, complete_checkout) requieren un Agent API Key o token OAuth Bearer.

Para flujos de checkout, los agentes necesitan autenticarse. Opción A (recomendado): Agent API Key: genera desde Dashboard, Ajustes de Tienda, API Keys. Pasa via header X-Agent-Api-Key. Las keys se hashean con HMAC-SHA256; la plataforma nunca almacena la clave en texto plano. Opción B: Token OAuth 2.0 Bearer para integraciones machine-to-machine (M2M) via /api/v1/auth/login. Para integración con Claude Desktop / Claude.ai, añade una entrada mcpServers con la URL de tu tienda y API key en los headers.

La secuencia completa de checkout del agente: (1) search_products para encontrar productos, (2) get_product_details para confirmar precio y disponibilidad, (3) create_cart para añadir items y obtener un cart_id, (4) preview_checkout para ver el total con envío e impuestos, (5) get_shipping_rates para opciones disponibles, (6) select_shipping_option para que el agente elija método, (7) complete_checkout, que devuelve un status: COMPLETED con order_id, o PENDING_EXTERNAL_CONFIRMATION con el enlace donde la persona completa el pago (en una tienda Shopify, tu checkout nativo). La plataforma nunca maneja tarjetas de crédito. Las sesiones de checkout están encriptadas (AES-256-GCM) con un TTL de 30 minutos.

Tres mecanismos de descubrimiento: (1) Directorio de Merchants (automático): tu tienda se lista en /.well-known/merchant-index.json y /api/v1/stores/directory con slug, categorías, trust score y endpoint MCP. (2) Búsqueda Semántica NLWeb: POST /{slug}/ask con consultas en lenguaje natural, usa embeddings pgvector, resultados via SSE. (3) Archivos de Descubrimiento Machine-Readable: /llms.txt, /mcp.json, /.well-known/acp.json, /.well-known/ucp, /.well-known/agent-policy.json, /.well-known/agent-card.json. Estos archivos son como Claude, ChatGPT y otros LLMs aprenden sobre la plataforma.

Trust Score v4.1 combina tres dimensiones ponderadas, un bonus opcional de aseguramiento externo y topes según confianza. Cada respuesta identifica el motor utilizado; algunas recurren a v2. El desglose legacy por componentes no explica una puntuación global producida por v4.1.

Registra endpoints de webhook via POST /api/v1/webhooks con eventos: order.created, order.status_changed, checkout.abandoned. Verifica payloads usando firma HMAC-SHA256 en header X-Webhook-Signature con crypto.timingSafeEqual para comparación en tiempo constante.

Trusteed soporta 8 protocolos: MCP, ACP, AP2, x402 stablecoin, UCP, A2A, AG-UI y redes de tarjetas VIC/MCAP. Cada protocolo es auto-detectado. Los agentes envian peticiones en su formato preferido; la plataforma normaliza todo a un AgentPaymentIntent unificado.