Implementação da API Cart

Este guia fornece a referência técnica da API e os esquemas de payload para integrar a API Cart do Protocolo de Comércio Universal (UCP) na versão 2026-04-08.

Antes de criar seus endpoints, revise a visão geral da API Cart para conhecer os conceitos e pré-requisitos de alto nível.

Criar carrinho

Esse endpoint permite a criação de uma nova sessão de carrinho. Para fazer a integração, implemente o endpoint CreateCart (POST /carts). Quando um usuário opta por transferir o carrinho, o Google chama esse endpoint com todos os detalhes dos itens de linha. Seu sistema precisa responder com um continue_url direcionando o usuário ao carrinho preenchido previamente no seu site.

• Endpoint: POST /carts
• Gatilho:uma única solicitação CreateCart (POST /carts) é acionada somente quando o usuário clica no botão de transferência (por exemplo, Finalizar compra na loja) para transferir o carrinho para sua loja.

Fluxo do carrinho

O fluxo e o estado do carrinho funcionam da seguinte maneira:

• Acúmulo no Google:quando um usuário adiciona itens ao carrinho, o Google os acumula localmente. O Google não dispara várias chamadas de API à medida que os itens são adicionados.
• O payload:a única solicitação POST /carts vai conter a matriz completa de todos os line_items acumulados de uma só vez.
• Redirecionamento e estado:o back-end do comerciante responde com um continue_url que aponta para o carrinho pré-preenchido no site.

Solicitação:o Google envia a matriz de line_items para ser adicionada ao carrinho.

Exemplo de solicitação:

{
  "line_items": [
    {
      "item": {
        "id": "item_123"
      },
      "quantity": 2
    }
  ]
}

Resposta:você retorna a sessão do carrinho inicializada, incluindo detalhes do item de linha, totais e um continue_url. O campo continue_url na resposta precisa direcionar o usuário de volta a uma página do seu site em que ele possa continuar gerenciando o carrinho. Normalmente, ele é vinculado ao carrinho ou à página de finalização da compra com a sessão identificada por id pré-carregada.

Exemplo de resposta:

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.cart": [{"version": "2026-04-08"}]
    }
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "total",
      "amount": 5000,
      "display_text": "Estimated total (taxes calculated at checkout)"
    }
  ],
  // Used for redirecting the user back to the merchant's cart experience from Google surfaces.
  "continue_url": "https://business.example.com/checkout?cart=cart_abc123",
  // Indicate the timestamp at which the cart session will expire and become invalid.
  "expires_at": "2026-01-16T12:00:00Z"
}

Tratamento de erros

Para conferir diretrizes completas sobre como formatar mensagens de erro e a distinção entre erros de protocolo e de lógica de negócios, consulte os Códigos de erro.