Listings APIListings API
Iniciar sesión

Cuentas conectadas

Conecta cuentas de Google, Facebook y Apple Business Connect, asocia sus fichas a ubicaciones y desconéctalas mediante client.connected_accounts.

Todos los métodos de cuentas conectadas se encuentran en client.connected_accounts. Una cuenta conectada es una cuenta de Google Business Profile, Facebook Pages o Apple Business Connect que ha autorizado a la plataforma y se identifica mediante un connectedAccountId que obtienes de connected_accounts.list.

Hay dos formas de conectarse. El flujo masivo autoriza una cuenta completa de una plataforma de publicación y luego busca correspondencias entre sus fichas y tus ubicaciones. El flujo para una sola ubicación crea un enlace OAuth para una ubicación, que es lo que necesitas cuando tu aplicación conecta las tiendas de una en una. Los métodos que reciben un location_id aceptan identificadores numéricos o codificados en base64; consulta Identificadores de ubicación.

Flujo de correspondencias

Tras una conexión masiva, las fichas de la plataforma de publicación aún no están vinculadas a tus ubicaciones. Llama a trigger_matches para poner en cola la tarea de búsqueda de correspondencias, consulta details periódicamente hasta que requestMatchesStatus indique MATCH_COMPLETED, lee las correspondencias con suggestions y luego confirma las que quieras con confirm_matches. Si omites trigger_matches, suggestions queda vacío.

connected_accounts.connect_google

Crea una URL que autoriza una cuenta completa de Google Business Profile. Dirige al usuario a ella y volverá a success_url o error_url. El enlace es válido durante 24 horas.

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)

Devuelve el objeto bulkConnectLinkForGoogle. Lee url y comprueba success y errors. Ambas URL de redirección deben ser URL https absolutas. Consulta Conectar una cuenta de Google.

connected_accounts.connect_facebook

Igual que connect_google, para una cuenta de Facebook Pages. Válido durante 24 horas.

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)

Devuelve el objeto bulkConnectLinkForFacebook, con los mismos campos url, success y errors. Consulta Conectar una cuenta de Facebook.

connected_accounts.oauth_url

Crea una URL que conecta un perfil de una plataforma de publicación a una ubicación. Usa este método cuando ya sepas qué ubicación está conectando el usuario, de modo que no sea necesario buscar correspondencias. Válida durante 24 horas.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParámetroTipoDescripción
location_idstr | intUbicación a la que se asociará el perfil, indicada mediante un identificador numérico o en base64.
sitestrGOOGLE, FACEBOOK o APPLE. El SDK lo convierte a mayúsculas antes de enviarlo.
success_urlstrURL https absoluta a la que vuelve el usuario si la operación se realiza correctamente.
error_urlstrURL https absoluta a la que vuelve el usuario si la operación falla.
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)

Devuelve el objeto createConnectUrl. Una URL de redirección relativa o que no se pueda analizar devuelve success: true con null url, así que comprueba el propio url y no solo success. El enlace es de un solo uso, así que crea uno nuevo para cada intento. Consulta Crear una URL de conexión OAuth para una ubicación.

connected_accounts.list

Enumera las cuentas de Google y Facebook conectadas a tu cuenta. Aquí obtienes el connectedAccountId que necesita cada llamada posterior.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParámetroTipoDescripción
publisherstrSolo las cuentas de una plataforma de publicación.
statusstrSolo las cuentas en un estado de conexión determinado, por ejemplo, CONNECTED.
pageintNúmero de página, empezando por 1.
per_pageintTamaño de página. Se envía como 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)

Devuelve el objeto connectedAccountsInfo: records más pageInfo con hasNextPage, totalPages y totalRecords. El orden es fijo: ascendente por el correo electrónico de la cuenta. Consulta Enumerar las cuentas conectadas.

connected_accounts.details

Obtén una cuenta conectada por su identificador. Consulta este método periódicamente después de trigger_matches y espera a que requestMatchesStatus alcance 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"))

Devuelve el objeto connectedAccountDetails. Los campos se encuentran en details: status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus y lastFetchMatchesRequestedAt. Un valor de connectivityIssue distinto de null significa que el token de la plataforma de publicación necesita una nueva autorización. Consulta Obtener los detalles de una cuenta conectada.

