Link di azione della sede

Gestisci i pulsanti di azione su Google di una sede (ordini, consegna, asporto, prenotazioni di tavoli e appuntamenti) tramite Listings API.

I link di azione della sede sono i pulsanti di azione che Google mostra sul profilo di un'attività: Order online (Ordina online), Get delivery (Richiedi la consegna), Reserve a table (Prenota un tavolo), Book an appointment (Prenota un appuntamento) e così via. Listings API li gestisce come parte di una sede, quindi puoi configurarli tramite gli stessi endpoint di creazione e aggiornamento che usi già e recuperarli tramite ogni endpoint di lettura delle sedi.

Il campo `placeActionLinks`

Sia la creazione sia l'aggiornamento accettano un array placeActionLinks in input. Ogni elemento:

Campo	Tipo	Obbligatorio	Descrizione
`placeActionType`	enum	sì	Uno dei tipi validi elencati di seguito.
`uri`	string	sì	URL di destinazione.
`isPreferred`	boolean	no	Contrassegna questo link come preferito per il suo tipo. Al massimo un link preferito per tipo.
`action`	string	no	`add` (il valore predefinito) o `delete`. Usato solo in fase di aggiornamento.
`name`	string	no	L'identificatore del link, restituito dagli endpoint di lettura una volta che il link è stato sincronizzato con Google. Facoltativo in fase di scrittura; includilo quando è disponibile per individuare con la massima precisione uno specifico link salvato.

Valori validi di placeActionType:

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

Come viene individuata la corrispondenza di un link (per la modifica o l'eliminazione): tramite name, se presente, altrimenti tramite placeActionType + uri. Includi name quando lo hai a disposizione (da una lettura) per ottenere la corrispondenza più precisa. Un link appena aggiunto che non è ancora stato sincronizzato con Google non ha un name, quindi la corrispondenza viene individuata tramite placeActionType + uri.

Azioni

Il modello di scrittura è append/upsert, non di sostituzione. In fase di aggiornamento, vengono interessati solo i link a cui fai riferimento; i link che non includi rimangono invariati.

Azione	Scopo	Corrispondenza
`add`	Aggiungi un nuovo link oppure aggiorna `uri` / `isPreferred` di un link salvato senza sostituirlo.	`name` se presente, altrimenti `placeActionType` + `uri`
`delete`	Rimuovi un link salvato e metti in coda la sua rimozione da Google.	`name` se presente, altrimenti `placeActionType` + `uri`

Per modificare l'URL di un link, rimuovi il vecchio link e aggiungi quello nuovo nella stessa richiesta (vedi Modificare l'URL di un link).

Flussi consigliati

Sono supportate due modalità per inserire i link di azione di una sede e mantenerli sincronizzati con Google.

Flusso 1: crea prima in Google, poi collega

Il titolare dell'attività configura i link di azione della sede direttamente nel proprio Google Business Profile.
La sede di quel Google Business Profile viene collegata a Listings API.
Al momento del collegamento, Listings API recupera i link attivi da Google e li inserisce nell'insieme dei link gestiti della sede. Non è necessario reinserirli tramite l'API.

Flusso 2: crea prima in Listings API, poi collega

Crea la sede in Listings API con i suoi link di azione (crea una sede), oppure aggiungili in seguito (aggiorna una sede).
Al momento del collegamento a Google Business Profile, Listings API recupera i link attivi e li unisce all'insieme dei link gestiti:
- i link per i quali viene trovata una corrispondenza univoca entrano a far parte dell'insieme dei link gestiti;
- qualsiasi link presente su Google che non può essere unito automaticamente (o che semplicemente non è ancora nell'insieme dei link gestiti) viene mostrato in discoveredPlaceActionLinks per consentirti di esaminarlo.
A ogni invio a Google, Listings API ricontrolla i link attivi. Qualsiasi nuovo link trovato direttamente in Google Business Profile che Listings API non gestisce viene aggiunto a discoveredPlaceActionLinks.

Link rilevati

I link rilevati sono link per le azioni sulla sede che esistono sul profilo Google dell'attività ma non sono gestiti in Listings API. Vengono importati tramite i flussi descritti sopra (link aggiuntivi trovati durante il collegamento o nuovi link trovati durante un invio successivo) e vengono restituiti separatamente dai link che gestisci, sotto discoveredPlaceActionLinks (con la stessa struttura di placeActionLinks), da ogni endpoint di lettura: elenco, per ID, per codici negozio e ricerca.

JSON

{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

Prendi in gestione un link rilevato

Per iniziare a gestire un link rilevato, invialo a aggiornare una sede con action: "add", usando la stessa chiamata utilizzata per aggiungere qualsiasi link (identificato da placeActionType + uri). Gli altri link rimangono invariati.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

Dopo questa operazione, il link compare sotto placeActionLinks e viene rimosso da discoveredPlaceActionLinks. Un link rilevato che non prendi in gestione rimane semplicemente nell'elenco (e viene rimosso automaticamente se in seguito scompare da Google); non è richiesta alcuna azione.

Esempi

Ogni aggiornamento restituisce l'insieme placeActionLinks della sede completo e attuale (che riflette la modifica). Subito dopo una scrittura, name e submissionStatus di un link sono null; vengono popolati quando il link viene sincronizzato con Google.

Aggiungi un link

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

Modifica l'URL di un link

La modifica di un URL consiste nella rimozione del vecchio link e nell'aggiunta di quello nuovo, nella stessa richiesta. Se il vecchio link è stato sincronizzato con Google, includi il suo name in delete per ottenere la corrispondenza più precisa; altrimenti viene usata la combinazione placeActionType + uri.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

Per modificare solo isPreferred (mantenendo lo stesso URL), invia nuovamente il link con action: "add" e il nuovo valore.

Rimuovi un link

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

Crea una sede con link

Al momento della creazione, ogni link è nuovo, quindi action assume per impostazione predefinita il valore add.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

Note

Al massimo un link preferito per tipo.
Il valore submissionStatus di un link riflette l'ultima sincronizzazione con Google (success, failed e così via), con un submissionMessage leggibile da una persona.
Google applica i link per le azioni sulla sede solo alle sedi verificate.