developer-guide14 min

Construyendo Comercio Agéntico #5: UCP — El Protocolo de Comercio Universal de Shopify en la Práctica

Cómo UCP (Universal Commerce Protocol) permite a los agentes IA descubrir tiendas, crear checkouts, vincular identidad de comprador y obtener datos de catálogo en tiempo real — con ejemplos de código de producción.

Resumen ejecutivo

Parte 5 de 'Construyendo Comercio Agéntico' explica UCP — el Protocolo de Comercio Universal de Google y Shopify. Cubre detección de protocolo (3 niveles de confianza), descubrimiento vía /.well-known/ucp, ciclo de vida del checkout de 6 estados, vinculación de identidad SCP con niveles de lealtad, capacidad de catálogo en tiempo real, delegación de mandatos AP2, 5 herramientas MCP y 215 tests.

Publicado

2026-04-06

14 min

Autoría

AgenticMCPStores Engineering

Core Protocol Team

Categoría

developer-guide

UCPProtocolo de Comercio UniversalShopifyGooglecomercio agénticoMCPcheckoutidentidadcatálogoSCP

En las Partes 1, 2, 3 y 4 cubrimos checkout multi-protocolo, descubrimiento de agentes, trust scores y pagos stablecoin x402. Ahora abordamos el protocolo respaldado por Google y Shopify con 30+ partners: UCP — el Protocolo de Comercio Universal.

¿Qué es UCP?

UCP es un protocolo abierto diseñado por Google y Shopify para estandarizar cómo los agentes IA interactúan con plataformas de comercio. A diferencia de ACP (centrado en Stripe) o x402 (basado en wallets), UCP es agnóstico de plataforma con un rico sistema de capacidades. Las tiendas declaran qué soportan — checkout, carrito, catálogo en tiempo real, vinculación de identidad — y los agentes descubren estas capacidades vía un endpoint estándar.

Diferencias clave con otros protocolos: UCP tiene un ciclo de vida de checkout de 6 estados (vs los 4 de ACP), un namespace de extensiones de capacidad (dev.ucp.*), vinculación de identidad SCP nativa para datos de lealtad del comprador, y delegación de mandatos AP2 integrada para pagos recurrentes.

Descubrimiento: /.well-known/ucp

Los agentes descubren tiendas habilitadas para UCP vía el endpoint /.well-known/ucp. El descubrimiento a nivel de plataforma devuelve todas las capacidades; el descubrimiento a nivel de merchant devuelve perfiles específicos por tienda:

// Descubrimiento de plataforma
GET /.well-known/ucp

// Descubrimiento específico de merchant
GET /.well-known/ucp?store=mi-tienda-slug

// Respuesta (perfil del merchant)
{
  "specVersion": "2026-01-23",
  "status": "active",
  "capabilities": [
    "dev.ucp.shopping.checkout",
    "dev.ucp.shopping.cart",
    "dev.ucp.catalog.realtime",
    "dev.ucp.identity.loyalty"
  ],
  "services": {
    "rest": "/api/v1/ucp",
    "mcp": "/mi-tienda-slug/mcp",
    "a2a": "/mi-tienda-slug/a2a"
  },
  "tools": [
    "ucp_create_checkout",
    "ucp_get_checkout",
    "ucp_update_checkout",
    "ucp_complete_checkout",
    "ucp_cancel_checkout"
  ]
}

Detección de Protocolo

El adaptador inbound de UCP usa tres niveles de confianza para identificar solicitudes UCP:

1
Header UCP-Agent presente → confianza 1.0 (declaración explícita)
2
Body contiene array capabilities → confianza 0.9
3
Body coincide con schema Zod UcpCheckout → confianza 0.85 (detección por forma)

Ciclo de Vida del Checkout de 6 Estados

UCP define un ciclo de vida de checkout más rico que ACP. Los 6 estados mapean tanto a estados internos de intent como a respuestas HTTP:

Estado UCP             → Estado Intent        → HTTP
─────────────────────────────────────────────────────
incomplete            → CREATED              → 200
requires_escalation   → BLOCKED              → 422
ready_for_complete    → POLICY_EVALUATED     → 200
complete_in_progress  → DISPATCHED           → 200
completed             → COMPLETED            → 200
canceled              → FAILED               → 409

El estado requires_escalation es único de UCP — señala que una regla de política KYAI ha bloqueado el checkout y el agente necesita escalar al usuario para revisión.

Vinculación de Identidad SCP

UCP integra nativamente con SCP (Shopper Context Protocol) para verificación de identidad y datos de lealtad. El flujo usa OAuth 2.0:

// Paso 1: El agente solicita autorización
GET /ucp/identity/authorize?scope=loyalty:read,identity:link
→ Devuelve código de autorización

// Paso 2: El agente intercambia código por token
POST /ucp/identity/token
{ "code": "auth-code-123", "grant_type": "authorization_code" }
→ Devuelve { "access_token": "tok-xxx", "expires_in": 3600 }

// Paso 3: El agente llama al checkout con token
POST /api/v1/ucp/checkout
Authorization: Bearer tok-xxx
→ UCP Identity Service obtiene datos reales de lealtad

1
Shopify: Lee metafields del cliente (namespace loyalty) vía Storefront GraphQL. Mapea tier a descuento: gold = 10%, silver = 5%, bronze = 0%.
2
WooCommerce: Obtiene balance de puntos vía /wp-json/wc/v1/customers/{id}/points. Fallback graceful si plugin de lealtad no está instalado.

Catálogo en Tiempo Real (Fase B)

Cuando un merchant habilita dev.ucp.catalog.realtime, los agentes pueden obtener precios e inventario en vivo sin un sync completo del catálogo:

