Tutorial del Universal Commerce Protocol: crea tu primer servidor UCP

En esta guía aprenderás qué es el Universal Commerce Protocol (UCP), para quién está pensado, por qué hace falta un nuevo estándar de comercio y cómo funciona su arquitectura. 

También seguirás un recorrido práctico para configurar tu propio servidor de ejemplo UCP, explorar su perfil de descubrimiento, crear una sesión de pago y ejecutar un flujo completo en local. 

Esto te dará una comprensión clara del protocolo y un punto de partida práctico para probar cómo funciona UCP en una implementación real.

Introducción al Universal Commerce Protocol

Universal Commerce Protocol es un estándar abierto que ayuda a que agentes de IA, apps, negocios y proveedores de pago colaboren en un único flujo de compra compartido. En lugar de crear una integración a medida para cada nuevo socio, UCP ofrece una forma común de comunicarse.

UCP está diseñado para el shopping guiado por agentes, donde las personas descubren y compran productos a través de asistentes de IA e interfaces conversacionales. Cubre todo el recorrido, desde descubrir qué ofrece un negocio hasta iniciar el pago y gestionar la compra de forma estructurada.

Fuente: Google Developers Blog

En pocas palabras, UCP actúa como un lenguaje común para el comercio. Un negocio puede publicar lo que admite, y un agente puede leer esa información e interactuar sin necesidad de una integración de API ad hoc. Shopify lo describe como la infraestructura creada para impulsar el comercio con agentes a gran escala.

UCP también es open source y neutral respecto a proveedores. Está diseñado para funcionar con los sistemas de comercio existentes y es compatible con el Agent Payments Protocol (AP2) para pagos seguros dirigidos por agentes. También puede funcionar sobre distintos transportes, incluidos APIs REST, comunicación agente a agente y MCP. 

¿Para quién está pensado Universal Commerce Protocol?

El UCP está pensado para los principales grupos implicados en el comercio digital actual. Su objetivo es darles a todos un lenguaje común para que colaboren sin construir integraciones a medida en cada conexión.

Está principalmente diseñado para:

1. Agentes de IA y plataformas de consumo

Son las apps, asistentes y superficies de descubrimiento que ayudan a los usuarios a encontrar productos y comprar. UCP les ayuda a entender qué admite un negocio e interactuar con él de forma estructurada. Google lo describe como conectar las superficies de consumo con los backends de los negocios para un shopping sin fricciones.

2. Empresas y comercios

UCP ayuda a las empresas a exponer sus productos, flujos de pago y funciones admitidas en un formato estándar. Así es más fácil colaborar con distintas plataformas y agentes de IA sin crear una integración distinta para cada uno.

3. Proveedores de pago

Los proveedores de pago también forman parte del ecosistema UCP. El protocolo está diseñado para admitir distintos payment handlers y credenciales de pago de forma flexible, para gestionar pagos con seguridad entre sistemas.

4. Desarrolladores y creadores de protocolos

UCP es open source, así que también está pensado para desarrolladores que quieran implementar, ampliar o contribuir al estándar. El proyecto UCP invita explícitamente a empresas, desarrolladores y proveedores de pago a definir el futuro del protocolo.

En resumen, UCP está pensado para quien participe en comercio impulsado por IA: la plataforma que ayuda a comprar al usuario, el negocio que vende, el sistema de pagos que procesa la transacción y los desarrolladores que construyen las conexiones entre ellos.

Por qué es necesario un nuevo estándar de comercio

Hace falta un nuevo estándar porque la mayoría de sistemas de comercio actuales se crearon para webs tradicionales y apps móviles, no para asistentes de IA y compras conversacionales. 

Ese modelo anterior suele depender de APIs a medida e integraciones puntuales, lo que lo hace lento y difícil de escalar entre muchas plataformas. UCP se creó para resolver esto ofreciendo a negocios, agentes y plataformas una forma común de comunicarse.

A medida que más gente compra con herramientas de IA, el comercio debe soportar acciones en vivo como descubrimiento de productos, pago, descuentos y actualizaciones de pedido dentro de la misma conversación. 

UCP está diseñado para este estilo más reciente de compra, donde la experiencia es más interactiva y ocurre en diferentes superficies digitales.

También es necesario porque el ecosistema de comercio actual está fragmentado. Distintos negocios, proveedores de pago y plataformas usan a menudo sistemas diferentes. UCP ayuda a unirlos con un estándar común, para que colaboren sin rehacer las mismas integraciones una y otra vez.

