Listings APIListings API
Entrar

Contas conectadas

Conecte contas do Google, Facebook e Apple Business Connect, associe suas listagens a locais e desconecte-as via client.connected_accounts.

Todos os métodos de contas conectadas estão em client.connected_accounts. Uma conta conectada é um login do Google Business Profile, Facebook Pages ou Apple Business Connect que autorizou a plataforma, identificado por um connectedAccountId que você obtém em connected_accounts.list.

Há duas formas de conectar. O fluxo em massa autoriza uma conta inteira de uma plataforma de publicação e depois associa suas listagens aos seus locais. O fluxo para um único local cria um link OAuth para um local, adequado quando seu aplicativo conecta uma loja por vez. Os métodos que recebem um location_id aceitam IDs numéricos ou codificados em base64; consulte IDs de locais.

Fluxo de associação

Após uma conexão em massa, as listagens da plataforma de publicação ainda não estão vinculadas aos seus locais. Chame trigger_matches para colocar a tarefa de associação na fila, consulte details periodicamente até que requestMatchesStatus tenha o valor MATCH_COMPLETED, leia as associações com suggestions e confirme as que você quiser com confirm_matches. Se você pular trigger_matches, suggestions ficará vazio.

connected_accounts.connect_google

Crie uma URL que autoriza uma conta inteira do Google Business Profile. Direcione o usuário a ela, e ele retornará a success_url ou error_url. O link é válido por 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)

Retorna o objeto bulkConnectLinkForGoogle. Leia url e verifique success e errors. As duas URLs de redirecionamento devem ser URLs https absolutas. Consulte Conectar uma conta do Google.

connected_accounts.connect_facebook

Igual a connect_google, para uma conta do Facebook Pages. Válido por 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)

Retorna o objeto bulkConnectLinkForFacebook, com os mesmos campos url, success e errors. Consulte Conectar uma conta do Facebook.

connected_accounts.oauth_url

Crie uma URL que conecta um perfil de uma plataforma de publicação a um local. Use este método quando você já souber qual local o usuário está conectando, dispensando a etapa de associação. Válida por 24 horas.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParâmetroTipoDescrição
location_idstr | intLocal ao qual vincular o perfil, com ID numérico ou em base64.
sitestrGOOGLE, FACEBOOK ou APPLE. O SDK converte o valor para maiúsculas antes de enviá-lo.
success_urlstrURL https absoluta à qual o usuário retorna em caso de sucesso.
error_urlstrURL https absoluta à qual o usuário retorna em caso de falha.
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)

Retorna o objeto createConnectUrl. Uma URL de redirecionamento relativa ou que não pode ser interpretada resulta em success: true com um null url, portanto, verifique o próprio url, e não apenas success. O link é de uso único, portanto, crie um novo a cada tentativa. Consulte Criar uma URL de conexão OAuth para um local.

connected_accounts.list

Liste as contas do Google e do Facebook conectadas à sua conta. É aqui que você obtém o connectedAccountId necessário para todas as chamadas posteriores.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParâmetroTipoDescrição
publisherstrApenas contas de uma plataforma de publicação.
statusstrApenas contas em um estado de conexão, por exemplo, CONNECTED.
pageintNúmero da página, começando em 1.
per_pageintTamanho da página. Enviado 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)

Retorna o objeto connectedAccountsInfo: records mais pageInfo com hasNextPage, totalPages e totalRecords. A ordenação é fixa, por e-mail da conta em ordem crescente. Consulte Listar contas conectadas.

connected_accounts.details

Obtenha uma conta conectada pelo ID. Consulte este método periodicamente após trigger_matches e aguarde até que requestMatchesStatus atinja 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"))

Retorna o objeto connectedAccountDetails. Os campos estão em details: status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus e lastFetchMatchesRequestedAt. Um valor não nulo em connectivityIssue significa que o token da plataforma de publicação precisa ser autorizado novamente. Consulte Obter detalhes de uma conta conectada.

connected_accounts.listings

Liste as listagens da plataforma de publicação às quais uma conta conectada tem acesso, estejam elas associadas ou não a um dos seus locais. Use este método para mostrar ao usuário quais acessos você obteve.

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âmetroTipoDescrição
connected_account_idstrConta conectada da qual ler as listagens.
location_infostrFiltro de texto livre aplicado ao nome e ao endereço da listagem.
pageintNúmero da página, começando em 1.
per_pageintTamanho da página. Enviado 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 e recebe todos os argumentos no corpo da requisição, não na query string; o SDK monta esse corpo para você. Retorna o objeto connectedAccountListings: records mais pageInfo. Cada registro contém id, locationName, address, phone, accountTypeName e liveLink. Consulte Buscar listagens de uma conta conectada.

connected_accounts.trigger_matches

Coloque na fila a tarefa que recupera todos os perfis aos quais as contas informadas têm acesso e busca correspondências com seus locais. Execute-a logo após uma conexão em massa e novamente após adicionar locais.

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)

Retorna o objeto connectedAccountsTriggerMatches com success e failedIds. O processamento é assíncrono, portanto, um success: true significa que a tarefa está na fila, não que foi concluída. Consulte details periodicamente até que requestMatchesStatus seja MATCH_COMPLETED antes de ler as sugestões. Consulte Iniciar associações.

connected_accounts.suggestions

Leia as associações que a tarefa de associação encontrou entre as listagens da conta e seus locais. Mostre-as ao usuário para avaliação antes de confirmá-las.

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)

Retorna o objeto connectionSuggestionsForAccount: records mais pageInfo. Cada registro contém locationId, accountType, matchedDataDatabaseId, locationInfo e suggestedLocationInfo. Um records vazio com totalRecords: 0 geralmente significa que a tarefa de associação ainda não foi executada. Consulte Listar sugestões de conexão.

connected_accounts.confirm_matches

Confirme as associações sugeridas. Após a confirmação, a listagem da plataforma de publicação começa a sincronizar com o local associado.

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)

Retorna o objeto confirmConnectMatches com success e failedIds. Um registro de sugestão não tem um id próprio: monte o ID de cada registro de associação a partir de matchedDataDatabaseId e accountType do registro, conforme descrito em Confirmar associações.

connected_accounts.folders

Liste as pastas (que o Google chama de grupos de contas) às quais uma conta conectada do Google tem acesso. Passe o folderId escolhido ao criar uma listagem no Google para que ela seja criada no lugar certo.

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)

Retorna a lista getFoldersUnderGoogleAccount. Cada item tem folderId (uma string accounts/{id} usada sem alterações), folderName e locationCount, cujo valor é null quando o Google não informa uma contagem. Apenas contas do tipo Google. Consulte Listar pastas e listings.create_gmb.

connected_accounts.disconnect_google

Desconecte uma conta inteira do Google. Todos os locais associados por meio dela deixam de sincronizar com o 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)

Retorna o objeto gmbBulkDisconnect com success. Consulte Desconectar uma conta do Google.

connected_accounts.disconnect_facebook

Desconecte uma conta inteira do 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)

Retorna o objeto fbBulkDisconnect com success. Consulte Desconectar uma conta do Facebook.

connected_accounts.oauth_disconnect

Desconecte um local de uma plataforma de publicação, mantendo o restante da conta conectado. Esta é a operação inversa de oauth_url.

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

site é GOOGLE, FACEBOOK ou APPLE, e o SDK converte o valor para maiúsculas antes de enviá-lo.

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

Retorna o objeto disconnectConnectedAccountsLocations com success e errors. Consulte Desconectar um local de uma plataforma de publicação.

Veja também