Listings APIListings API
Anmelden

Verbundene Konten

Google-, Facebook- und Apple Business Connect-Konten mit dem listingsapi-js SDK verbinden, ihre Einträge Standorten zuordnen und Konten trennen.

Ein verbundenes Konto ist eine OAuth-Autorisierung durch einen Inhaber eines Google Business Profile-, Facebook Pages- oder Apple Business Connect-Kontos. Sobald die Autorisierung vorliegt, kann die Plattform die Einträge dieses Kontos lesen und jeden Eintrag mit einem Standort verknüpfen. Alle Methoden für verbundene Konten stehen auf der Client-Instanz ListingsAPI zur Verfügung.

Die übliche Reihenfolge ist: einen Verbindungslink erstellen, auf die Autorisierung durch den Inhaber warten, die Konten auflisten, um einen Wert für connectedAccountId zu erhalten, den Abgleich starten, die Vorschläge prüfen und sie dann bestätigen oder einen Eintrag manuell verknüpfen. Jede Methode liefert die Nutzdaten unter ihrem eigenen Antwortschlüssel, der im jeweiligen Abschnitt unten genannt wird.

connectGoogleAccount

Erstellen Sie einen kontoweiten OAuth-Link für Google Business Profile. Leiten Sie den Inhaber zur zurückgegebenen url weiter; nach dem Schließen des Zustimmungsdialogs kehrt er zu Ihrer successUrl oder errorUrl zurück.

TypeScript
const link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',); console.log(link.url);

Parameter

ParameterTypBeschreibung
successUrlstringAbsolute URL, zu der der Inhaber nach der Autorisierung zurückkehrt.
errorUrlstringAbsolute URL, zu der der Inhaber zurückkehrt, wenn er den Vorgang abbricht oder die Autorisierung fehlschlägt.

Liefert die Nutzdaten unter bulkConnectLinkForGoogle: url, success und errors. Prüfen Sie url und nicht nur success, da eine unbrauchbare Weiterleitung als Erfolg mit null für url zurückgegeben werden kann. Der Link ist nur kurz gültig. Erstellen Sie daher für jeden Versuch einen neuen Link.

connectFacebookAccount

Das Gegenstück zu connectGoogleAccount für Facebook Pages mit denselben beiden Weiterleitungsargumenten.

TypeScript
const link = await client.connectFacebookAccount('https://app.example.com/onboarding/facebook/done','https://app.example.com/onboarding/facebook/failed',); console.log(link.url);

Parameter

ParameterTypBeschreibung
successUrlstringAbsolute URL, zu der der Inhaber nach der Autorisierung zurückkehrt.
errorUrlstringAbsolute URL, zu der der Inhaber zurückkehrt, wenn er den Vorgang abbricht oder die Autorisierung fehlschlägt.

Liefert die Nutzdaten unter bulkConnectLinkForFacebook: url, success und errors.

getOauthConnectUrl

Erstellen Sie einen OAuth-Link, der auf einen einzelnen Standort statt auf ein ganzes Konto beschränkt ist. Verwenden Sie ihn, wenn Sie bereits wissen, welchen Standort der Inhaber verbindet, und ihn zur Ansicht dieses Standorts in Ihrem eigenen Produkt zurückleiten möchten.

TypeScript
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);

Parameter

ParameterTypBeschreibung
locationIdstring | numberStandort, dem die Verbindung zugeordnet wird. Numerische IDs werden für Sie kodiert.
sitestringZu verbindende Plattform: 'GOOGLE', 'FACEBOOK' oder 'APPLE'.
successUrlstringAbsolute URL, zu der der Inhaber nach der Autorisierung zurückkehrt.
errorUrlstringAbsolute URL, zu der der Inhaber zurückkehrt, wenn die Autorisierung fehlschlägt.

Liefert die Nutzdaten unter createConnectUrl: url, success und errors. Beide Weiterleitungs-URLs sind erforderlich und müssen absolut sein. Der Link kann nur einmal verwendet werden und ist an den angegebenen Standort gebunden.

fetchConnectedAccounts

Listen Sie die für Ihr Konto autorisierten Google- und Facebook-Konten mit dem Zustand der Verbindung und der Anzahl verknüpfter Standorte auf. Hier erhalten Sie den Wert für connectedAccountId, den jede nachfolgende Methode benötigt.

TypeScript
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);}

Optionen

ParameterTypBeschreibung
publisherstringKontotyp, zum Beispiel 'GoogleAccount' oder 'FacebookAccount'.
statusstringFilter für den Verbindungsstatus: 'Connected', 'NotConnected' oder 'ConnectionIssue'.
pagenumberSeitennummer (beginnend bei 1).
perPagenumberDatensätze pro Seite.

Liefert die Nutzdaten unter connectedAccountsInfo: ein records-Array sowie pageInfo mit hasNextPage, hasPreviousPage, totalPages und totalRecords. Jeder Datensatz enthält connectedAccountId, email, connectedAccountType, connectedLocationsCount, connectivityIssue, status und requestMatchesStatus.