GET /{slug}/ucp/catalog?product_ids=prod1,prod2&limit=20

{
  "products": [
    {
      "id": "prod-aaa",
      "title": "Widget A",
      "price": { "amount": 1500, "currency": "USD" },
      "availability": "IN_STOCK",
      "inventory_count": 42
    }
  ],
  "freshness_ms": 2500
}

Delegación de Mandatos AP2

UCP soporta mandatos AP2 (Authorization Protocol v2) como extensión nativa. Cuando un merchant habilita dev.ucp.shopping.ap2_mandate, los agentes pueden incluir mandatos de pago recurrente directamente en solicitudes de checkout UCP. El adaptador ucp-ap2-delegate.ts extrae el mandato del campo extensions de UCP y delega al parser AP2 existente — no se escribió código nuevo de verificación de mandatos.

Manejo de Errores: Modelo Basado en Severidad

UCP usa un modelo de errores basado en severidad que mapea a códigos HTTP:

Severidad              → HTTP  → Significado
──────────────────────────────────────────────────
recoverable            → 400   → El cliente puede reintentar con input diferente
requires_buyer_input   → 303   → Redirigir agente a recopilar input del usuario
requires_buyer_review  → 422   → Regla de política necesita confirmación del usuario
unrecoverable          → 409   → Checkout ya completado o cancelado

UCP vs ACP: Cuándo Usar Cuál

Aspecto	UCP	ACP
Respaldado por	Google + Shopify (30+ partners)	Stripe + OpenAI
Descubrimiento	`/.well-known/ucp` (dinámico)	`/.well-known/acp.json` (estático)
Estados de checkout	6 (con escalación)	4
Soporte de carrito	Sí (`dev.ucp.shopping.cart`)	No (solo checkout)
Catálogo en tiempo real	Sí (`dev.ucp.catalog.realtime`)	No
Vinculación de identidad	Estándar SCP (OAuth 2.0)	Headers personalizados
Transportes	REST, MCP, A2A, AG-UI, Embedded	REST, MCP
Modelo de errores	4 niveles de severidad	Estado HTTP + body

Ambos protocolos normalizan al mismo formato interno AgentPaymentIntent y comparten el mismo motor de políticas KYAI. Desde la perspectiva de la plataforma, UCP y ACP son solo adaptadores de protocolo diferentes — la lógica de checkout es idéntica.

Idea clave

Herramientas MCP para UCP

1
ucp_create_checkout — Crear sesión de checkout UCP desde line items
2
ucp_get_checkout — Obtener detalles del checkout por ID
3
ucp_update_checkout — Modificar items o totales
4
ucp_complete_checkout — Finalizar y disparar pago
5
ucp_cancel_checkout — Cancelar una sesión activa

Las 5 herramientas devuelven structuredContent (compatible con Claude SDK 1.27.x) junto con resúmenes de texto formateados. La idempotencia se soporta vía idempotency_key.

Cobertura de Tests

La implementación UCP está respaldada por 215 tests en 22 archivos de test. La cobertura incluye: detección inbound (25 tests), traducción outbound (20 tests), mapping de checkout (18 tests), mapping de errores (12 tests), delegación AP2 (20 tests), perfiles de descubrimiento (25 tests), validación de configuración (10 tests), integración end-to-end (30 tests), servicio de catálogo (40+ tests), servicio de identidad (35+ tests) y herramientas MCP (10 tests).

Qué Viene

En la Parte 6, exploraremos A2A — el Protocolo Agent-to-Agent de Google y cómo permite que los agentes colaboren en flujos de trabajo de comercio multi-paso. Mantente atento.

Preguntas frecuentes

¿Qué es UCP y quién lo creó?

UCP (Universal Commerce Protocol) es un protocolo abierto diseñado por Google y Shopify con 30+ partners. Estandariza cómo los agentes IA interactúan con plataformas de comercio — desde descubrimiento de productos hasta checkout y vinculación de identidad.

¿En qué se diferencia UCP de ACP?

UCP tiene un ciclo de vida de checkout de 6 estados (vs los 4 de ACP), un namespace de extensiones de capacidad (dev.ucp.*), vinculación de identidad SCP nativa para datos de lealtad, acceso a catálogo en tiempo real, y soporta 5 bindings de transporte (REST, MCP, A2A, AG-UI, Embedded). ACP es centrado en Stripe con flujos de checkout más simples.

¿Pueden UCP y ACP coexistir en la misma tienda?

Sí. Ambos protocolos normalizan al mismo formato AgentPaymentIntent y comparten el motor de políticas KYAI. El detector de protocolos enruta cada solicitud al adaptador correcto basándose en scores de confianza. Una tienda puede tener UCP y ACP habilitados simultáneamente.

¿Qué es la vinculación de identidad SCP en UCP?

SCP (Shopper Context Protocol) permite a los agentes vincular la identidad del comprador y acceder a datos de lealtad vía OAuth 2.0. Los agentes pueden leer niveles de lealtad (gold/silver/bronze), obtener balances de puntos y aplicar descuentos de lealtad en el checkout.

¿Cómo funciona el catálogo en tiempo real de UCP?

Cuando un merchant habilita dev.ucp.catalog.realtime, los agentes pueden obtener precios e inventario en vivo vía GET /{slug}/ucp/catalog. Los datos se cachean por 30 segundos con un campo freshness_ms que muestra la antigüedad. El servicio obtiene datos de Shopify Storefront GraphQL o WooCommerce REST API.

Fuentes y referencias

Especificación del Protocolo de Comercio Universal
UCP Working Group (Google + Shopify)
Shopper Context Protocol (SCP)
SCP Working Group
Especificación MCP — Model Context Protocol
Anthropic