Aggiunta della disponibilità per le integrazioni v1 di Ordinazione retail

Questo tutorial illustra:

  1. Una descrizione generale di come viene mostrata all'utente la disponibilità e del tipo di dati richiesti
  2. Istruzioni specifiche su come codificare i dati sulla disponibilità negli attributi action_link nei feed
  3. Istruzioni su come aggiornare la disponibilità se cambia nel corso della giornata
  4. Aspettative relative all'accuratezza della disponibilità

Oltre ai metadati sulla disponibilità, devi fornire anche i metadati sulle tariffe associate a consegna o ritiro, nonché gli importi minimi degli ordini. Per un esempio di feed completo che mostra l'utilizzo della disponibilità, le commissioni e gli ordini minimi, consulta l'esempio di feed V1 al dettaglio.

Informazioni necessarie sulla disponibilità

La disponibilità degli ordini retail per questa esperienza viene raccolta con granularità a livello di giorno. Questi dati sulla disponibilità vengono mostrati agli utenti insieme alle tariffe e agli importi minimi degli ordini con un messaggio come "Disponibile oggi", "Disponibile domani" o "Disponibile DD/MM" in base alla prima data disponibile.

Quando invii questi dati nei feed, invierai date future disponibili e l'ultimo orario in cui un utente potrebbe effettuare un ordine e pianificare il ritiro o la consegna per ogni data. Queste due informazioni riguardano rispettivamente la data di evasione e l'ora dell'ultimo ordine.

Ad esempio, se la data di oggi è il 23 marzo 2021 e domani è disponibile la consegna, a condizione che gli utenti ordinino oggi alle 16:00, i dati che forniresti per rappresentare questa disponibilità sono:

  • Data di evasione: 24/03/2021
  • Ora dell'ultimo ordine: 23/03/2021 16:00

Poiché l'orario dell'ultimo ordine è incluso, trascorso il periodo di tempo in cui è stato effettuato l'ultimo ordine, il front-end di Google verrà aggiornato automaticamente alla data disponibile successiva.

Ogni giorno, quando carichi un nuovo feed commerciante, devono essere inclusi nuovi dati sulla disponibilità. Poiché il front-end mostra solo la disponibilità attuale, è necessario fornire soltanto le prossime 3-5 date di disponibilità per una determinata località. Ciò consente al front-end di mostrare la disponibilità attuale e la disponibilità successiva da mostrare dopo il termine dell'ultimo ordine.

Specificare la disponibilità tramite i feed

La disponibilità dei link di azione è inclusa nel messaggio action_link del feed del commerciante, come parte del campo order_online_metadata. Per ciascun commerciante e ciascuna opzione di evasione degli ordini, è presente un elenco di messaggi AvailableDay lungo il percorso 

Merchant.action_link.order_online_metadata.fulfillment_option.available_day

Questi messaggi devono essere nel seguente formato:

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

In questo formato, il fulfillment_date è l'anno, il mese e il giorno disponibile. Questa data deve fare riferimento alla località specificata da questo commerciante.

last_ordering_time è un timestamp unix in secondi. Il fuso orario è indipendente e indica l'ultimo momento in cui il commerciante può effettuare ordini per la data specificata in fulfillment_date. L'ultimo orario di ordinamento può essere precedente o durante la data di evasione. Una volta trascorso il tempo dell'ultimo ordine, Google interromperà automaticamente la visualizzazione della disponibilità per la data di evasione specificata e inizierà a mostrare la disponibilità in base alla successiva data di evasione disponibile.

Per la definizione di riferimento di order_online_metadata, consulta la sezione Riferimento del feed del commerciante. Per un esempio di feed che include la disponibilità in formato JSON, consulta la pagina Esempi di feed Ordinamento retail + Metadati.

Aggiornamento della disponibilità con aggiornamenti in tempo reale

Se la disponibilità di un luogo per la consegna o il ritiro cambia tra l'invio di un feed giornaliero, la versione in tempo reale dell'API REST può essere utilizzata per aggiornare la disponibilità mostrata agli utenti.

Gli aggiornamenti vengono effettuati per un singolo commerciante alla volta. Quando esegui un aggiornamento, devi specificare il commerciante da aggiornare e i campi che devono essere aggiornati come parte dell'endpoint API. Nel corpo della richiesta includerai i nuovi dati per questi campi. Eventuali campi in fase di aggiornamento verranno sostituiti con le informazioni fornite.

Per aggiornare la disponibilità, dovrai inviare una richiesta di patch al seguente endpoint:

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

Il corpo della richiesta sarà quindi un oggetto Merchant con solo action_link incluso (poiché abbiamo impostato updateMask per includere solo 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 la richiesta API viene soddisfatta, la risposta includerà l'oggetto Merchant con i dati appena aggiornati.

Per una specifica di riferimento completa del metodo di aggiornamento del commerciante, consulta: Metodo: inventory.partners.merchants.patch.

Precisione della disponibilità

Prenota con Google comprende che le specifiche della disponibilità cambiano in base a una serie di fattori. Questi fattori includono:

  • Modifiche alla disponibilità in base alle dimensioni dell'ordine
  • Modifiche alla disponibilità in base al tempo necessario per completare l'ordine e il pagamento
  • Latenza tra l'aggiornamento delle modifiche della disponibilità, tramite feed o aggiornamenti in tempo reale

Uno di questi fattori può portare a situazioni in cui la disponibilità mostrata all'utente inizialmente non è quella finale che verrà visualizzata al momento del pagamento. Lo scopo dell'implementazione della disponibilità non è eliminarli completamente, ma fornire informazioni chiare agli utenti il più spesso possibile.

I partner sono tenuti a fornire un'implementazione che consenta di mostrare agli utenti una disponibilità accurata il più spesso possibile, nel miglior modo possibile. Inoltre, se la disponibilità cambia a causa dei dettagli dell'ordine, questa informazione deve essere mostrata chiaramente agli utenti. Se hai dubbi in merito a ciò che è specifico nel tuo caso, rivolgiti al tuo contatto di Prenota con Google.