Links de ação do local

Gerencie os botões de ação de um local no Google (pedidos, entrega, retirada, reserva, agendamento) por meio da Listings API.

Os links de ação do local são os botões de ação que o Google exibe no perfil de uma empresa: Order online (Pedir on-line), Get delivery (Solicitar entrega), Reserve a table (Reservar uma mesa), Book an appointment (Agendar um horário) e assim por diante. A Listings API os gerencia como parte de um local, então você os configura pelos mesmos endpoints de criação e atualização que já usa e os consulta em todos os endpoints de leitura de locais.

O campo `placeActionLinks`

Tanto a criação quanto a atualização aceitam um array placeActionLinks em input. Cada elemento:

Campo	Tipo	Obrigatório	Descrição
`placeActionType`	enum	sim	Um dos tipos válidos abaixo.
`uri`	string	sim	URL de destino.
`isPreferred`	boolean	não	Marca este link como preferencial para seu tipo. No máximo um preferencial por tipo.
`action`	string	não	`add` (o padrão) ou `delete`. Usado apenas na atualização.
`name`	string	não	O identificador do link, retornado pelos endpoints de leitura após a sincronização do link com o Google. Opcional na gravação; inclua-o quando disponível para identificar um link salvo específico com a maior precisão possível.

Valores válidos de placeActionType:

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

Como um link é identificado (para edição / exclusão): por name, se presente; caso contrário, por placeActionType + uri. Inclua name quando você o tiver (obtido em uma leitura) para uma correspondência mais precisa. Um link recém-adicionado que ainda não foi sincronizado com o Google não tem name, então é identificado por placeActionType + uri.

Ações

O modelo de gravação é append/upsert, não substituição. Na atualização, apenas os links que você referencia são afetados; os links que você não inclui permanecem inalterados.

Ação	Finalidade	Correspondência
`add`	Adicionar um novo link ou atualizar `uri` / `isPreferred` de um link salvo, sem substituí-lo.	`name`, se presente; caso contrário, `placeActionType` + `uri`
`delete`	Remover um link salvo e colocar sua remoção do Google na fila.	`name`, se presente; caso contrário, `placeActionType` + `uri`

Para alterar a URL de um link, remova o antigo e adicione o novo na mesma requisição (consulte Alterar a URL de um link).

Fluxos recomendados

Há duas maneiras compatíveis de preencher os links de ação de um local e mantê-los sincronizados com o Google.

Fluxo 1: criar primeiro no Google e depois conectar

O comerciante configura os links de ação do local diretamente no próprio Google Business Profile.
Esse local do Google Business Profile é conectado à Listings API.
Ao conectar, a Listings API importa os links ativos do Google para o conjunto gerenciado do local. Você não precisa inseri-los novamente pela API.

Fluxo 2: criar primeiro na Listings API e depois conectar

Crie o local na Listings API com seus links de ação (criar um local) ou adicione-os depois (atualizar um local).
Ao conectar ao Google Business Profile, a Listings API busca os links ativos e os mescla com o conjunto gerenciado:
- os links com correspondência inequívoca passam a integrar o conjunto gerenciado;
- qualquer link que o Google tenha e que não possa ser mesclado automaticamente (ou que simplesmente ainda não esteja no conjunto gerenciado) é exibido em discoveredPlaceActionLinks para você analisar.
A cada envio ao Google, a Listings API verifica novamente os links ativos. Qualquer link novo encontrado diretamente no Google Business Profile que a Listings API não gerencie é adicionado a discoveredPlaceActionLinks.

Links descobertos

Links descobertos são links de ação do local que existem no perfil da empresa no Google, mas não são gerenciados na Listings API. Eles são importados pelos fluxos acima (links adicionais encontrados na conexão ou novos links encontrados em um envio posterior) e são retornados separadamente dos links que você gerencia, em discoveredPlaceActionLinks (com a mesma estrutura de placeActionLinks), por todos os endpoints de leitura: listar, por IDs, por códigos de loja e pesquisar.

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    }  ]}

Adotar um link descoberto

Para começar a gerenciar um link descoberto, envie-o para atualizar um local com action: "add", usando a mesma chamada usada para adicionar qualquer link (identificado por placeActionType + uri). Os outros links permanecem inalterados.

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" }      ]    }  }'

Depois disso, o link aparece em placeActionLinks e é removido de discoveredPlaceActionLinks. Um link descoberto que você não adotar simplesmente permanece listado (e é removido automaticamente se depois desaparecer do Google); nenhuma ação é necessária.

Exemplos

Cada atualização retorna o conjunto placeActionLinks completo e atual do local (refletindo a alteração). Logo após uma gravação, os campos name e submissionStatus de um link têm o valor null; eles são preenchidos assim que o link é sincronizado com o Google.

Adicionar um 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" }      ]    }  }'

Alterar a URL de um link

Uma alteração de URL consiste em remover o link antigo e adicionar o novo, na mesma requisição. Se o link antigo já tiver sido sincronizado com o Google, inclua seu name em delete para obter a correspondência mais precisa; caso contrário, será usada a combinação 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" }      ]    }  }'

Para alterar apenas isPreferred (mantendo a mesma URL), reenvie o link com action: "add" e o novo valor.

Remover um 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" }      ]    }  }'

Criar um local com links

Na criação, todos os links são novos, então action assume o valor padrão 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" }      ]    }  }'

Observações

No máximo um link preferencial por tipo.
O campo submissionStatus de um link reflete a última sincronização com o Google (success, failed e assim por diante), com um submissionMessage legível por humanos.
O Google aplica links de ação do local apenas a locais verificados.