Comptes connectés
Connectez des comptes Google, Facebook et Apple Business Connect, associez leurs fiches aux établissements et déconnectez-les avec le SDK listingsapi-js.
Un compte connecté correspond à une autorisation OAuth accordée par le propriétaire d'un compte Google Business Profile, Facebook Pages ou Apple Business Connect. Une fois l'autorisation accordée, la plateforme peut lire les fiches appartenant à ce compte et associer chacune à un établissement. Toutes les méthodes de gestion des comptes connectés sont disponibles sur l'instance du client ListingsAPI.
L'ordre habituel est le suivant : créer un lien de connexion, attendre que le propriétaire accorde l'autorisation, lister les comptes pour récupérer un connectedAccountId, lancer la recherche de correspondances, examiner les suggestions, puis les confirmer ou associer une fiche manuellement. Chaque méthode renvoie les données contenues sous sa propre clé de réponse, indiquée dans la section correspondante ci-dessous.
connectGoogleAccount
Créez un lien OAuth à l'échelle d'un compte pour Google Business Profile. Dirigez le propriétaire vers le url renvoyé ; il revient à votre successUrl ou errorUrl lorsque l'écran de consentement se ferme.
const link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',); console.log(link.url);Paramètres
Renvoie les données de bulkConnectLinkForGoogle : url, success et errors. Vérifiez url et pas seulement success, car une redirection inutilisable peut produire une réponse indiquant un succès avec un url à null. Le lien a une courte durée de validité ; créez-en donc un nouveau à chaque tentative.
connectFacebookAccount
L'équivalent de connectGoogleAccount pour Facebook Pages, avec les deux mêmes arguments de redirection.
const link = await client.connectFacebookAccount('https://app.example.com/onboarding/facebook/done','https://app.example.com/onboarding/facebook/failed',); console.log(link.url);Paramètres
Renvoie les données de bulkConnectLinkForFacebook : url, success et errors.
getOauthConnectUrl
Créez un lien OAuth limité à un établissement plutôt qu'à un compte entier. Utilisez-le lorsque vous savez déjà quel établissement le propriétaire connecte et souhaitez qu'il revienne à l'écran de cet établissement dans votre propre produit.
const link = await client.getOauthConnectUrl(1800289,'GOOGLE','https://app.example.com/locations/1800289/connected','https://app.example.com/locations/1800289/connect-failed',); console.log(link.url);Paramètres
Renvoie les données de createConnectUrl : url, success et errors. Les deux URL de redirection sont obligatoires et doivent être absolues. Le lien est à usage unique et lié à l'établissement que vous avez indiqué.
fetchConnectedAccounts
Listez les comptes Google et Facebook autorisés sur votre compte, avec l'état de leur connexion et le nombre d'établissements associés. C'est ici que vous obtenez le connectedAccountId dont toutes les méthodes suivantes ont besoin.
const page1 = await client.fetchConnectedAccounts({publisher: 'GoogleAccount',status: 'Connected',page: 1,perPage: 20,}); for (const record of page1.records ?? []) {console.log(record.email, record.connectedAccountId, record.status);}Options
Renvoie les données de connectedAccountsInfo : un tableau records ainsi que pageInfo contenant hasNextPage, hasPreviousPage, totalPages et totalRecords. Chaque enregistrement contient connectedAccountId, email, connectedAccountType, connectedLocationsCount, connectivityIssue, status et requestMatchesStatus.
Le filtre et le champ n'utilisent pas les mêmes valeurs. L'option status accepte 'Connected', 'NotConnected' ou 'ConnectionIssue', tandis que le champ status d'un enregistrement vaut CONNECTED, MATCH_IN_PROGRESS ou CONNECTIVITY_ISSUE. Réutiliser la valeur d'un enregistrement comme filtre entraîne un rejet.
fetchConnectedAccountDetails
Consultez un compte à partir de son identifiant. Cette méthode est moins coûteuse que de parcourir toute la liste paginée lorsque vous disposez déjà de l'identifiant, et c'est celle à interroger régulièrement pendant la recherche de correspondances.
const details = await client.fetchConnectedAccountDetails('4f712c17-4f95-42dd-90f4-97171a2e67b5',); console.log(details.details.requestMatchesStatus); // MATCH_IN_PROGRESS, then MATCH_COMPLETEDParamètres
Renvoie les données de connectedAccountDetails, qui contiennent l'enregistrement sous details avec les mêmes champs que ceux renvoyés par la liste. Surveillez requestMatchesStatus pour savoir quand les suggestions sont prêtes, et consultez status ainsi que connectivityIssue pour déterminer s'il faut demander une nouvelle autorisation.
fetchConnectedAccountFolders
Listez les groupes de comptes Google (dossiers) auxquels le compte connecté a accès. Appelez cette méthode avant createGmbListing lorsque le propriétaire souhaite placer la nouvelle fiche dans un groupe précis.
const folders = await client.fetchConnectedAccountFolders('4f712c17-4f95-42dd-90f4-97171a2e67b5',); for (const folder of folders) {console.log(folder.folderId, folder.folderName, folder.locationCount);} // Narrow by nameconst matching = await client.fetchConnectedAccountFolders('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ folderName: 'West Region' },);Options
Renvoie le tableau getFoldersUnderGoogleAccount, ou un tableau vide par défaut. Chaque dossier contient folderId (une chaîne accounts/<id> que vous transmettez telle quelle), folderName et locationCount, qui peut valoir null lorsque Google ne fournit aucun décompte. Ce chemin n'est valide que pour les comptes de type Google.
fetchConnectedAccountListings
Listez les fiches des plateformes de publication auxquelles le compte connecté a accès. Le champ id de chaque enregistrement correspond exactement au connectedAccountListingId accepté par connectListing ; vous pouvez ainsi créer un sélecteur de fiches.
const listings = await client.fetchConnectedAccountListings('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ locationInfo: 'William St', page: 1, perPage: 50 },); for (const record of listings.records ?? []) {console.log(record.id, record.locationName, record.address);}Options
Renvoie les données de connectedAccountListings : records ainsi que pageInfo. Chaque enregistrement contient id, locationName, address, phone, liveLink et accountTypeName. Bien que la requête sous-jacente ait la forme d'une requête d'écriture, il s'agit d'une lecture : le SDK place pour vous l'identifiant du compte et les paramètres de pagination dans le corps de la requête, comme l'exige le point de terminaison.
triggerConnectedAccountMatches
Mettez en file d'attente la tâche qui récupère tous les profils accessibles aux comptes indiqués et recherche leurs correspondances parmi vos établissements. Appelez cette méthode dès que le propriétaire termine l'étape de consentement, puis à nouveau après avoir créé des établissements en masse.
const result = await client.triggerConnectedAccountMatches(['4f712c17-4f95-42dd-90f4-97171a2e67b5',]); console.log(result.success, result.failedIds);Paramètres
Renvoie les données de connectedAccountsTriggerMatches : success et failedIds. Une valeur true pour success signifie que la tâche a été mise en file d'attente, pas que la recherche de correspondances est terminée. Interrogez régulièrement fetchConnectedAccountDetails jusqu'à ce que requestMatchesStatus vaille MATCH_COMPLETED, puis consultez les suggestions.
fetchConnectionSuggestions
Consultez les paires produites par la recherche de correspondances afin qu'un opérateur puisse comparer chaque établissement à la fiche de la plateforme de publication avant toute association.
const suggestions = await client.fetchConnectionSuggestions('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ page: 1, perPage: 50 },); for (const record of suggestions.records ?? []) {console.log(record.accountType, record.matchedDataDatabaseId, record.locationInfo.name);}Options
Renvoie les données de connectionSuggestionsForAccount : records ainsi que pageInfo. Un enregistrement de suggestion ne comporte aucun champ id. Son identifiant est matchedDataDatabaseId, et accountType (GMB, FB ou APPLE) indique le type d'enregistrement de correspondance. Conservez les deux ensemble, car confirmConnectedAccountMatches a besoin des deux pour construire l'identifiant qu'il accepte. Un compte pour lequel aucune correspondance n'a encore été trouvée renvoie un tableau records vide.
confirmConnectedAccountMatches
Acceptez les paires examinées. La confirmation associe chaque établissement à sa fiche sur la plateforme de publication afin que les mises à jour ultérieures de l'établissement y soient transmises.
Construisez chaque identifiant à partir d'un enregistrement de suggestion : concaténez le nom du type d'enregistrement de correspondance et le matchedDataDatabaseId de l'enregistrement en les séparant par un deux-points, puis encodez le résultat en base64. GMB correspond à GmbLocationMatchedData, FB à FbLocationMatchedData et APPLE à AppleLocationMatchedData.
const TYPES: Record<string, string> = {GMB: 'GmbLocationMatchedData',FB: 'FbLocationMatchedData',APPLE: 'AppleLocationMatchedData',}; const matchRecordId = (record: any) =>Buffer.from(TYPES[record.accountType] + ':' + record.matchedDataDatabaseId).toString('base64'); const approved = (suggestions.records ?? []).map(matchRecordId);const result = await client.confirmConnectedAccountMatches(approved); console.log(result.success, result.failedIds);Paramètres
Renvoie les données de confirmConnectMatches : success et failedIds. Vérifiez success à chaque appel : un identifiant qui, une fois décodé, ne correspond à aucun des trois types produit une réponse ayant la forme d'un succès, avec success à false et sans failedIds. Lorsque certains identifiants échouent, failedIds contient les identifiants décodés de la base de données, et non les valeurs encodées que vous avez envoyées ; rapprochez-les donc de matchedDataDatabaseId.
Associer une fiche à un établissement
Trois méthodes permettent de finaliser l’association entre une seule fiche correspondante et un seul établissement ; elles sont documentées avec les autres endpoints des fiches pour éviter de répéter leur documentation :
- connectListing associe une fiche correspondante à un établissement.
- disconnectListing supprime cette association.
- createGmbListing crée une fiche Google Business Profile pour un établissement qui n’en possède pas, dans un dossier provenant de fetchConnectedAccountFolders.
Utilisez ces méthodes après que confirmConnectedAccountMatches a effectué l’essentiel du traitement d’un compte, lorsqu’un établissement doit encore être associé manuellement.
oauthDisconnect
Cette méthode effectue la même déconnexion d’un seul établissement, via le parcours OAuth propre à chaque établissement. Elle prend les mêmes arguments et renvoie les mêmes données une fois résolue ; choisissez donc le nom qui convient le mieux à votre code.
await client.oauthDisconnect(1800289, 'GOOGLE');Paramètres
Une fois résolue, renvoie les données disconnectConnectedAccountsLocations, avec la même clé que celle renvoyée par disconnectListing.
disconnectGoogleAccount
Déconnectez un compte Google entier : tous les établissements associés par son intermédiaire cessent de recevoir des mises à jour. Utilisez cette méthode lorsqu’un client résilie son abonnement ou transfère la propriété.
await client.disconnectGoogleAccount('4f712c17-4f95-42dd-90f4-97171a2e67b5');Paramètres
Une fois résolue, renvoie les données gmbBulkDisconnect, qui contiennent success. Cette opération s’applique à l’ensemble du compte : pour dissocier un seul établissement tout en conservant le compte, utilisez disconnectListing. La valeur true est renvoyée pour success même si l’identifiant est inconnu ; consultez donc fetchConnectedAccounts ensuite si vous devez vérifier le résultat.
disconnectFacebookAccount
L’équivalent pour Facebook, avec le même argument et le même comportement qui s’applique à l’ensemble du compte.
await client.disconnectFacebookAccount('9d2b5a41-0c7e-4f83-bb16-2ac43e70d915');Paramètres
Une fois résolue, renvoie les données fbBulkDisconnect, qui contiennent success. La même réserve s’applique : un identifiant inconnu produit tout de même un résultat indiquant une réussite ; vérifiez donc avec fetchConnectedAccounts.
Procédure de configuration initiale habituelle
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // 1. Send the owner through the consent screenconst link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',);console.log('open:', link.url); // 2. After they return, pick up the account IDconst accounts = await client.fetchConnectedAccounts({ publisher: 'GoogleAccount' });const accountId = accounts.records[0].connectedAccountId; // 3. Match its listings against your locationsawait client.triggerConnectedAccountMatches([accountId]); // 4. Poll until matching finisheslet details = await client.fetchConnectedAccountDetails(accountId);while (details.details.requestMatchesStatus !== 'MATCH_COMPLETED') {await new Promise((resolve) => setTimeout(resolve, 5000));details = await client.fetchConnectedAccountDetails(accountId);} // 5. Read the suggestions and confirm the approved onesconst suggestions = await client.fetchConnectionSuggestions(accountId, { perPage: 100 });console.log('found ' + (suggestions.records ?? []).length + ' suggested matches');Ressources associées
- Fiches, les mêmes méthodes de connexion et de déconnexion dans le contexte des fiches
- Établissements, rechercher les identifiants des établissements
- Gestion des erreurs, les erreurs typées levées par chaque méthode
- Endpoints des comptes connectés, la procédure REST correspondant à ces méthodes
- Connecter Google et importer des établissements, le guide complet de configuration initiale
- Connecter des pages Facebook, la variante pour Facebook
- Créer une fiche Google Business Profile, le guide de
createGmbListing - Référence REST : lister les comptes, détails d’un compte, dossiers, fiches d’un compte, déclencher la recherche de correspondances, suggestions de connexion, confirmer les correspondances, connecter une fiche, déconnecter une fiche