En resumen, UCP es necesario porque las herramientas antiguas de comercio no se crearon para compras guiadas por IA. Ofrece a la industria una base más moderna y flexible para cómo la gente descubrirá y comprará productos a partir de ahora.

Comprender la arquitectura de Universal Commerce Protocol

El Universal Commerce Protocol (UCP) es un sistema modular para comercio con agentes. Ofrece a empresas, agentes de IA y proveedores de pago una forma común de gestionar el recorrido de compra, desde el descubrimiento hasta el pago y más allá. 

En lugar de crear integraciones a medida para cada plataforma, UCP permite que un negocio publique lo que admite para que un agente lo lea y siga un flujo estándar. 

UCP es modular y extensible, admite transportes como REST, MCP y A2A, y funciona con payment handlers para que los negocios aprovechen con más facilidad sus configuraciones de pago existentes.

1. El negocio publica un perfil de descubrimiento

Un negocio con UCP expone un perfil en /.well-known/ucp. Este perfil indica a plataformas y agentes qué admite el negocio antes de cualquier transacción, incluidas capacidades y endpoints disponibles.

2. El agente lee las capacidades admitidas

Tras el descubrimiento, el agente comprueba qué servicios y capacidades ofrece el negocio. El lanzamiento inicial de UCP se centra en capacidades clave como checkout, vinculación de identidad y gestión de pedidos, que actúan como los bloques básicos del protocolo.

3. Las extensiones añaden funciones extra

UCP mantiene simple el flujo básico, pero los negocios pueden añadir extensiones opcionales cuando lo necesiten. Estas extensiones se construyen sobre las capacidades principales y permiten admitir funciones más ricas sin cambiar todo el protocolo.

4. El flujo se ejecuta sobre un transporte admitido

Una vez que el agente sabe qué se admite, puede interactuar con el negocio usando un transporte como REST, MCP o A2A. Así es más fácil reutilizar la misma lógica de comercio en APIs, herramientas de IA y sistemas agente a agente.

5. El pago se gestiona mediante payment handlers

UCP separa el flujo de comercio de la capa de pagos. Los negocios pueden declarar los payment handlers admitidos, y el protocolo está diseñado para que los comercios sigan usando sus integraciones de pago existentes en lugar de reconstruirlo todo desde cero.

6. Los pagos seguros guiados por agentes pueden usar AP2

UCP es compatible con el Agent Payments Protocol (AP2), que añade una capa segura para pagos dirigidos por agentes. Esto ayuda a una autorización más segura cuando un agente de IA actúa en nombre del usuario.

Recorrido de extremo a extremo por Universal Commerce Protocol

Esta guía muestra un flujo completo de Universal Commerce Protocol usando la implementación de referencia en Python. Configurarás el servidor de ejemplo del comercio, cargarás un catálogo de una floristería de demo, descubrirás las capacidades del negocio, crearás una sesión de pago, aplicarás un descuento y después detendrás el servidor.

Paso 1: configura el servidor del negocio

En este paso, instalarás uv para gestionar dependencias de Python y luego clonarás tanto el UCP Python SDK como el repositorio del servidor de ejemplo. El README del servidor de ejemplo sigue el mismo patrón de configuración e indica que la ruta relativa al SDK es importante para los ejemplos.

Como nuestro sistema operativo es Linux, usaremos el siguiente comando para instalar uv. uv es un gestor de paquetes y entornos de Python rápido y fiable. Cumple un propósito similar a herramientas como Anaconda, pero es mucho más ligero y veloz.

curl -LsSf https://astral.sh/uv/install.sh | sh

Cuando termine la instalación, recarga tu sesión de terminal para que el comando uv esté disponible en la shell actual.

source ~/.bashrc

A continuación, crea una carpeta nueva llamada sdk. Esta carpeta almacenará el Universal Commerce Protocol Python SDK cuando lo clonemos desde el repositorio de GitHub. 

mkdir sdk
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git 
sdk/python

Ahora cambia al directorio sdk/python, donde se clonó el repositorio del SDK.

pushd sdk/python

Una vez dentro del directorio del SDK, instala con uv sync todas las dependencias de Python necesarias.

uv sync

Cuando finalicen las dependencias, vuelve a tu directorio de trabajo anterior.

popd

Ahora clona el repositorio de samples, que contiene el servidor de referencia en Python que usaremos en este recorrido.

git clone https://github.com/Universal-Commerce-Protocol/samples.git

Después, entra en el ejemplo del servidor en Python dentro del repositorio de samples.

cd samples/rest/python/server

