Listings APIListings API
Masuk

Akun terhubung

Hubungkan akun Google, Facebook, dan Apple Business Connect, cocokkan profil bisnis dengan lokasi, dan putuskan koneksi melalui client.connected_accounts.

Semua metode untuk akun terhubung berada di bawah client.connected_accounts. Akun terhubung adalah satu akun Google Business Profile, Facebook Pages, atau Apple Business Connect yang telah memberikan otorisasi kepada platform, yang diidentifikasi oleh connectedAccountId yang Anda dapatkan dari connected_accounts.list.

Ada dua cara untuk menghubungkan akun. Alur massal memberikan otorisasi untuk seluruh akun platform publikasi, lalu mencocokkan profil bisnisnya dengan lokasi Anda. Alur untuk satu lokasi membuat satu tautan OAuth untuk satu lokasi, yang sesuai jika aplikasi Anda menghubungkan toko satu per satu. Metode yang menerima location_id dapat menggunakan ID numerik atau ID yang dikodekan dengan base64, lihat ID Lokasi.

Alur pencocokan

Setelah koneksi massal, profil bisnis di platform publikasi belum ditautkan ke lokasi Anda. Panggil trigger_matches untuk memasukkan tugas pencocokan ke antrean, periksa details secara berkala hingga requestMatchesStatus bernilai MATCH_COMPLETED, baca pasangan yang ditemukan dengan suggestions, lalu simpan pasangan yang Anda inginkan dengan confirm_matches. Jika trigger_matches dilewati, suggestions tetap kosong.

connected_accounts.connect_google

Buat URL untuk memberikan otorisasi bagi seluruh akun Google Business Profile. Arahkan pengguna ke URL tersebut, lalu pengguna akan kembali ke success_url atau error_url. Tautan berlaku selama 24 jam.

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)

Mengembalikan objek bulkConnectLinkForGoogle. Baca url, lalu periksa success dan errors. Kedua URL pengalihan harus berupa URL https absolut. Lihat Menghubungkan akun Google.

connected_accounts.connect_facebook

Sama seperti connect_google, untuk akun Facebook Pages. Berlaku selama 24 jam.

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)

Mengembalikan objek bulkConnectLinkForFacebook, dengan field url, success, dan errors yang sama. Lihat Menghubungkan akun Facebook.

connected_accounts.oauth_url

Buat URL yang menghubungkan satu profil di platform publikasi ke satu lokasi. Gunakan ini jika Anda sudah mengetahui lokasi yang akan dihubungkan pengguna, sehingga langkah pencocokan tidak diperlukan. Berlaku selama 24 jam.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParameterTipeDeskripsi
location_idstr | intLokasi yang akan ditautkan dengan profil, dalam bentuk ID numerik atau base64.
sitestrGOOGLE, FACEBOOK, atau APPLE. SDK mengubah nilainya menjadi huruf kapital sebelum mengirimkannya.
success_urlstrURL https absolut tempat pengguna kembali jika berhasil.
error_urlstrURL https absolut tempat pengguna kembali jika gagal.
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)

Mengembalikan objek createConnectUrl. URL pengalihan yang relatif atau tidak dapat diurai menghasilkan success: true dengan null url, jadi periksa url itu sendiri, bukan hanya success. Tautan hanya dapat digunakan sekali, jadi buat tautan baru untuk setiap percobaan. Lihat Membuat URL koneksi OAuth untuk satu lokasi.

connected_accounts.list

Tampilkan daftar akun Google dan Facebook yang terhubung ke akun Anda. Di sinilah Anda mendapatkan connectedAccountId yang diperlukan oleh setiap pemanggilan berikutnya.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParameterTipeDeskripsi
publisherstrHanya akun untuk satu platform publikasi.
statusstrHanya akun dengan satu status koneksi tertentu, misalnya CONNECTED.
pageintNomor halaman dimulai dari 1.
per_pageintUkuran halaman. Dikirim sebagai 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)

Mengembalikan objek connectedAccountsInfo: records beserta pageInfo yang berisi hasNextPage, totalPages, dan totalRecords. Urutan selalu berdasarkan alamat email akun secara menaik. Lihat Menampilkan daftar akun terhubung.

connected_accounts.details

Ambil satu akun terhubung berdasarkan ID. Periksa akun ini secara berkala setelah trigger_matches dan tunggu hingga requestMatchesStatus mencapai 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"))

Mengembalikan objek connectedAccountDetails. Field berada di bawah details: status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus, dan lastFetchMatchesRequestedAt. Nilai connectivityIssue yang bukan null berarti token platform publikasi perlu diotorisasi ulang. Lihat Mengambil detail akun terhubung.

