Listings APIListings API
Accedi

Account collegati

Collega gli account Google, Facebook e Apple Business Connect, associa le loro schede alle sedi e scollegali tramite client.connected_accounts.

Tutti i metodi per gli account collegati si trovano in client.connected_accounts. Un account collegato è un account Google Business Profile, Facebook Pages o Apple Business Connect che ha autorizzato la piattaforma, identificato da un connectedAccountId che ottieni da connected_accounts.list.

Ci sono due modi per effettuare il collegamento. Il flusso di collegamento in blocco autorizza un intero account di una piattaforma di pubblicazione e poi abbina le sue schede alle tue sedi. Il flusso per una singola sede crea un link OAuth per una sede ed è quello da usare quando la tua app collega un negozio alla volta. I metodi che accettano un location_id accettano ID numerici o codificati in base64; vedi ID delle sedi.

Flusso di abbinamento

Dopo un collegamento in blocco, le schede della piattaforma di pubblicazione non sono ancora collegate alle tue sedi. Chiama trigger_matches per mettere in coda il processo di abbinamento, interroga periodicamente details finché requestMatchesStatus non assume il valore MATCH_COMPLETED, leggi gli abbinamenti con suggestions, quindi conferma quelli che vuoi con confirm_matches. Se salti trigger_matches, suggestions rimane vuoto.

connected_accounts.connect_google

Crea un URL che autorizza un intero account Google Business Profile. Indirizza l'utente a questo URL, da cui tornerà a success_url o error_url. Il link è valido per 24 ore.

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)

Restituisce l'oggetto bulkConnectLinkForGoogle. Leggi url e controlla success e errors. Entrambi gli URL di reindirizzamento devono essere URL https assoluti. Vedi Collegare un account Google.

connected_accounts.connect_facebook

Come connect_google, per un account Facebook Pages. Valido per 24 ore.

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)

Restituisce l'oggetto bulkConnectLinkForFacebook, con gli stessi campi url, success e errors. Vedi Collegare un account Facebook.

connected_accounts.oauth_url

Crea un URL che collega un profilo su una piattaforma di pubblicazione a una sede. Usalo quando sai già quale sede sta collegando l'utente, quindi non serve un passaggio di abbinamento. Valido per 24 ore.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParametroTipoDescrizione
location_idstr | intSede a cui associare il profilo, indicata tramite ID numerico o in base64.
sitestrGOOGLE, FACEBOOK o APPLE. L'SDK converte il valore in maiuscolo prima di inviarlo.
success_urlstrURL https assoluto a cui torna l'utente in caso di successo.
error_urlstrURL https assoluto a cui torna l'utente in caso di errore.
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)

Restituisce l'oggetto createConnectUrl. Un URL di reindirizzamento relativo o non interpretabile restituisce success: true con un null url, quindi controlla url stesso e non solo success. Il link è monouso, quindi creane uno nuovo per ogni tentativo. Vedi Creare un URL di collegamento OAuth per una sede.

connected_accounts.list

Elenca gli account Google e Facebook collegati al tuo account. Da qui ottieni il connectedAccountId necessario per ogni chiamata successiva.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParametroTipoDescrizione
publisherstrSolo gli account di una piattaforma di pubblicazione.
statusstrSolo gli account in uno stato di connessione specifico, ad esempio CONNECTED.
pageintNumero di pagina a partire da 1.
per_pageintDimensione della pagina. Inviata come 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)

Restituisce l'oggetto connectedAccountsInfo: records più pageInfo con hasNextPage, totalPages e totalRecords. L'ordinamento è fisso, per indirizzo email dell'account in ordine crescente. Vedi Elencare gli account collegati.

connected_accounts.details

Recupera un account collegato tramite ID. Interroga periodicamente questo metodo dopo trigger_matches e attendi che requestMatchesStatus raggiunga 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"))

Restituisce l'oggetto connectedAccountDetails. I campi si trovano in details: status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus e lastFetchMatchesRequestedAt. Un valore di connectivityIssue diverso da null indica che il token della piattaforma di pubblicazione richiede una nuova autorizzazione. Vedi Recuperare i dettagli di un account collegato.