connected_accounts.listings

Enumera las fichas de la plataforma de publicación a las que puede acceder una cuenta conectada, tengan o no una correspondencia con una de tus ubicaciones. Usa este método para mostrar al usuario a qué fichas has obtenido acceso.

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParámetroTipoDescripción
connected_account_idstrCuenta conectada de la que se leerán las fichas.
location_infostrFiltro de texto libre sobre el nombre y la dirección de la ficha.
pageintNúmero de página, empezando por 1.
per_pageintTamaño de página. Se envía como 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)

Este endpoint usa POST y recibe todos los argumentos en el cuerpo de la solicitud, no en la cadena de consulta; el SDK construye ese cuerpo por ti. Devuelve el objeto connectedAccountListings: records más pageInfo. Cada registro contiene id, locationName, address, phone, accountTypeName y liveLink. Consulta Obtener las fichas de una cuenta conectada.

connected_accounts.trigger_matches

Pon en cola la tarea que obtiene todos los perfiles a los que pueden acceder las cuentas indicadas y busca correspondencias con tus ubicaciones. Ejecútala justo después de una conexión masiva y de nuevo después de añadir ubicaciones.

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)

Devuelve el objeto connectedAccountsTriggerMatches con success y failedIds. La tarea es asíncrona, por lo que success: true significa que está en cola, no que haya terminado. Consulta details periódicamente hasta que requestMatchesStatus sea MATCH_COMPLETED antes de leer las sugerencias. Consulta Iniciar la búsqueda de correspondencias.

connected_accounts.suggestions

Lee las correspondencias que la tarea encontró entre las fichas de la cuenta y tus ubicaciones. Muéstraselas al usuario para que las revise antes de confirmarlas.

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)

Devuelve el objeto connectionSuggestionsForAccount: records más pageInfo. Cada registro contiene locationId, accountType, matchedDataDatabaseId, locationInfo y suggestedLocationInfo. Un records vacío con totalRecords: 0 suele significar que la tarea de búsqueda de correspondencias aún no se ha ejecutado. Consulta Enumerar las sugerencias de conexión.

connected_accounts.confirm_matches

Confirma las correspondencias sugeridas. Una vez confirmadas, la ficha de la plataforma de publicación comienza a sincronizarse con la ubicación correspondiente.

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)

Devuelve el objeto confirmConnectMatches con success y failedIds. Un registro de sugerencia no tiene un id propio: construye el identificador de cada registro de correspondencia a partir de los campos matchedDataDatabaseId y accountType del registro, como se describe en Confirmar correspondencias.

connected_accounts.folders

Enumera las carpetas (Google las llama grupos de cuentas) a las que puede acceder una cuenta de Google conectada. Pasa el folderId elegido cuando crees una ficha de Google para que se cree en la carpeta correcta.

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)

Devuelve la lista getFoldersUnderGoogleAccount. Cada elemento tiene folderId (una cadena accounts/{id} que se usa sin cambios), folderName y locationCount, cuyo valor es null cuando Google no proporciona un recuento. Solo para cuentas de tipo Google. Consulta Enumerar las carpetas y listings.create_gmb.

connected_accounts.disconnect_google

Desconecta una cuenta completa de Google. Todas las ubicaciones vinculadas a través de ella dejan de sincronizarse 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)

Devuelve el objeto gmbBulkDisconnect con success. Consulta Desconectar una cuenta de Google.

connected_accounts.disconnect_facebook

Desconecta una cuenta completa de 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)

Devuelve el objeto fbBulkDisconnect con success. Consulta Desconectar una cuenta de Facebook.

connected_accounts.oauth_disconnect

Desconecta una ubicación de una plataforma de publicación y mantiene conectado el resto de la cuenta. Esta es la operación inversa a oauth_url.

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

site es GOOGLE, FACEBOOK o APPLE, y el SDK lo convierte a mayúsculas antes de enviarlo.

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

Devuelve el objeto disconnectConnectedAccountsLocations con success y errors. Consulta Desconectar una ubicación de una plataforma de publicación.

Consulta también