Der Filter und das Feld verwenden unterschiedliche Werte. Die Option status akzeptiert 'Connected', 'NotConnected' oder 'ConnectionIssue', während das Feld status eines Datensatzes den Wert CONNECTED, MATCH_IN_PROGRESS oder CONNECTIVITY_ISSUE hat. Wird der Wert eines Datensatzes als Filter übergeben, wird die Anfrage abgelehnt.

fetchConnectedAccountDetails

Lesen Sie ein einzelnes Konto anhand seiner ID aus. Diese Methode ist weniger aufwendig als das seitenweise Abrufen der gesamten Liste, wenn Ihnen die ID bereits vorliegt, und wird während des laufenden Abgleichs regelmäßig abgefragt.

TypeScript
const details = await client.fetchConnectedAccountDetails('4f712c17-4f95-42dd-90f4-97171a2e67b5',); console.log(details.details.requestMatchesStatus); // MATCH_IN_PROGRESS, then MATCH_COMPLETED

Parameter

ParameterTypBeschreibung
connectedAccountIdstringID des verbundenen Kontos aus fetchConnectedAccounts.

Liefert die Nutzdaten unter connectedAccountDetails, in denen der Datensatz unter details mit denselben Feldern wie in der Liste verschachtelt ist. Prüfen Sie requestMatchesStatus, um zu erkennen, wann Vorschläge bereitstehen, und lesen Sie status sowie connectivityIssue, um zu entscheiden, ob Sie zu einer erneuten Autorisierung auffordern sollten.

fetchConnectedAccountFolders

Listen Sie die Google-Kontogruppen (Ordner) auf, auf die das verbundene Konto zugreifen kann. Rufen Sie diese Methode vor createGmbListing auf, wenn der Inhaber den neuen Eintrag in einer bestimmten Gruppe erstellen möchte.

TypeScript
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' },);

Optionen

ParameterTypBeschreibung
folderNamestringBeschränken Sie das Ergebnis auf Ordner, deren Name diesem Namen entspricht.

Liefert das Array getFoldersUnderGoogleAccount, standardmäßig ein leeres Array. Jeder Ordner enthält folderId (eine accounts/<id>-Zeichenfolge, die Sie unverändert weitergeben), folderName und locationCount, das null sein kann, wenn Google keine Anzahl meldet. Der Pfad ist nur für Konten vom Typ Google gültig.

fetchConnectedAccountListings

Listen Sie die Einträge auf den Plattformen auf, auf die das verbundene Konto zugreifen kann. Der Wert für id jedes Datensatzes ist genau der Wert für connectedAccountListingId, den connectListing akzeptiert, sodass Sie damit eine Eintragsauswahl erstellen können.

TypeScript
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);}

Optionen

ParameterTypBeschreibung
locationInfostringFreitextsuche über Unternehmensname, Adresse, Ort, Postleitzahl, Filialcode und Telefonnummer.
pagenumberSeitennummer (beginnend bei 1).
perPagenumberDatensätze pro Seite. Der Standardwert ist 500 und zugleich das Maximum.

Liefert die Nutzdaten unter connectedAccountListings: records sowie pageInfo. Jeder Datensatz enthält id, locationName, address, phone, liveLink und accountTypeName. Obwohl die zugrunde liegende Anfrage wie eine Schreibanfrage aufgebaut ist, handelt es sich um einen Lesevorgang: Das SDK überträgt die Konto-ID und die Parameter für die Seitennavigation für Sie im Anfrage-Body, wie es der Endpunkt verlangt.

triggerConnectedAccountMatches

Stellen Sie den Auftrag in die Warteschlange, der alle Profile abruft, auf die die angegebenen Konten zugreifen können, und sie mit Ihren Standorten abgleicht. Rufen Sie diese Methode direkt auf, nachdem ein Inhaber den Zustimmungsdialog abgeschlossen hat, und erneut, nachdem Sie Standorte in einem Sammelvorgang erstellt haben.

TypeScript
const result = await client.triggerConnectedAccountMatches(['4f712c17-4f95-42dd-90f4-97171a2e67b5',]); console.log(result.success, result.failedIds);

Parameter

ParameterTypBeschreibung
connectedAccountIdsstring[]Konten, für die der Abgleich ausgeführt werden soll.

Liefert die Nutzdaten unter connectedAccountsTriggerMatches: success und failedIds. Der Wert true für success bedeutet, dass der Auftrag in die Warteschlange gestellt wurde, nicht dass der Abgleich abgeschlossen ist. Fragen Sie fetchConnectedAccountDetails regelmäßig ab, bis requestMatchesStatus den Wert MATCH_COMPLETED hat, und lesen Sie dann die Vorschläge aus.

fetchConnectionSuggestions

Lesen Sie die beim Abgleich ermittelten Zuordnungen aus, damit eine zuständige Person jeden Standort mit dem Eintrag auf der Plattform vergleichen kann, bevor eine Verknüpfung hergestellt wird.

TypeScript
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);}

Optionen

ParameterTypBeschreibung
pagenumberSeitennummer (beginnend bei 1).
perPagenumberDatensätze pro Seite.

