Saltar al contenido
UCP
Menú

Guía Técnica · Implementación

Implementando UCP: guía completa para comerciantes y desarrolladores

¿Quieres que tu tienda sea compatible con el Universal Commerce Protocol para ser accesible a los agentes de IA? Esta guía técnica cubre los requisitos previos, los endpoints a exponer, la integración de pagos AP2, las pruebas de validación y los errores comunes a evitar.

Actualizado : Abril de 2026 · Consulta principal : implementar UCP

Requisitos previos antes de empezar

Compatibilidad de la plataforma

Si utilizas Shopify: tienes una ventaja. Shopify es cofundador de UCP y ofrece soporte nativo desde el lanzamiento del protocolo en enero de 2026. La clave es activar las funciones de UCP en tu Admin y completar los datos de tus productos.

Para WooCommerce, Magento, PrestaShop, Salesforce Commerce o BigCommerce: las especificaciones están abiertas en el GitHub oficial de UCP. Un desarrollador backend familiarizado con REST y JSON-RPC puede implementar una integración básica en 2 o 3 días de trabajo.

Para una solución personalizada: la implementación directa es posible y está documentada en ucp.dev. Calcula de 5 a 10 días de desarrollo para una integración completa con pruebas.

Calidad de los datos de producto requerida

  • Completos: nombre, descripción, precio, moneda, variantes (talla, color), peso, dimensiones
  • Identificados: GTIN/EAN o SKU propietario documentado por producto
  • Actualizados: stock sincronizado casi en tiempo real (retraso máximo: unos minutos)
  • Enriquecidos: políticas de devolución estructuradas, tiempos de entrega por zona, atributos específicos de categoría

Procesador de pagos compatible con AP2

UCP se basa en el Agent Payments Protocol (AP2). Los procesadores compatibles son Stripe, Adyen, Mastercard, Visa y American Express, todos ellos socios fundadores de UCP. Si utilizas uno de estos procesadores con una integración actualizada, el soporte de AP2 requiere activación, no una revisión técnica.

Paso 1: Exponer los endpoints del catálogo

UCP define endpoints REST estandarizados que tu servidor debe exponer para que los agentes de IA puedan consultar tu catálogo.

GET /ucp/v1/catalog

Devuelve tu lista de productos en formato UCP JSON-LD. Cada producto debe incluir: @type: "Product", sku o gtin, name, description, offers (con precio, moneda, disponibilidad), shippingDetails y returnPolicy.

GET /ucp/v1/inventory/{sku}

Disponibilidad en tiempo real de un producto específico. Requisitos críticos de rendimiento: respuesta en menos de 200 ms, tiempo de actividad mínimo del 99,5%. Un tiempo de espera (timeout) excluye directamente tu producto, el agente de IA pasa a un competidor.

POST /ucp/v1/checkout

Recibe instrucciones de compra del agente de IA e inicia el proceso de pedido. Debe manejar: validación de identidad (UCP Identity Linking), reserva de stock, inicio de pago AP2 y generación de confirmación de pedido con número de seguimiento.

Paso 2: Implementar Identity Linking

Identity Linking permite a un agente de IA asociar la identidad de un usuario con tu sistema de comerciante sin que el usuario tenga que iniciar sesión manualmente en tu sitio en cada compra.

El usuario autoriza una vez (en la interfaz del agente de IA) para compartir su información de entrega y contacto. Esta información se transmite luego a través de tokens firmados criptográficamente que verificas a través de la API de verificación de UCP. Tu sistema nunca almacena datos bancarios, solo el token de identidad verificado.

Paso 3: Configurar pagos AP2

Para Stripe: Panel de control → Configuración → Pagos Agénticos → Habilitar Agent Payments Protocol. Configura los límites de transacción para pagos iniciados por agentes (cantidad máxima, categorías elegibles).

Para Adyen: contacta a tu gerente de cuenta para habilitar el perfil AP2. Adyen requiere una validación previa de tus endpoints de catálogo e inventario antes de activar los pagos agénticos.

Paso 4: Exponer los endpoints de gestión de pedidos

UCP requiere un conjunto de endpoints de gestión post-compra que los agentes de IA utilizan para mantener informado al usuario:

  • GET /ucp/v1/orders/{order_id}, estado del pedido en tiempo real
  • POST /ucp/v1/orders/{order_id}/cancel, cancelación iniciada por el agente de IA
  • GET /ucp/v1/orders/{order_id}/tracking, seguimiento de la entrega

Paso 5: Pruebas y validación

El repositorio oficial de GitHub (github.com/Universal-Commerce-Protocol/ucp) incluye un conjunto de pruebas de conformidad y un simulador de agente de IA. Antes de salir en vivo:

  1. Ejecuta el conjunto de pruebas de UCP en todos los endpoints
  2. Prueba escenarios de error (sin stock, pago rechazado, tiempo de espera)
  3. Valida Identity Linking con un token de prueba oficial
  4. Verifica los tiempos de respuesta del endpoint de inventario bajo carga
  5. Simula una compra completa de principio a fin con el simulador de agente

Errores comunes a evitar

Tiempos de espera (timeouts) no gestionados. Un endpoint de inventario que responda más allá de 500 ms será marcado como poco fiable. Utiliza Redis o una caché equivalente para los datos de inventario consultados con frecuencia.

Stock no sincronizado. Mostrar "disponible" para un producto sin stock crea una mala experiencia y degrada tu puntuación de reputación agéntica.

Política de devolución faltante. Los agentes de IA comparan activamente las políticas de devolución entre comerciantes. Un campo returnPolicy faltante o vacío te pone en desventaja.

Falta de manejo de errores en el proceso de pago. El agente de IA debe recibir códigos de error estandarizados (sin stock, identidad no verificada, pago rechazado) para ofrecer alternativas al usuario.

Recursos oficiales