connected_accounts.listings

Tampilkan daftar profil bisnis di platform publikasi yang dapat diakses oleh akun terhubung, baik yang sudah maupun yang belum dicocokkan dengan salah satu lokasi Anda. Gunakan ini untuk menunjukkan kepada pengguna akses yang telah Anda peroleh.

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParameterTipeDeskripsi
connected_account_idstrAkun terhubung yang profil bisnisnya akan dibaca.
location_infostrFilter teks bebas untuk nama dan alamat profil bisnis.
pageintNomor halaman dimulai dari 1.
per_pageintUkuran halaman. Dikirim sebagai 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)

Endpoint ini menggunakan POST dan menerima semua argumen dalam body permintaan, bukan dalam query string; SDK menyusun body tersebut untuk Anda. Mengembalikan objek connectedAccountListings: records beserta pageInfo. Setiap record berisi id, locationName, address, phone, accountTypeName, dan liveLink. Lihat Mengambil profil bisnis dari akun terhubung.

connected_accounts.trigger_matches

Masukkan ke antrean tugas yang mengambil semua profil yang dapat diakses oleh akun yang ditentukan dan mencocokkannya dengan lokasi Anda. Jalankan tugas ini segera setelah koneksi massal, lalu jalankan kembali setelah Anda menambahkan lokasi.

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)

Mengembalikan objek connectedAccountsTriggerMatches dengan success dan failedIds. Tugas dijalankan secara asinkron, jadi success: true berarti tugas telah masuk antrean, bukan selesai. Periksa details secara berkala hingga requestMatchesStatus bernilai MATCH_COMPLETED sebelum membaca saran. Lihat Memicu pencocokan.

connected_accounts.suggestions

Baca pasangan antara profil bisnis akun dan lokasi Anda yang ditemukan oleh tugas pencocokan. Tampilkan pasangan ini kepada pengguna untuk ditinjau sebelum dikonfirmasi.

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)

Mengembalikan objek connectionSuggestionsForAccount: records beserta pageInfo. Setiap record berisi locationId, accountType, matchedDataDatabaseId, locationInfo, dan suggestedLocationInfo. records yang kosong dengan totalRecords: 0 biasanya berarti tugas pencocokan belum dijalankan. Lihat Menampilkan daftar saran koneksi.

connected_accounts.confirm_matches

Simpan pasangan yang disarankan. Setelah dikonfirmasi, profil bisnis di platform publikasi mulai disinkronkan dengan lokasi yang cocok.

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)

Mengembalikan objek confirmConnectMatches dengan success dan failedIds. Record saran tidak memiliki id sendiri: susun ID setiap record pencocokan dari matchedDataDatabaseId dan accountType milik record tersebut, seperti yang dijelaskan di Mengonfirmasi hasil pencocokan.

connected_accounts.folders

Tampilkan daftar folder (Google menyebutnya grup akun) yang dapat diakses oleh akun Google terhubung. Sertakan folderId yang dipilih saat Anda membuat profil bisnis Google agar profil tersebut ditempatkan di folder yang tepat.

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)

Mengembalikan daftar getFoldersUnderGoogleAccount. Setiap item memiliki folderId (string accounts/{id} yang digunakan tanpa perubahan), folderName, dan locationCount, yang bernilai null jika Google tidak melaporkan jumlahnya. Hanya untuk akun bertipe Google. Lihat Menampilkan daftar folder dan listings.create_gmb.

connected_accounts.disconnect_google

Putuskan koneksi seluruh akun Google. Setiap lokasi yang dicocokkan melalui akun tersebut berhenti disinkronkan dengan 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)

Mengembalikan objek gmbBulkDisconnect dengan success. Lihat Memutuskan koneksi akun Google.

connected_accounts.disconnect_facebook

Putuskan koneksi seluruh akun 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)

Mengembalikan objek fbBulkDisconnect dengan success. Lihat Memutuskan koneksi akun Facebook.

connected_accounts.oauth_disconnect

Putuskan koneksi satu lokasi dari satu platform publikasi, sementara bagian akun lainnya tetap terhubung. Ini merupakan operasi kebalikan dari oauth_url.

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

site adalah GOOGLE, FACEBOOK, atau APPLE, dan SDK mengubah nilainya menjadi huruf kapital sebelum mengirimkannya.

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

Mengembalikan objek disconnectConnectedAccountsLocations dengan success dan errors. Lihat Memutuskan koneksi satu lokasi dari platform publikasi.

Lihat juga