Listings APIListings API
Se connecter

Comptes connectés

Connectez des comptes Google, Facebook et Apple Business Connect, liez leurs fiches aux établissements et déconnectez-les via client.connected_accounts.

Toutes les méthodes relatives aux comptes connectés se trouvent sous client.connected_accounts. Un compte connecté correspond à un compte Google Business Profile, Facebook Pages ou Apple Business Connect qui a autorisé la plateforme et qui est identifié par un connectedAccountId obtenu via connected_accounts.list.

Il existe deux façons de se connecter. Le processus de connexion groupée autorise l'accès à un compte entier sur une plateforme de publication, puis associe ses fiches à vos établissements. Le processus pour un seul établissement crée un lien OAuth pour un établissement, ce qui convient lorsque votre application connecte les magasins un par un. Les méthodes qui prennent un location_id acceptent les identifiants numériques ou encodés en base64, voir Identifiants des établissements.

Processus d'association

Après une connexion groupée, les fiches de la plateforme de publication ne sont pas encore liées à vos établissements. Appelez trigger_matches pour mettre la tâche d'association en file d'attente, interrogez régulièrement details jusqu'à ce que requestMatchesStatus indique MATCH_COMPLETED, consultez les associations avec suggestions, puis validez celles que vous souhaitez conserver avec confirm_matches. Si vous omettez trigger_matches, suggestions reste vide.

connected_accounts.connect_google

Créez une URL qui autorise l'accès à un compte Google Business Profile entier. Dirigez l'utilisateur vers cette URL ; il sera ensuite redirigé vers success_url ou error_url. Le lien est valable pendant 24 heures.

Python
client.connected_accounts.connect_google(    success_url: str,    error_url: str,) -> APIObject
Python
link = client.connected_accounts.connect_google(  "https://app.example.com/onboarding/google/done",  "https://app.example.com/onboarding/google/retry",)print(link.url)

Renvoie l'objet bulkConnectLinkForGoogle. Lisez url et vérifiez success et errors. Les deux URL de redirection doivent être des URL https absolues. Voir Connecter un compte Google.

connected_accounts.connect_facebook

Identique à connect_google, pour un compte Facebook Pages. Valable pendant 24 heures.

Python
client.connected_accounts.connect_facebook(    success_url: str,    error_url: str,) -> APIObject
Python
link = client.connected_accounts.connect_facebook(  "https://app.example.com/onboarding/facebook/done",  "https://app.example.com/onboarding/facebook/retry",)print(link.url)

Renvoie l'objet bulkConnectLinkForFacebook, avec les mêmes champs url, success et errors. Voir Connecter un compte Facebook.

connected_accounts.oauth_url

Créez une URL qui connecte un profil sur une plateforme de publication à un établissement. Utilisez cette méthode lorsque vous savez déjà quel établissement l'utilisateur connecte, ce qui évite toute étape d'association. Valable pendant 24 heures.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParamètreTypeDescription
location_idstr | intÉtablissement auquel rattacher le profil, indiqué par son identifiant numérique ou encodé en base64.
sitestrGOOGLE, FACEBOOK ou APPLE. Le SDK convertit cette valeur en majuscules avant l'envoi.
success_urlstrURL https absolue vers laquelle l'utilisateur est redirigé en cas de succès.
error_urlstrURL https absolue vers laquelle l'utilisateur est redirigé en cas d'échec.
Python
link = client.connected_accounts.oauth_url(  16808,  site="google",  success_url="https://app.example.com/locations/16808?connected=1",  error_url="https://app.example.com/locations/16808?connected=0",)print(link.url)

Renvoie l'objet createConnectUrl. Une URL de redirection relative ou impossible à analyser entraîne le renvoi de success: true avec un null url ; vérifiez donc url lui-même et pas seulement success. Le lien est à usage unique ; créez-en donc un nouveau à chaque tentative. Voir Créer une URL de connexion OAuth pour un établissement.

connected_accounts.list

Listez les comptes Google et Facebook connectés à votre compte. C'est ici que vous obtenez le connectedAccountId nécessaire à chaque appel ultérieur.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParamètreTypeDescription
publisherstrUniquement les comptes d'une plateforme de publication.
statusstrUniquement les comptes dans un état de connexion donné, par exemple CONNECTED.
pageintNuméro de page à partir de 1.
per_pageintTaille de la page. Envoyée sous le nom perPage.
Python
accounts = client.connected_accounts.list(status="CONNECTED", per_page=50)for account in accounts.records:  print(account.connectedAccountId, account.email, account.connectedLocationsCount)print(accounts.pageInfo.totalRecords)

Renvoie l'objet connectedAccountsInfo : records ainsi que pageInfo contenant hasNextPage, totalPages et totalRecords. Le tri est fixe, par adresse e-mail du compte dans l'ordre croissant. Voir Lister les comptes connectés.

connected_accounts.details

Récupérez un compte connecté par son identifiant. Interrogez régulièrement cette méthode après trigger_matches et attendez que requestMatchesStatus atteigne MATCH_COMPLETED.

Python
client.connected_accounts.details(connected_account_id: str) -> APIObject
Python
account = client.connected_accounts.details("4f712c17-4f95-42dd-90f4-97171a2e67b5")print(account.details.get("status"))print(account.details.get("requestMatchesStatus"))

Renvoie l'objet connectedAccountDetails. Les champs se trouvent sous details : status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus et lastFetchMatchesRequestedAt. Une valeur non nulle de connectivityIssue signifie que l'autorisation du jeton de la plateforme de publication doit être renouvelée. Voir Obtenir les détails d'un compte connecté.

connected_accounts.listings