Por último, instala todas las dependencias de Python necesarias para ejecutar el servidor de ejemplo.

uv sync

A estas alturas, el servidor de ejemplo del negocio está listo en tu espacio de trabajo. Este servidor ya implementa las capacidades básicas de compra definidas por UCP.

Paso 2: crea una base de datos de productos de ejemplo

En este paso, crearás una tienda de demo local basada en SQLite para el negocio de ejemplo. El negocio de ejemplo en este tutorial es una floristería, y este comando carga el catálogo de productos y la base de datos de transacciones que usará el servidor.

Primero, crea una carpeta temporal donde se almacenarán los archivos de la base de datos.

mkdir /tmp/ucp_test

Después, ejecuta el script de importación para crear y poblar las bases de datos de productos y transacciones.

uv run import_csv.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --data_dir=../test_data/flower_shop

Este comando hace lo siguiente:

• --products_db_path crea la base de datos del catálogo de productos.
• --transactions_db_path crea la base de datos de transacciones usada para el estado del checkout.
• --data_dir=../test_data/flower_shop apunta a los datos de muestra de la floristería incluidos en el repositorio.

Cuando completes este paso, los datos de tu tienda de ejemplo local estarán listos y el servidor podrá usarlos.

Paso 3: inicia el servidor del negocio

En este paso, iniciarás el servidor de negocio UCP de ejemplo. Este servidor usará las bases de datos de productos y transacciones que creaste en el paso anterior y expondrá las APIs de compra de UCP en el puerto 8182.

Ejecuta el siguiente comando para iniciar el servidor en segundo plano.

uv run server.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --port=8182 &
SERVER_PID=$!

Este comando hace lo siguiente:

• uv run server.py inicia el servidor de ejemplo en Python.
• --products_db_path conecta el servidor a la base de datos de productos.
• --transactions_db_path conecta el servidor a la base de datos de transacciones.
• --port=8182 indica que el servidor se ejecute en el puerto 8182.
• & ejecuta el proceso en segundo plano para que puedas seguir usando la terminal.
• SERVER_PID=$! guarda el ID del proceso para poder detener el servidor más tarde.

En este punto, el servidor del negocio está en marcha y listo para aceptar solicitudes de un agente.

Paso 4: descubre las capacidades del negocio

En este paso, consultarás el endpoint de descubrimiento de UCP. Todo negocio con UCP publica un documento de descubrimiento en /.well-known/ucp, que permite a los agentes entender qué admite el negocio antes de hacer ninguna solicitud.

Primero, guarda la URL del servidor en una variable para que los próximos comandos sean más legibles.

export SERVER_URL=http://localhost:8182

Ahora recupera el documento de descubrimiento de UCP desde el servidor del negocio.

curl -s $SERVER_URL/.well-known/ucp

Esta respuesta indica al agente:

• qué versión de UCP admite el servidor,
• qué servicios están disponibles,
• qué capacidades están implementadas, como checkout y descuentos,
• y qué payment handlers o esquemas se admiten.

Este paso de descubrimiento es importante porque elimina la necesidad de integraciones personalizadas y rígidas. El agente puede inspeccionar primero el servidor y después decidir cómo interactuar con él.

Paso 5: crea una sesión de checkout

En este paso, crearás una nueva sesión de pago usando la capacidad de checkout de UCP. Aquí es donde el agente envía el producto seleccionado, la información del comprador y la estructura de pago al servidor del negocio.

Antes de enviar la solicitud, genera las cabeceras necesarias. Estas cabeceras ayudan con el trazado de solicitudes, la idempotencia y la validación de firmas.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Esto hace lo siguiente:

• REQUEST_ID crea un identificador único para la solicitud.
• IDEMPOTENCY_KEY garantiza que la misma solicitud no se procese dos veces si se reintenta.
• REQUEST_SIGNATURE proporciona la cabecera de firma requerida. En una demo local, se puede usar "dev" si no se aplica validación estricta.

Ahora envía la solicitud de checkout al servidor.

curl -X POST "$SERVER_URL/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d '{
    "line_items": [
      { "item": { "id": "bouquet_roses", "title": "Red Rose" }, "quantity": 1 }
    ],
    "buyer": { "full_name": "John Doe", "email": "john.doe@example.com" },
    "currency": "USD",
    "payment": { "handlers": [], "instruments": [] }
  }'

Esta solicitud incluye:

• line_items para definir qué quiere comprar el comprador,
• item.id para identificar el producto,
• item.title para mostrar un nombre legible,
• quantity para indicar cuántas unidades se compran,
• buyer para incluir los datos del cliente,
• currency para definir la divisa del checkout,
• y payment para proporcionar la estructura de pago requerida.

