Erro #1: Retornar um catálogo parcial
O problema: O endpoint GET /ucp/v1/catalog pagina corretamente, mas omite produtos sem imagens, itens fora de estoque ou produtos em certas categorias. Os agentes de IA recebem uma visão incompleta do seu inventário.
A correção: Inclua todos os produtos ativos, incluindo aqueles temporariamente fora de estoque (com availability: "OutOfStock"). Os agentes usam o status de disponibilidade para planejar compras; saber que um produto existe, mas está atualmente indisponível, é uma informação útil. Nunca filtre por status de estoque no nível do catálogo.
Erro #2: Dados de inventário desatualizados
O problema: O endpoint do catálogo retorna níveis de estoque atualizados a cada 24 horas, mas seu inventário real muda em tempo real. Um agente de IA confirma o estoque para um cliente, o cliente aprova a compra e o checkout falha porque o item esgotou 6 horas antes.
A correção: Implemente um endpoint dedicado GET /ucp/v1/products/{id}/availability que consulta o inventário em tempo real. O fluxo de checkout deve verificar novamente a disponibilidade no momento da criação do pedido, não depender do cache do catálogo. O suporte a webhooks para mudanças no nível de estoque é fortemente recomendado.
Erro #3: Campos obrigatórios ausentes em objetos de produto
O problema: O UCP define campos obrigatórios para objetos de produto: id, name, description, price, currency, availability, category. Muitas implementações omitem category (usando uma taxonomia proprietária) ou gtin / mpn (úteis, mas tratados como opcionais). Agentes que filtram por categoria ou fazem referência cruzada de GTINs entre comerciantes perderão seus produtos.
A correção: Mapeie suas categorias internas para a taxonomia padrão do UCP. Inclua GTINs e MPNs para todos os produtos onde estes existam, eles permitem que os agentes comparem produtos idênticos entre vários comerciantes.
Erro #4: Expiração do token de autenticação não tratada
O problema: Os tokens de autenticação AP2 têm uma janela de validade. Se sua implementação não lidar com a atualização do token, as sessões de checkout agentic que duram mais do que a janela de validade do token falham no meio da transação.
A correção: Implemente a lógica de atualização de token em seu manipulador de checkout. Quando um token AP2 estiver perto de expirar durante uma transação, solicite uma atualização antes de prosseguir. Registre eventos de expiração de token para identificar se isso está causando abandono.
Erro #5: Nomes de produtos não descritivos
O problema: Nomes de produtos como "Modelo XR-2200B" ou "SKU-48291" são significativos em seu sistema interno, mas incompreensíveis para um agente de IA tentando corresponder a uma solicitação de linguagem natural do usuário ("uma prensa francesa de aço inoxidável para 4 xícaras").
A correção: Os nomes dos produtos nas respostas do catálogo UCP devem ser legíveis por humanos e descritivos. "Prensa Francesa de Aço Inoxidável, 4 xícaras / 600ml" é muito mais útil para um agente do que um código de modelo. Considere ter um campo agent_name separado que seja otimizado para correspondência de linguagem natural.
Erro #6: Política de devolução não legível por máquina
O problema: A especificação UCP inclui um objeto returnPolicy nas respostas de checkout. Muitas implementações retornam um URL que aponta para a página da política de devolução, em vez de dados estruturados. Os agentes de IA não conseguem analisar HTML para extrair os termos da política.
A correção: Retorne um objeto returnPolicy estruturado com os campos: returnWindowDays (inteiro), returnType ("free" / "paid" / "exchange-only"), conditions (array de strings em linguagem simples). Isso permite que os agentes informem com precisão os usuários sobre os termos de devolução antes da confirmação da compra.
Erro #7: Limitação de taxa definida de forma muito agressiva
O problema: Os comerciantes definem limites de taxa nos endpoints UCP para proteger sua infraestrutura. Limites de 10 requisições/minuto podem parecer razoáveis para navegadores humanos, mas são inadequados para agentes de IA, que podem fazer requisições sequenciais rápidas para comparar produtos ou verificar o inventário em várias categorias.
A correção: Diferencie os limites de taxa por tipo de endpoint. As leituras de catálogo podem ser servidas do cache com limites generosos (mais de 100 requisições/minuto). Os endpoints de checkout devem ter limites mais rígidos (10–30/minuto), pois envolvem reserva de inventário. Implemente respostas HTTP 429 adequadas com cabeçalhos Retry-After para que os agentes possam recuar graciosamente em vez de falhar.
Erro #8: Problemas de certificado HTTPS no subdomínio UCP
O problema: Muitos comerciantes hospedam endpoints UCP em um subdomínio (por exemplo, api.yourstore.com) com um certificado SSL gerenciado separadamente. Certificados expirados, SANs mal configurados ou certificados intermediários ausentes fazem com que os agentes rejeitem seus endpoints como não confiáveis.
A correção: Use a renovação automática de certificados (Let's Encrypt com certbot, ou certificados gerenciados pelo seu provedor de CDN). Configure alertas de monitoramento para certificados que expiram em 30 dias. Teste seu subdomínio UCP com SSL Labs regularmente.
Erro #9: Confirmação de checkout não retornada em tempo real
O problema: Seu endpoint POST /ucp/v1/checkout enfileira o pedido para processamento e retorna uma resposta 202 Accepted, esperando que o agente faça polling para confirmação. Muitos agentes interpretam qualquer coisa diferente de um 200 OK síncrono com um ID de pedido como uma falha.
A correção: Processe o checkout de forma síncrona e retorne uma resposta 200 com um objeto de pedido completo (ID do pedido, entrega estimada, número de confirmação) em 3 segundos. Se seu backend exigir processamento assíncrono, implemente uma etapa de pré-validação síncrona rápida que retorne um ID de pedido otimista e, em seguida, atualize via webhook.
Erro #10: Não testar com o conjunto de testes oficial do UCP
O problema: Os desenvolvedores testam os endpoints UCP com comandos curl manuais ou Postman, não com o conjunto de testes de certificação oficial do UCP. Esses testes manuais perdem casos de borda que a especificação define: requisições malformadas, payloads parciais, tratamento de tempo limite, tentativas de checkout concorrentes.
A correção: Execute o conjunto de testes oficial do UCP (disponível em ucp.dev/testing) em seu ambiente de staging antes e depois de cada lançamento. Adicione o conjunto de testes ao seu pipeline de CI/CD. A certificação UCP é cada vez mais referenciada pelos principais provedores de agentes de IA como um sinal de confiança, manter o status de certificação é importante.