Liefert die Nutzdaten unter connectionSuggestionsForAccount: records sowie pageInfo. Ein Vorschlagsdatensatz hat kein Feld id. Sein Bezeichner ist matchedDataDatabaseId, und accountType (GMB, FB oder APPLE) gibt an, um welche Art von Abgleichsdatensatz es sich handelt. Bewahren Sie beide Werte zusammen auf, da confirmConnectedAccountMatches beide benötigt, um die erforderliche ID zu bilden. Ein Konto, für das noch keine Übereinstimmungen vorliegen, liefert ein leeres records-Array.

confirmConnectedAccountMatches

Akzeptieren Sie die geprüften Zuordnungen. Durch die Bestätigung wird jeder Standort mit seinem Eintrag auf der Plattform verknüpft, sodass spätere Standortaktualisierungen übertragen werden.

Bilden Sie jede ID aus einem Vorschlagsdatensatz: Verbinden Sie den Typnamen des Abgleichsdatensatzes und dessen matchedDataDatabaseId mit einem Doppelpunkt und kodieren Sie das Ergebnis anschließend mit Base64. GMB wird GmbLocationMatchedData zugeordnet, FB wird FbLocationMatchedData zugeordnet und APPLE wird AppleLocationMatchedData zugeordnet.

TypeScript
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);

Parameter

ParameterTypBeschreibung
matchRecordIdsstring[]Kodierte IDs der zu bestätigenden Abgleichsdatensätze. Mindestens eine ist erforderlich.

Liefert die Nutzdaten unter confirmConnectMatches: success und failedIds. Prüfen Sie success bei jedem Aufruf: Für eine ID, die sich nicht zu einem der drei Typen dekodieren lässt, wird eine Antwort im Erfolgsformat zurückgegeben, in der success den Wert false hat und failedIds fehlt. Wenn einige IDs fehlschlagen, enthält failedIds die dekodierten Datenbank-IDs und nicht die von Ihnen gesendeten kodierten Werte. Gleichen Sie sie daher mit matchedDataDatabaseId ab.

Einen einzelnen Eintrag mit einem einzelnen Standort verknüpfen

Drei Methoden schließen die Verknüpfung zwischen einem einzelnen zugeordneten Eintrag und einem einzelnen Standort ab. Sie sind zusammen mit den übrigen Endpunkten für Einträge dokumentiert, um eine doppelte Dokumentation zu vermeiden:

Verwenden Sie diese Methoden, nachdem confirmConnectedAccountMatches den Großteil eines Kontos verarbeitet hat, wenn eine einzelne Filiale noch manuell zugeordnet werden muss.

oauthDisconnect

Dieselbe Trennung der Verbindung für einen einzelnen Standort, aufgerufen über den OAuth-Pfad für den jeweiligen Standort. Sie akzeptiert dieselben Argumente und liefert dieselben Nutzdaten. Wählen Sie daher den Namen, der in Ihrem Code besser lesbar ist.

TypeScript
await client.oauthDisconnect(1800289, 'GOOGLE');

Parameter

ParameterTypBeschreibung
locationIdstring | numberStandort, dessen Verbindung getrennt werden soll.
sitestringPlattform, zu der die Verbindung getrennt werden soll: 'GOOGLE', 'FACEBOOK' oder 'APPLE'.

Liefert die Nutzdaten disconnectConnectedAccountsLocations, also denselben Schlüssel, den disconnectListing zurückgibt.

disconnectGoogleAccount

Trennen Sie die Verbindung zu einem gesamten Google-Konto: Alle darüber verknüpften Standorte erhalten dann keine Aktualisierungen mehr. Verwenden Sie diese Methode, wenn ein Kunde kündigt oder die Inhaberschaft überträgt.

TypeScript
await client.disconnectGoogleAccount('4f712c17-4f95-42dd-90f4-97171a2e67b5');

Parameter

ParameterTypBeschreibung
connectedAccountIdstringGoogle-Konto, dessen Verbindung getrennt werden soll.

Liefert die Nutzdaten gmbBulkDisconnect, die success enthalten. Die Trennung erfolgt vollständig oder gar nicht: Um die Verknüpfung eines einzelnen Standorts aufzuheben und das Konto beizubehalten, verwenden Sie disconnectListing. Für success wird selbst bei einer unbekannten ID der Wert true zurückgegeben. Rufen Sie daher anschließend fetchConnectedAccounts ab, wenn Sie Gewissheit benötigen.

disconnectFacebookAccount

Die entsprechende Methode für Facebook mit demselben Argument und demselben Verhalten: Die Trennung erfolgt vollständig oder gar nicht.

TypeScript
await client.disconnectFacebookAccount('9d2b5a41-0c7e-4f83-bb16-2ac43e70d915');

Parameter

ParameterTypBeschreibung
connectedAccountIdstringFacebook-Konto, dessen Verbindung getrennt werden soll.

Liefert die Nutzdaten fbBulkDisconnect, die success enthalten. Dieselbe Einschränkung gilt: Auch bei einer unbekannten ID wird Erfolg gemeldet. Überprüfen Sie das Ergebnis daher mit fetchConnectedAccounts.

Typischer Einrichtungsablauf

connect_google.ts
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');