La respuesta devolverá un objeto de sesión de checkout. Incluye el nuevo ID de checkout, IDs de líneas, totales, información del comprador y el estado actual del checkout.

Paso 6: aplica descuentos con UCP

En este paso, actualizarás la sesión de checkout existente y aplicarás un código de descuento. Los descuentos en UCP se implementan como una extensión de la capacidad de checkout, por lo que el descuento se añade como parte de la solicitud de actualización del checkout.

Primero, guarda el ID real de checkout y el ID de la línea que devolvió la respuesta anterior.

export CHECKOUT_ID=5dd08e18-c9c1-4fa1-a0d1-885ca81cda29
export LINE_ITEM_ID=ed72ebe6-2484-4e7b-afc8-a8ff5c8f430e

Después, genera un nuevo request ID y una nueva clave de idempotencia para esta actualización.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Ahora envía la actualización del checkout con el código de descuento incluido.

curl -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d "{
    \"id\": \"$CHECKOUT_ID\",
    \"line_items\": [
      {
        \"id\": \"$LINE_ITEM_ID\",
        \"item\": { \"id\": \"bouquet_roses\", \"title\": \"Red Rose\" },
        \"quantity\": 1
      }
    ],
    \"buyer\": {
      \"full_name\": \"John Doe\",
      \"email\": \"john.doe@example.com\"
    },
    \"currency\": \"USD\",
    \"discounts\": {
      \"codes\": [\"10OFF\"]
    },
    \"payment\": {
      \"handlers\": [],
      \"instruments\": []
    }
  }"

Esta solicitud hace lo siguiente:

• actualiza el checkout existente usando PUT,
• incluye el ID de checkout original,
• vuelve a incluir la línea de producto,
• añade la sección discounts,
• y aplica el código 10OFF.

La respuesta debería devolver el checkout actualizado con:

• totales recalculados,
• el importe del descuento,
• el total final actualizado,
• y los detalles del descuento aplicado.

El código de descuento es válido; deberías ver el cambio de precio en la respuesta.

Paso 7: apaga el servidor

En este último paso, detendrás el servidor del negocio de ejemplo que iniciaste antes. Como guardaste el ID del proceso al arrancarlo, puedes apagarlo fácilmente con un comando.

Ejecuta el siguiente comando para parar el servidor.

kill $SERVER_PID

De principio a fin, has construido y probado con éxito un flujo UCP completo de extremo a extremo en tu máquina local.

Has:

• instalado las herramientas necesarias de Python con uv,
• clonado los repositorios del UCP Python SDK y del servidor de ejemplo,
• creado una base de datos de productos de una floristería de ejemplo,
• iniciado el servidor del negocio,
• descubierto las capacidades UCP del servidor a través del endpoint de descubrimiento,
• creado una sesión de checkout como agente,
• actualizado ese checkout aplicando un código de descuento,
• y por último apagado el servidor.

En pocas palabras, has configurado un negocio con UCP funcional, te has conectado como agente, has creado un checkout y has probado cómo UCP gestiona actualizaciones como los descuentos. Esto te da un ejemplo básico completo de cómo pueden interactuar un negocio y un agente usando Universal Commerce Protocol.

Conclusión

Universal Commerce Protocol ofrece a la industria una base común para el comercio guiado por IA. Crea una forma estándar de comunicación entre negocios, agentes de IA y sistemas de pago, facilitando descubrimiento, checkout, actualizaciones y pagos sin reconstruir integraciones a medida para cada nueva plataforma.

En esta guía has aprendido qué es UCP, por qué importa, cómo funciona su arquitectura y cómo ejecutar un ejemplo local completo de principio a fin. Al configurar el servidor de ejemplo, descubrir sus capacidades, crear una sesión de checkout y aplicar un descuento, has visto cómo UCP convierte el comercio en un flujo estructurado y amigable para agentes.

La mayor oportunidad de UCP es clara: puede reducir la fragmentación y hacer el comercio más interoperable en un mundo donde cada vez más compras suceden a través de asistentes de IA e interfaces conversacionales. 

El verdadero reto, sin embargo, será la adopción. Es posible que las empresas sigan optando por APIs a medida, integraciones existentes basadas en REST, herramientas basadas en MCP u otros flujos con agentes que ya usan hoy. Para que UCP tenga éxito, necesitará un fuerte apoyo del ecosistema por parte de comercios, plataformas, desarrolladores y proveedores de pago.