connected_accounts.listings

Elenca le schede della piattaforma di pubblicazione a cui un account collegato può accedere, indipendentemente dal fatto che siano abbinate a una delle tue sedi. Usalo per mostrare all'utente a quali schede hai ottenuto accesso.

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParametroTipoDescrizione
connected_account_idstrAccount collegato da cui leggere le schede.
location_infostrFiltro a testo libero sul nome e sull'indirizzo della scheda.
pageintNumero di pagina a partire da 1.
per_pageintDimensione della pagina. Inviata come 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)

Questo endpoint usa POST e accetta tutti gli argomenti nel corpo della richiesta, non nella query string; l'SDK costruisce il corpo per te. Restituisce l'oggetto connectedAccountListings: records più pageInfo. Ogni record contiene id, locationName, address, phone, accountTypeName e liveLink. Vedi Recuperare le schede di un account collegato.

connected_accounts.trigger_matches

Metti in coda il processo che recupera tutti i profili a cui gli account specificati possono accedere e li abbina alle tue sedi. Eseguilo subito dopo un collegamento in blocco e di nuovo dopo aver aggiunto delle sedi.

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)

Restituisce l'oggetto connectedAccountsTriggerMatches con success e failedIds. L'elaborazione è asincrona, quindi success: true indica che il processo è in coda, non che è terminato. Interroga periodicamente details finché requestMatchesStatus non assume il valore MATCH_COMPLETED prima di leggere i suggerimenti. Vedi Avviare gli abbinamenti.

connected_accounts.suggestions

Leggi gli abbinamenti trovati dal processo di abbinamento tra le schede dell'account e le tue sedi. Mostrali all'utente per una verifica prima di confermarli.

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)

Restituisce l'oggetto connectionSuggestionsForAccount: records più pageInfo. Ogni record contiene locationId, accountType, matchedDataDatabaseId, locationInfo e suggestedLocationInfo. Un records vuoto con totalRecords: 0 di solito indica che il processo di abbinamento non è ancora stato eseguito. Vedi Elencare i suggerimenti di collegamento.

connected_accounts.confirm_matches

Conferma gli abbinamenti suggeriti. Dopo la conferma, la scheda della piattaforma di pubblicazione inizia a sincronizzarsi con la sede abbinata.

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)

Restituisce l'oggetto confirmConnectMatches con success e failedIds. Un record di suggerimento non ha un proprio id: costruisci l'ID di ogni record di abbinamento a partire da matchedDataDatabaseId e accountType del record, come descritto in Confermare gli abbinamenti.

connected_accounts.folders

Elenca le cartelle (che Google chiama gruppi di account) a cui un account Google collegato può accedere. Passa il folderId scelto quando crei una scheda Google, in modo che venga inserita nella cartella corretta.

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)

Restituisce l'elenco getFoldersUnderGoogleAccount. Ogni elemento contiene folderId (una stringa accounts/{id} usata senza modifiche), folderName e locationCount, che vale null quando Google non fornisce un conteggio. Solo per account di tipo Google. Vedi Elencare le cartelle e listings.create_gmb.

connected_accounts.disconnect_google

Scollega un intero account Google. Ogni sede abbinata tramite quell'account smette di sincronizzarsi con 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)

Restituisce l'oggetto gmbBulkDisconnect con success. Vedi Scollegare un account Google.

connected_accounts.disconnect_facebook

Scollega un intero account Facebook Pages.

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)

Restituisce l'oggetto fbBulkDisconnect con success. Vedi Scollegare un account Facebook.

connected_accounts.oauth_disconnect

Scollega una sede da una piattaforma di pubblicazione, mantenendo collegato il resto dell'account. È l'operazione inversa di oauth_url.

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

site è GOOGLE, FACEBOOK o APPLE e l'SDK converte il valore in maiuscolo prima di inviarlo.

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

Restituisce l'oggetto disconnectConnectedAccountsLocations con success e errors. Vedi Scollegare una sede da una piattaforma di pubblicazione.

Vedi anche