Enlaces de acción de la ubicación

Gestiona los botones de acción de Google de una ubicación (pedidos, entrega a domicilio, comida para llevar, reservas y citas) a través de Listings API.

Los enlaces de acción de la ubicación son los botones de acción que Google muestra en el perfil de un negocio: Order online (Pedir en línea), Get delivery (Solicitar entrega a domicilio), Reserve a table (Reservar una mesa), Book an appointment (Reservar una cita), etc. Listings API los gestiona como parte de una ubicación, por lo que los configuras a través de los mismos endpoints de creación y actualización que ya utilizas, y los recuperas en todos los endpoints de lectura de ubicaciones.

El campo `placeActionLinks`

Tanto la creación como la actualización aceptan un array placeActionLinks en input. Cada elemento:

Campo	Tipo	Obligatorio	Descripción
`placeActionType`	enum	sí	Uno de los tipos válidos que se indican a continuación.
`uri`	string	sí	URL de destino.
`isPreferred`	boolean	no	Marca este enlace como preferido para su tipo. Como máximo, un enlace preferido por tipo.
`action`	string	no	`add` (el valor predeterminado) o `delete`. Solo se utiliza en la actualización.
`name`	string	no	El identificador del enlace, que devuelven los endpoints de lectura una vez que el enlace se ha sincronizado con Google. Es opcional en las operaciones de escritura; inclúyelo cuando esté disponible para identificar con la mayor precisión posible un enlace guardado específico.

Valores válidos de placeActionType:

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

Cómo se identifica un enlace (para editarlo o eliminarlo): por name si está presente; de lo contrario, por placeActionType + uri. Incluye name cuando lo tengas (obtenido de una lectura) para identificarlo con la mayor precisión posible. Un enlace recién añadido que aún no se ha sincronizado con Google no tiene name, por lo que se identifica por placeActionType + uri.

Acciones

El modelo de escritura es append/upsert, no de reemplazo. En una actualización, solo se ven afectados los enlaces que indiques; los enlaces que no incluyas permanecen sin cambios.

Acción	Propósito	Criterio de coincidencia
`add`	Añadir un enlace nuevo o actualizar `uri` / `isPreferred` de un enlace guardado en el mismo registro.	`name` si está presente; de lo contrario, `placeActionType` + `uri`
`delete`	Eliminar un enlace guardado y poner en cola su eliminación de Google.	`name` si está presente; de lo contrario, `placeActionType` + `uri`

Para cambiar la URL de un enlace, elimina el antiguo y añade el nuevo en la misma solicitud (consulta Cambiar la URL de un enlace).

Flujos recomendados

Hay dos formas admitidas de incorporar los enlaces de acción de una ubicación y mantenerlos sincronizados con Google.

Flujo 1: crear primero en Google y después conectar

El comerciante configura los enlaces de acción de la ubicación directamente en su Google Business Profile.
Esa ubicación de Google Business Profile se conecta a Listings API.
Al establecer la conexión, Listings API recupera los enlaces activos de Google y los incorpora al conjunto de enlaces gestionados de la ubicación. No necesitas volver a introducirlos a través de la API.

Flujo 2: crear primero en Listings API y después conectar

Crea la ubicación en Listings API con sus enlaces de acción (crear una ubicación) o añádelos más adelante (actualizar una ubicación).
Al conectarse a Google Business Profile, Listings API obtiene los enlaces activos y los combina con el conjunto de enlaces gestionados:
- los enlaces que coinciden sin ambigüedad se incorporan al conjunto de enlaces gestionados;
- cualquier enlace de Google que no se pueda combinar automáticamente (o que simplemente aún no esté en el conjunto de enlaces gestionados) se muestra en discoveredPlaceActionLinks para que lo revises.
En cada envío a Google, Listings API vuelve a comprobar los enlaces activos. Cualquier enlace nuevo que se encuentre directamente en Google Business Profile y que Listings API no gestione se añade a discoveredPlaceActionLinks.

Enlaces descubiertos

Los enlaces descubiertos son enlaces de acción del lugar que existen en el perfil de Google del negocio, pero no se gestionan en Listings API. Los flujos anteriores los incorporan (enlaces adicionales encontrados al conectar o enlaces nuevos encontrados en un envío posterior) y todos los endpoints de lectura los devuelven por separado de tus enlaces gestionados, en discoveredPlaceActionLinks (con la misma estructura que placeActionLinks): listar, por IDs, por códigos de tienda y buscar.

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

Adoptar un enlace descubierto

Para empezar a gestionar un enlace descubierto, envíalo a actualizar una ubicación con action: "add", mediante la misma llamada que se usa para añadir cualquier enlace (identificado por placeActionType + uri). Los demás enlaces no se modifican.

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

Después de esto, el enlace aparece en placeActionLinks y se elimina de discoveredPlaceActionLinks. Un enlace descubierto que no adoptes simplemente sigue apareciendo en la lista (y se elimina de ella automáticamente si más adelante desaparece de Google); no es necesario hacer nada.

Ejemplos

Cada actualización devuelve el conjunto placeActionLinks completo y actual de la ubicación (que refleja el cambio). Justo después de una escritura, los campos name y submissionStatus de un enlace tienen el valor null; se rellenan cuando el enlace se sincroniza con Google.

Añadir un enlace

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

Cambiar la URL de un enlace

Un cambio de URL consiste en eliminar el enlace antiguo y añadir el nuevo en la misma solicitud. Si el enlace antiguo se ha sincronizado con Google, incluye su name en delete para obtener la coincidencia más precisa; de lo contrario, se usa 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 cambiar solo isPreferred (con la misma URL), vuelve a enviar el enlace con action: "add" y el nuevo valor.

Eliminar un enlace

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

Crear una ubicación con enlaces

Al crear una ubicación, todos los enlaces son nuevos, por lo que action tiene el valor predeterminado 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" }      ]    }  }'

Notas

Como máximo, un enlace preferido por tipo.
El campo submissionStatus de un enlace refleja la última sincronización con Google (success, failed, etc.), con un submissionMessage legible para las personas.
Google aplica los enlaces de acción del lugar solo a las ubicaciones verificadas.