Liens d'action des établissements

Gérez les boutons d'action Google d'un établissement (commande, livraison, vente à emporter, réservation de table, prise de rendez-vous) via Listings API.

Les liens d'action des établissements sont les boutons d'action que Google affiche sur la fiche d'une entreprise : Order online (Commander en ligne), Get delivery (Se faire livrer), Reserve a table (Réserver une table), Book an appointment (Prendre rendez-vous), etc. Listings API les gère au niveau d'un établissement : vous les définissez donc via les mêmes endpoints de création et de mise à jour que vous utilisez déjà, et vous les retrouvez dans les réponses de tous les endpoints de lecture des établissements.

Le champ `placeActionLinks`

La création et la mise à jour acceptent toutes deux un tableau placeActionLinks sur input. Chaque élément :

Champ	Type	Obligatoire	Description
`placeActionType`	enum	oui	L'un des types valides ci-dessous.
`uri`	string	oui	URL de destination.
`isPreferred`	boolean	non	Marque ce lien comme préféré pour son type. Au maximum un lien préféré par type.
`action`	string	non	`add` (par défaut) ou `delete`. Utilisé uniquement lors de la mise à jour.
`name`	string	non	L'identifiant du lien, renvoyé par les endpoints de lecture une fois le lien synchronisé avec Google. Facultatif lors de l'écriture ; incluez-le lorsqu'il est disponible pour cibler le plus précisément possible un lien enregistré.

Valeurs valides pour placeActionType :

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

Comment un lien est identifié (pour modification / suppression) : par name s'il est présent, sinon par placeActionType + uri. Incluez name lorsque vous l'avez obtenu (lors d'une lecture) pour une correspondance aussi précise que possible. Un lien nouvellement ajouté qui n'a pas encore été synchronisé avec Google n'a pas de name ; il est donc identifié par placeActionType + uri.

Actions

Le modèle d'écriture est append/upsert, et non un remplacement. Lors d'une mise à jour, seuls les liens que vous référencez sont concernés ; les liens que vous n'incluez pas restent inchangés.

Action	Objectif	Correspondance
`add`	Ajouter un nouveau lien ou mettre à jour sur place les champs `uri` / `isPreferred` d'un lien enregistré.	`name` s'il est présent, sinon `placeActionType` + `uri`
`delete`	Supprimer un lien enregistré et mettre en file d'attente sa suppression de Google.	`name` s'il est présent, sinon `placeActionType` + `uri`

Pour modifier l'URL d'un lien, supprimez l'ancien lien et ajoutez le nouveau dans la même requête (voir Modifier l'URL d'un lien).

Procédures recommandées

Deux procédures sont prises en charge pour renseigner les liens d'action d'un établissement et les maintenir synchronisés avec Google.

Procédure 1 : créer d'abord dans Google, puis connecter

Le commerçant configure les liens d'action de l'établissement directement dans sa fiche Google Business Profile.
Cet établissement Google Business Profile est connecté à Listings API.
Lors de la connexion, Listings API récupère les liens en ligne sur Google et les intègre à l'ensemble des liens gérés de l'établissement. Vous n'avez pas besoin de les saisir à nouveau via l'API.

Procédure 2 : créer d'abord dans Listings API, puis connecter

Créez l'établissement dans Listings API avec ses liens d'action (créer un établissement), ou ajoutez-les ultérieurement (mettre à jour un établissement).
Lors de la connexion à Google Business Profile, Listings API récupère les liens en ligne et les fusionne avec l'ensemble des liens gérés :
- les liens pour lesquels une correspondance sans ambiguïté est trouvée rejoignent l'ensemble des liens gérés ;
- tout lien présent sur Google qui ne peut pas être fusionné automatiquement (ou qui ne fait tout simplement pas encore partie de l'ensemble des liens gérés) est affiché sous discoveredPlaceActionLinks pour que vous puissiez l'examiner.
À chaque soumission à Google, Listings API vérifie à nouveau les liens en ligne. Tout nouveau lien trouvé directement dans Google Business Profile et que Listings API ne gère pas est ajouté à discoveredPlaceActionLinks.

Liens découverts

Les liens découverts sont des liens d'action associés à un établissement qui existent sur le profil Google de l'entreprise mais ne sont pas gérés dans Listings API. Ils sont récupérés par les processus ci-dessus (liens supplémentaires trouvés lors de la connexion ou nouveaux liens trouvés lors d'un envoi ultérieur) et sont renvoyés séparément de vos liens gérés, sous discoveredPlaceActionLinks (même structure que placeActionLinks), par chaque endpoint de lecture : liste, par identifiants, par codes de magasin et recherche.

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

Adopter un lien découvert

Pour commencer à gérer un lien découvert, envoyez-le à mettre à jour un établissement avec action: "add", en utilisant le même appel que pour ajouter n'importe quel lien (identifié par placeActionType + uri). Les autres liens restent inchangés.

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

Après cette opération, le lien apparaît sous placeActionLinks et est supprimé de discoveredPlaceActionLinks. Un lien découvert que vous n'adoptez pas reste simplement répertorié (et est retiré automatiquement s'il disparaît ensuite de Google) ; aucune action n'est requise.

Exemples

Chaque mise à jour renvoie l'ensemble placeActionLinks complet et actuel de l'établissement (reflétant la modification). Juste après une écriture, les champs name et submissionStatus d'un lien valent null ; ils sont renseignés une fois le lien synchronisé avec Google.

Ajouter un lien

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

Modifier l'URL d'un lien

Une modification d'URL consiste à supprimer l'ancien lien et à ajouter le nouveau dans la même requête. Si l'ancien lien a été synchronisé avec Google, incluez son name dans delete pour obtenir la correspondance la plus précise possible ; sinon, placeActionType + uri est utilisé.

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

Pour modifier uniquement isPreferred (en conservant la même URL), renvoyez le lien avec action: "add" et la nouvelle valeur.

Supprimer un lien

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

Créer un établissement avec des liens

Lors de la création, chaque lien est nouveau, donc action prend par défaut la valeur 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" }      ]    }  }'

Remarques

Au maximum un lien préféré par type.
Le champ submissionStatus d'un lien reflète la dernière synchronisation avec Google (success, failed, etc.), avec un champ submissionMessage lisible par un humain.
Google applique les liens d'action associés à un établissement uniquement aux établissements validés.