Visão geral da finalização de compra nativa

Para permitir que os usuários finalizem a compra, implemente a integração de finalização de compra nativa. Isso envolve a criação de uma API REST padrão que permite que o Google gerencie de maneira programática o fluxo de finalização da compra com seus servidores. Esse método oferece a experiência mais integrada para os usuários. Inicialmente, o Google vai renderizar a interface do usuário para o comprador, com planos futuros de oferecer suporte a mais experiências de agente.

Fluxo de finalização da compra

A integração nativa exige que você crie uma API RESTful que o Google possa chamar para criar e gerenciar sessões de finalização da compra.

O fluxo geral é o seguinte:

  1. Criar sessão de finalização da compra:o usuário e, opcionalmente, um agente estão em um loop adicionando itens à sessão.
  2. Transferência para uma interface do Google:quando o usuário decide finalizar a compra, o agente (se envolvido) transfere o controle para uma interface do Google (transmitindo os dados da sessão de finalização da compra).
  3. Finalização da compra manual:o usuário agora interage apenas com a interface do Google para preencher detalhes confidenciais de atendimento e pagamento e enviar o pedido. O agente não está envolvido nessa parte, garantindo o determinismo.
  4. Conclusão e retorno:a interface do Google mostra uma página de agradecimento para confirmar o pedido. Opcionalmente, o usuário pode ser redirecionado de volta ao agente, que já pode ter sido notificado da compra concluída.

Ciclo de vida do status da sessão de finalização da compra

À medida que o usuário avança no fluxo de finalização da compra, você precisa atualizar o status da sessão para refletir o estado atual. A sessão passa pelo seguinte ciclo de vida:

  • incomplete:o status inicial quando uma sessão é criada. Isso indica que informações obrigatórias (como métodos de envio, impostos ou detalhes do usuário) estão ausentes ou não calculadas.
  • ready_for_payment:o status a ser usado depois que o usuário atualizar o endereço de entrega e você calcular as opções e os totais de envio, mas antes que o instrumento de pagamento seja finalizado.
  • ready_for_complete:o status a ser usado durante a hidratação completa do objeto de finalização da compra, depois que o instrumento de pagamento for selecionado e todos os detalhes do pedido forem validados.
  • completed:o status final retornado depois que você processar o pagamento e fizer o pedido.
  • canceled:o status retornado se a sessão de finalização da compra for interrompida.
  • error:o status retornado se um erro de lógica de negócios irrecuperável impedir a finalização da compra. Esse status está disponível na versão 2026-04-08 e mais recente do UCP.

Fluxo de finalização da compra de vários itens:

O Google agora oferece suporte a vários itens de linha distintos em uma única sessão de finalização da compra. O fluxo geral é o seguinte:

  1. O usuário inicia a finalização da compra em uma interface ativada pelo UCP (por exemplo, clicando em "Comprar agora" em um produto).
  2. A chamada POST /checkout-sessions é feita, incluindo todos os itens distintos na matriz line_items. A matriz line_items vai conter um objeto separado para cada item exclusivo que está sendo finalizado.
  3. O usuário pode atualizar o instrumento de pagamento, os detalhes de atendimento ou aplicar descontos usando chamadas PUT /checkout-sessions/{id}.
  4. Quando o usuário clica no botão "Pagar com o GPay", a chamada POST /checkout-sessions/{id}/complete é feita.

Autenticação

Para mais detalhes sobre como proteger os endpoints da API Native Checkout, incluindo métodos de autenticação compatíveis, como chaves de API e OAuth 2.0, consulte o guia Autenticação e segurança.

Ferramentas para desenvolvedores

Para ajudar na implementação da API de Checkout Nativo, você pode encontrar os seguintes recursos no repositório do Protocolo de Comércio Universal no GitHub:

  • Repositório do UCP no GitHub: confira o repositório principal para acessar documentação abrangente, especificações e recursos da comunidade.
  • SDKs:use os kits de desenvolvimento de software para acelerar a integração. SDKs específicos de linguagem estão disponíveis, incluindo:

  • Testes de conformidade: valide os endpoints da API em relação à especificação do UCP usando o pacote de testes de conformidade .

    Isso ajuda a garantir que sua implementação atenda aos padrões e comportamentos necessários.

Recomendamos o uso dessas ferramentas para simplificar o processo de desenvolvimento e teste.

Objetivos de nível de serviço

Os seguintes objetivos de nível de serviço (SLOs) se aplicam aos endpoints da API REST Native Checkout. As empresas que fazem a integração com o Google precisam atender a essas metas de desempenho e disponibilidade da API.

Endpoint Disponibilidade Latência (50º percentil) Latência (95º percentil)
POST /checkout-sessions (Criar) >= 95% <= 1 segundo <= 4 segundos
PUT /checkout-sessions/{id} (Atualizar) >= 95% <= 1 segundo <= 5 segundos
POST /checkout-sessions/{id}/complete (Concluir) >= 95% <= 6 segundos <= 10 segundos

A latência do 50º percentil indica que pelo menos 50% das solicitações devem ser concluídas dentro desse período. A latência do 95º percentil indica que pelo menos 95% das solicitações devem ser concluídas dentro desse período.

Próximas etapas

Confira os payloads da API de finalização da compra e os detalhes técnicos de implementação da sua versão do UCP:

Anterior
Authentication
Avançar
Ciclo de vida do pedido (após a compra)