Listez les fiches de la plateforme de publication auxquelles un compte connecté a accès, qu'elles soient associées ou non à l'un de vos établissements. Utilisez cette méthode pour montrer à l'utilisateur les accès obtenus.

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParamètreTypeDescription
connected_account_idstrCompte connecté dont les fiches doivent être lues.
location_infostrFiltre en texte libre sur le nom et l'adresse de la fiche.
pageintNuméro de page à partir de 1.
per_pageintTaille de la page. Envoyée sous le nom perPage.
Python
page = client.connected_accounts.listings(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  location_info="Manhattan",  per_page=25,)for listing in page.records:  print(listing.locationName, listing.address, listing.accountTypeName)

Ce point de terminaison utilise POST et prend tous les arguments dans le corps de la requête, et non dans la chaîne de requête ; le SDK construit ce corps pour vous. Renvoie l'objet connectedAccountListings : records ainsi que pageInfo. Chaque enregistrement contient id, locationName, address, phone, accountTypeName et liveLink. Voir Récupérer les fiches d'un compte connecté.

connected_accounts.trigger_matches

Mettez en file d'attente la tâche qui récupère tous les profils auxquels les comptes indiqués ont accès et recherche les établissements correspondants parmi les vôtres. Exécutez-la juste après une connexion groupée, puis à nouveau après avoir ajouté des établissements.

Python
client.connected_accounts.trigger_matches(    connected_account_ids: list[str],) -> APIObject
Python
result = client.connected_accounts.trigger_matches(  ["4f712c17-4f95-42dd-90f4-97171a2e67b5"],)print(result.success, result.failedIds)

Renvoie l'objet connectedAccountsTriggerMatches avec success et failedIds. Le traitement est asynchrone ; success: true signifie donc que la tâche est en file d'attente, et non qu'elle est terminée. Interrogez régulièrement details jusqu'à ce que requestMatchesStatus soit MATCH_COMPLETED avant de consulter les suggestions. Voir Déclencher la recherche de correspondances.

connected_accounts.suggestions

Consultez les associations que la tâche d'association a trouvées entre les fiches du compte et vos établissements. Présentez-les à l'utilisateur pour vérification avant de les confirmer.

Python
client.connected_accounts.suggestions(    connected_account_id: str,    *,    page: int | None = None,    per_page: int | None = None,) -> APIObject
Python
page = client.connected_accounts.suggestions(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  per_page=50,)for match in page.records:  print(match.locationId, match.accountType, match.matchedDataDatabaseId)

Renvoie l'objet connectionSuggestionsForAccount : records ainsi que pageInfo. Chaque enregistrement contient locationId, accountType, matchedDataDatabaseId, locationInfo et suggestedLocationInfo. Un records vide avec totalRecords: 0 signifie généralement que la tâche d'association n'a pas encore été exécutée. Voir Lister les suggestions de connexion.

connected_accounts.confirm_matches

Validez les associations suggérées. Une fois l'association confirmée, la fiche de la plateforme de publication commence à se synchroniser avec l'établissement associé.

Python
client.connected_accounts.confirm_matches(    match_record_ids: list[str],) -> APIObject
Python
result = client.connected_accounts.confirm_matches([  "R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=",])print(result.success, result.failedIds)

Renvoie l'objet confirmConnectMatches avec success et failedIds. Un enregistrement de suggestion n'a pas de id propre : construisez l'identifiant de chaque enregistrement d'association à partir de ses champs matchedDataDatabaseId et accountType, comme décrit dans Confirmer les associations.

connected_accounts.folders

Listez les dossiers (que Google appelle groupes de comptes) auxquels un compte Google connecté a accès. Transmettez le folderId choisi lorsque vous créez une fiche Google afin qu'elle soit placée dans le bon dossier.

Python
client.connected_accounts.folders(    connected_account_id: str,    *,    folder_name: str | None = None,) -> list[APIObject]
Python
folders = client.connected_accounts.folders(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)for folder in folders:  print(folder.folderId, folder.folderName, folder.locationCount)

Renvoie la liste getFoldersUnderGoogleAccount. Chaque élément contient folderId (une chaîne accounts/{id} utilisée telle quelle), folderName et locationCount, qui vaut null lorsque Google ne fournit aucun nombre. Comptes de type Google uniquement. Voir Lister les dossiers et listings.create_gmb.

connected_accounts.disconnect_google

Déconnectez un compte Google entier. Tous les établissements associés par l'intermédiaire de ce compte cessent de se synchroniser avec Google.

Python
client.connected_accounts.disconnect_google(    connected_account_id: str,) -> APIObject
Python
result = client.connected_accounts.disconnect_google(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)print(result.success)

Renvoie l'objet gmbBulkDisconnect avec success. Voir Déconnecter un compte Google.

connected_accounts.disconnect_facebook

Déconnectez un compte Facebook Pages entier.

Python
client.connected_accounts.disconnect_facebook(    connected_account_id: str,) -> APIObject
Python
result = client.connected_accounts.disconnect_facebook(  "9a41b8c0-7d2e-4c15-9f63-2b8e5ad71f04",)print(result.success)

Renvoie l'objet fbBulkDisconnect avec success. Voir Déconnecter un compte Facebook.

connected_accounts.oauth_disconnect

Déconnectez un établissement d'une plateforme de publication, en laissant le reste du compte connecté. C'est l'opération inverse de oauth_url.

Python
client.connected_accounts.oauth_disconnect(    location_id: str | int,    site: str,) -> APIObject

site vaut GOOGLE, FACEBOOK ou APPLE, et le SDK convertit cette valeur en majuscules avant l'envoi.

Python
client.connected_accounts.oauth_disconnect(16808, site="google")

Renvoie l'objet disconnectConnectedAccountsLocations avec success et errors. Voir Déconnecter un établissement d'une plateforme de publication.

Voir aussi