Como adicionar disponibilidade para integrações de pedidos de varejo v1

Este tutorial mostra o seguinte:

  1. Uma descrição de alto nível de como a disponibilidade é mostrada ao usuário e que tipo de dados são necessários
  2. Instruções específicas sobre como codificar os dados de disponibilidade nos action_link dos seus feeds
  3. Instruções sobre como atualizar essa disponibilidade ao longo do dia
  4. Expectativas quanto à precisão da disponibilidade

Além dos metadados de disponibilidade, também é esperado que você forneça metadados sobre as taxas associadas à entrega ou retirada, além dos valores mínimos do pedido. Para ver uma amostra completa de feed que mostra o uso da disponibilidade, além de taxas e pedidos mínimos, consulte Amostra de feed de pedidos de varejo v1.

Informações de disponibilidade necessárias

A disponibilidade do pedido de varejo para essa experiência é coletada em nível de granularidade por dia. Esses dados de disponibilidade são exibidos aos usuários junto com as taxas e os valores mínimos do pedido, com uma mensagem como "Disponível hoje", "Disponível amanhã" ou "DD/MM disponível" com base na data mais antiga disponível.

Ao enviar esses dados nos feeds, você envia as datas futuras que têm disponibilidade e o horário mais recente em que o usuário pode fazer um pedido e programar a retirada ou a entrega para cada data. Essas duas informações são a data de fulfillment e o horário da última ordem.

Por exemplo: se a data de hoje for 23 de março de 2021 e houver disponibilidade para entrega amanhã, desde que o usuário faça o pedido hoje às 16h, os dados que você forneceria para representar essa disponibilidade serão os seguintes:

  • Data de entrega: 24/03/2021
  • Horário do último pedido: 23/03/2021 16:00

Como o horário do último pedido está incluído, após esse período, o front-end do Google será atualizado automaticamente para a próxima data disponível, após o último horário de pedido.

Todos os dias, ao fazer upload de um novo feed do comerciante, serão necessários novos dados de disponibilidade. Como o front-end só exibe a disponibilidade atual, é necessário fornecer somente as próximas três a cinco datas de disponibilidade para qualquer local. Isso permite que o front-end exiba a disponibilidade atual, bem como a próxima disponibilidade a ser exibida após o último horário de pedido.

Como especificar a disponibilidade usando feeds

A disponibilidade de links de ação está incluída na mensagem action_link do feed do comerciante, como parte do campo order_online_metadata. Para cada comerciante e cada opção de atendimento do pedido, há uma lista de mensagens AvailableDay no caminho 

Merchant.action_link.order_online_metadata.fulfillment_option.available_day

Essas mensagens precisam estar neste formato:

{
  "fulfillment_date": {
    "year": "2020",
    "month": "10",
    "day": "1"
  },
  "last_ordering_time":  {
    "seconds": "1601614800"  // 2020/10/1, 10pm
  }
}

Nesse formato, o fulfillment_date é o ano, o mês e o dia que têm disponibilidade. Essa data deve se referir ao local especificado pelo comerciante.

last_ordering_time é um carimbo de data/hora Unix em segundos. Ela é independente do fuso horário e marca o último momento em que o comerciante pode receber pedidos na data fornecida em fulfillment_date. O último pedido pode ser a qualquer momento antes ou durante a data de atendimento do pedido. Depois que o tempo do último pedido terminar, o Google deixará de mostrar automaticamente a disponibilidade para a data de atendimento em questão e passará a mostrar a disponibilidade com base na próxima data de atendimento disponível.

Para a definição de referência de order_online_metadata, consulte a referência do feed do comerciante. Para ver uma amostra de feed que inclui disponibilidade no formato JSON, consulte Amostra de feed: ordem de varejo + metadados.

Como atualizar a disponibilidade com atualizações em tempo real

Se a disponibilidade de um local para entrega ou retirada mudar entre os horários em que você envia um feed diário, a API REST de atualização em tempo real pode ser usada para atualizar a disponibilidade exibida aos usuários.

As atualizações são feitas para um único comerciante por vez. Ao fazer uma atualização, você especifica o comerciante a ser atualizado e os campos que precisam ser atualizados como parte do endpoint da API. No corpo da solicitação, serão incluídos os novos dados para esses campos. Os campos atualizados serão substituídos pelas informações fornecidas.

Para atualizar a disponibilidade, faça uma solicitação de patch para o seguinte endpoint:

PATCH https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}?updateMask=action_link

O corpo da solicitação seria um objeto do comerciante com apenas o action_link incluído, já que definimos o updateMask para incluir apenas o action_link:

{
  "action_link": [
    ..., // all required action_link fields here
    "order_online_metadata": {
      "fulfillment_option": [
        "fulfillment_type": "FULFILLMENT_TYPE_DELIVERY",
        "available_day": [ // Include the updated availability here
          {
            "fulfillment_date": {
              "year": "2020",
              "month": "10",
              "day": "1"
            }
            "last_ordering_time": {
              "seconds": "1601614800"  // 2020/10/1, 10pm
            }
          },
          ... // Other updated availability_days
        ]
      ]
    }
  ]
}

Se a solicitação da API for bem-sucedida, a resposta incluirá o objeto do comerciante com os dados atualizados recentemente.

Para uma especificação de referência completa do método de atualização do comerciante, consulte Método: Inventory.partners.merchants.patch.

Precisão de disponibilidade

O Reservar com o Google entende que as especificidades da disponibilidade mudam de acordo com vários fatores. Entre esses fatores estão:

  • Mudanças na disponibilidade baseadas no tamanho do pedido
  • Mudanças na disponibilidade com base no tempo para concluir o pedido e a finalização da compra
  • Latência entre a atualização das alterações de disponibilidade, seja por feeds ou atualizações em tempo real

Qualquer um desses fatores pode levar a situações em que a disponibilidade exibida ao usuário inicialmente não é a disponibilidade final que ele verá ao finalizar a compra. O objetivo da implementação de disponibilidade não é eliminá-las completamente, mas fornecer informações claras aos usuários com a maior frequência possível.

Espera-se que os parceiros forneçam uma implementação que leve à precisão da disponibilidade exibida aos usuários com a maior frequência possível de acordo com o melhor esforço. Além disso, se a disponibilidade mudar devido aos detalhes do pedido, isso vai ser mostrado claramente aos usuários. Se você não tiver certeza do que é necessário no seu caso, fale com seu contato do Reservar com o Google.