Error #1: Devolver un catálogo parcial
El problema: El endpoint GET /ucp/v1/catalog pagina correctamente pero omite productos sin imágenes, artículos agotados o productos en ciertas categorías. Los agentes de IA reciben una vista incompleta de tu inventario.
La solución: Incluye todos los productos activos, incluidos los temporalmente agotados (con availability: "OutOfStock"). Los agentes utilizan el estado de disponibilidad para planificar compras; saber que un producto existe pero no está disponible actualmente es información útil. Nunca filtres por estado de stock a nivel de catálogo.
Error #2: Datos de inventario obsoletos
El problema: El endpoint del catálogo devuelve niveles de stock actualizados cada 24 horas, pero tu inventario real cambia en tiempo real. Un agente de IA confirma el stock para un cliente, el cliente aprueba la compra y el pago falla porque el artículo se agotó 6 horas antes.
La solución: Implementa un endpoint dedicado GET /ucp/v1/products/{id}/availability que consulte el inventario en vivo. El flujo de pago debe volver a verificar la disponibilidad en el momento de la creación del pedido, no depender de la caché del catálogo. Se recomienda encarecidamente el soporte de webhooks para los cambios en el nivel de stock.
Error #3: Campos obligatorios faltantes en los objetos de producto
El problema: UCP define campos obligatorios para los objetos de producto: id, name, description, price, currency, availability, category. Muchas implementaciones omiten category (usando una taxonomía propietaria) o gtin / mpn (útiles pero tratados como opcionales). Los agentes que filtran por categoría o que hacen referencias cruzadas de GTINs entre comerciantes no encontrarán tus productos.
La solución: Mapea tus categorías internas a la taxonomía estándar de UCP. Incluye GTINs y MPNs para todos los productos donde existan, ya que permiten a los agentes comparar productos idénticos entre múltiples comerciantes.
Error #4: No se gestiona la caducidad del token de autenticación
El problema: Los tokens de autenticación AP2 tienen una ventana de validez. Si tu implementación no maneja la actualización del token, las sesiones de pago agéntico que duran más que la ventana de validez del token fallan a mitad de la transacción.
La solución: Implementa la lógica de actualización de tokens en tu manejador de pagos. Cuando un token AP2 esté cerca de caducar durante una transacción, solicita una actualización antes de continuar. Registra los eventos de caducidad de tokens para identificar si esto está causando abandonos.
Error #5: Nombres de productos poco descriptivos
El problema: Nombres de productos como "Modelo XR-2200B" o "SKU-48291" son significativos en tu sistema interno pero incomprensibles para un agente de IA que intenta hacer coincidir la solicitud en lenguaje natural de un usuario ("una prensa francesa de acero inoxidable para 4 tazas").
La solución: Los nombres de los productos en las respuestas del catálogo UCP deben ser legibles por humanos y descriptivos. "Prensa francesa de acero inoxidable, 4 tazas / 600 ml" es mucho más útil para un agente que un código de modelo. Considera tener un campo agent_name separado que esté optimizado para la coincidencia de lenguaje natural.
Error #6: Política de devoluciones no legible por máquina
El problema: La especificación UCP incluye un objeto returnPolicy en las respuestas de pago. Muchas implementaciones devuelven una URL que enlaza a la página de la política de devoluciones en lugar de datos estructurados. Los agentes de IA no pueden analizar HTML para extraer los términos de la política.
La solución: Devuelve un objeto returnPolicy estructurado con los campos: returnWindowDays (entero), returnType ("free" / "paid" / "exchange-only"), conditions (array de cadenas de texto en lenguaje sencillo). Esto permite a los agentes informar con precisión a los usuarios sobre los términos de devolución antes de la confirmación de la compra.
Error #7: Límite de velocidad configurado de forma demasiado agresiva
El problema: Los comerciantes establecen límites de velocidad en los endpoints de UCP para proteger su infraestructura. Límites de 10 solicitudes/minuto pueden parecer razonables para navegadores humanos, pero son inadecuados para agentes de IA, que pueden realizar solicitudes secuenciales rápidas para comparar productos o verificar el inventario en múltiples categorías.
La solución: Diferencia los límites de velocidad por tipo de endpoint. Las lecturas del catálogo pueden servirse desde la caché con límites generosos (más de 100 solicitudes/minuto). Los endpoints de pago deben tener límites más estrictos (10-30/minuto) ya que implican la reserva de inventario. Implementa respuestas HTTP 429 adecuadas con encabezados Retry-After para que los agentes puedan retroceder elegantemente en lugar de fallar.
Error #8: Problemas con el certificado HTTPS en el subdominio UCP
El problema: Muchos comerciantes alojan los endpoints de UCP en un subdominio (por ejemplo, api.yourstore.com) con un certificado SSL gestionado por separado. Los certificados caducados, los SAN mal configurados o la falta de certificados intermedios hacen que los agentes rechacen tus endpoints como no confiables.
La solución: Utiliza la renovación automática de certificados (Let's Encrypt con certbot, o los certificados gestionados por tu proveedor de CDN). Configura alertas de monitoreo para certificados que caduquen en 30 días. Prueba tu subdominio UCP con SSL Labs regularmente.
Error #9: La confirmación de pago no se devuelve en tiempo real
El problema: Tu endpoint POST /ucp/v1/checkout pone el pedido en cola para su procesamiento y devuelve una respuesta 202 Accepted, esperando que el agente consulte la confirmación. Muchos agentes interpretan cualquier cosa que no sea un 200 OK síncrono con un ID de pedido como un fallo.
La solución: Procesa el pago de forma síncrona y devuelve una respuesta 200 con un objeto de pedido completo (ID de pedido, entrega estimada, número de confirmación) en 3 segundos. Si tu backend requiere procesamiento asíncrono, implementa un paso de prevalidación síncrono rápido que devuelva un ID de pedido optimista, luego actualiza a través de webhook.
Error #10: No probar con la suite de pruebas oficial de UCP
El problema: Los desarrolladores prueban los endpoints de UCP con comandos curl manuales o Postman, no con la suite de pruebas de certificación oficial de UCP. Estas pruebas manuales omiten casos límite que la especificación define: solicitudes mal formadas, cargas útiles parciales, manejo de tiempos de espera, intentos de pago concurrentes.
La solución: Ejecuta la suite de pruebas oficial de UCP (disponible en ucp.dev/testing) en tu entorno de staging antes y después de cada lanzamiento. Añade la suite de pruebas a tu pipeline de CI/CD. La certificación UCP es cada vez más referenciada por los principales proveedores de agentes de IA como una señal de confianza; mantener el estado de certificación es importante.