Listings APIListings API
Masuk

Hubungkan Halaman Facebook

Buat tautan koneksi Facebook, cocokkan Halaman pemilik ke lokasi Anda, konfirmasi atau pilih sendiri tautan, dan putuskan koneksi akun saat klien berhenti.

Akun Facebook yang terhubung memungkinkan publikasi dan pelaporan untuk suatu lokasi di Facebook. Setelah Halaman ditautkan, postingan dapat menargetkan FACEBOOK dalam postSites, endpoint analitik Facebook mengembalikan metrik Halaman sebagai pengganti null, Halaman ditambahkan sebagai sumber ulasan sehingga ulasannya masuk bersama ulasan lainnya, dan baris Facebook dalam profil bisnis premium lokasi tersebut tidak lagi berstatus REQUIRING_ACTION.

Alurnya sama seperti Google: buat tautan, minta pemilik memberikan persetujuan, cocokkan, lalu konfirmasikan. Nilai yang berbeda untuk Facebook dijelaskan secara khusus.

Jam buka Halaman Facebook harus sudah diatur di Facebook. Facebook menolak pembaruan dari ListingsAPI ke Halaman yang tidak memiliki jam buka, meskipun lokasi tersebut memiliki businessHours. Profil bisnis Facebook kemudian tetap berstatus IN_PROGRESS dengan syncIssue tentang jam buka yang belum diisi. Untuk memperbaikinya, tambahkan jam buka ke Halaman di Facebook, lalu kirim pembaruan lokasi.

Isi permintaan hanya memuat dua URL pengalihan Anda. Tautan tersebut hanya berlaku untuk akun pemilik kunci dan berlaku selama 24 jam.

Connect link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/facebook/success",    "errorUrl": "https://app.example.com/connect/facebook/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForFacebook": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

url di atas adalah contoh pengganti. Arahkan pemilik ke url yang dikembalikan dalam respons Anda sendiri.

Arahkan pemilik ke url. Pemilik menerima ketentuan Facebook, memberikan izin Halaman, dan diarahkan ke successUrl Anda.

2. Tampilkan daftar akun yang terhubung setelah alur OAuth kembali

Filter berdasarkan publisher=FacebookAccount. Ini adalah halaman berbasis offset: records[] ditambah pageInfo.totalRecords, dengan paginasi menggunakan page dan perPage.

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=FacebookAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",          "connectedAccountType": "FacebookAccount",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

Simpan connectedAccountId. Nilai status adalah CONNECTED, MATCH_IN_PROGRESS, atau CONNECTIVITY_ISSUE; nilai apa pun selain CONNECTED berarti pemilik harus melakukan otorisasi ulang agar langkah-langkah berikutnya dapat dijalankan.

3. Mulai pencocokan dan tunggu hingga selesai

Pencocokan mengambil Halaman yang dapat diakses akun dan memasangkan masing-masing dengan salah satu lokasi Anda. Proses ini berjalan di latar belakang, jadi periksa detail akun secara berkala hingga requestMatchesStatus bernilai MATCH_COMPLETED. Membaca saran sebelum proses tersebut selesai akan mengembalikan array records kosong yang tampak seperti "tidak ada kecocokan".

Trigger and poll
curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["d2397854-52c2-41d7-95f1-b90cba16498d"] } }' # then, every 15 seconds until requestMatchesStatus is MATCH_COMPLETEDcurl https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/details \-H "Authorization: API $LISTINGSAPI_KEY"

Catatan detail dikembalikan di data.connectedAccountDetails.details. MATCH_COMPLETED berarti proses pencocokan telah selesai; belum ada yang ditautkan hingga Anda mengonfirmasi, jadi connectedLocationsCount tetap bernilai 0 untuk saat ini.

4. Tinjau dan konfirmasikan saran

Setiap catatan memasangkan lokasi Anda (locationInfo, locationId) dengan sebuah Halaman (suggestedLocationInfo). Untuk akun Facebook, accountType bernilai FB, bukan GMB, dan hal itu mengubah id yang Anda kirim untuk konfirmasi.

Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

Saran tidak memiliki id. Buat nilainya dengan mengodekan <MatchRecordType>:<matchedDataDatabaseId> ke base64, dengan memilih jenis dari accountType. Referensi hanya menampilkan contoh Google, yang setelah didekode menghasilkan GmbLocationMatchedData:...; jenisnya berbeda untuk setiap platform publikasi. Untuk Facebook, jenisnya adalah FbLocationMatchedData, sehingga FB dengan 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc dikodekan menjadi RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==.

accountTypeJenis catatan pencocokan
GMBGmbLocationMatchedData
FBFbLocationMatchedData
APPLEAppleLocationMatchedData
Confirm matches
# base64 of FbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw=="] } }'

Responsnya adalah data.confirmConnectMatches dengan success dan failedIds, yaitu id basis data yang telah didekode dan tidak dapat dikonfirmasi. Id yang dibuat dengan jenis yang salah mengembalikan 200 dengan success: false dan tanpa failedIds, jadi selalu periksa success.

5. Tautkan Halaman ke lokasi secara manual

Jika proses pencocokan tidak dapat menentukan kecocokan dengan pasti, atau Halaman dibuat setelah proses pencocokan dijalankan, tampilkan daftar Halaman yang dapat dilihat akun dan tautkan salah satunya secara langsung. connectedAccountId harus ditempatkan dalam isi JSON pada panggilan profil bisnis; jika ditempatkan sebagai parameter kueri, nilai tersebut diabaikan dan Anda mendapatkan profil bisnis dari akun terhubung pertama.

Pick and link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d", "locationInfo": "Lincoln" }' curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",    "connectedAccountListingId": "<id from the listings response>"  }}'

Setiap catatan profil bisnis memuat id, locationName, address, dan liveLink. Nilai id pada catatan tersebut adalah connectedAccountListingId yang diterima connect-listing; nama kolomnya bukan listingId. Penautan yang gagal mengembalikan success: false dengan message seperti Listing record not found.

6. Putuskan koneksi akun saat klien berhenti menggunakan layanan

Pemutusan koneksi berlaku untuk seluruh akun: setiap Halaman yang ditautkan melalui akun tersebut berhenti disinkronkan dan interaksi Facebook berhenti diterima. Untuk melepaskan satu lokasi sambil tetap mempertahankan akun, gunakan disconnect-listing.

Disconnect
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'

Responsnya adalah data.fbBulkDisconnect dengan success. Responsnya tetap true bahkan untuk connectedAccountId yang tidak dikenal, sehingga artinya adalah "telah diproses", bukan "koneksi aktif telah dihapus". Ambil kembali daftar akun yang terhubung jika Anda memerlukan kepastian.

7. Apa yang terjadi selanjutnya

Peristiwa connection.location_connected dengan data.platform: "facebook" dipicu untuk setiap lokasi yang ditautkan, dan connection.location_disconnected dipicu saat Anda memutuskan tautan. Jika Facebook membatalkan otorisasi yang diberikan, Anda menerima connection.reauth_required: buat tautan baru (langkah 1) dan minta pemilik untuk memberikan persetujuan lagi dengan menyertakan semua izin. Setelah ditautkan, baris Facebook dalam daftar profil bisnis premium lokasi tersebut beralih ke SYNCED, postSites: ["FACEBOOK"] menjadi target yang valid, dan endpoint analitik Facebook mulai mengembalikan data.

Langkah berikutnya