Listings APIListings API
登入

連結 Facebook 粉絲專頁

建立 Facebook 連結網址，將擁有者的粉絲專頁與您的地點配對，確認或手動選擇連結，並在客戶離開時中斷帳號連結。

已連結的 Facebook 帳號可讓地點在 Facebook 上使用發布與報表功能。連結粉絲專頁後，貼文即可在 postSites 中以 FACEBOOK 為目標，Facebook 分析端點會傳回粉絲專頁指標，而非 null，該粉絲專頁也會新增為評論來源，讓其評論與其他評論一併匯入，且地點進階商家資訊中的 Facebook 列會脫離 REQUIRING_ACTION 狀態。

流程與 Google 相同：建立連結、讓擁有者同意授權、配對、確認。Facebook 使用的值若有不同，文中會特別指出。

Facebook 粉絲專頁必須已在 Facebook 上設定營業時間。即使地點具有 businessHours，Facebook 仍會拒絕 ListingsAPI 對未設定營業時間的粉絲專頁所送出的更新。Facebook 商家資訊隨後會維持 IN_PROGRESS，並附上指出缺少營業時間的 syncIssue。若要修正，請在 Facebook 上為該粉絲專頁新增營業時間，然後傳送地點更新。

請求主體只包含您的兩個重新導向 URL。此連結僅適用於擁有該金鑰的帳戶，有效期限為 24 小時。

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 是預留位置。請將擁有者導向您自己的回應中傳回的 url。

將擁有者重新導向至 url。擁有者接受 Facebook 條款、授予粉絲專頁權限後，便會抵達您的 successUrl。

2. OAuth 返回後列出已連結帳戶

依 publisher=FacebookAccount 篩選。此處採用位移量分頁：包含 records[] 與 pageInfo.totalRecords，並使用 page 和 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        }      ]    }  }}

保留 connectedAccountId。status 的值為 CONNECTED、MATCH_IN_PROGRESS 或 CONNECTIVITY_ISSUE；只要不是 CONNECTED，擁有者就必須重新授權，後續步驟才能正常運作。

3. 觸發配對並等待完成

配對程序會擷取該帳號可存取的粉絲專頁，並將每個粉絲專頁與您的一個地點配對。程序會在背景執行，因此請輪詢帳號詳細資料，直到 requestMatchesStatus 為 MATCH_COMPLETED。若在此之前讀取建議，會傳回空的 records 陣列，看起來就像「沒有配對結果」。

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"

詳細資料記錄會在 data.connectedAccountDetails.details 傳回。MATCH_COMPLETED 表示配對程序已完成；在您確認之前，不會建立任何連結，因此 connectedLocationsCount 目前仍維持 0。

4. 檢視並確認建議

每筆記錄都會將您的地點（locationInfo、locationId）與一個粉絲專頁（suggestedLocationInfo）配對。對 Facebook 帳號而言，accountType 是 FB，而非 GMB，因此您傳送以進行確認的 id 也會不同。

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"

建議中沒有 id。請從 accountType 選取類型，並將 <MatchRecordType>:<matchedDataDatabaseId> 以 base64 編碼來建立此值。參考文件只提供 Google 範例，其解碼結果為 GmbLocationMatchedData:...；類型會因發布平台而異。Facebook 的類型為 FbLocationMatchedData，因此 FB 搭配 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc 會編碼為 RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==。

accountType配對記錄類型
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=="] } }'

回應為 data.confirmConnectMatches，包含 success 與 failedIds，後者是無法確認的已解碼資料庫 id。以錯誤類型建立的 id 會傳回 200，其中包含 success: false，但沒有 failedIds，因此請務必檢查 success。

5. 手動將粉絲專頁連結至地點

當配對程序無法確定配對結果，或粉絲專頁是在配對程序執行後才建立時，請列出該帳號可查看的粉絲專頁，並直接連結其中一個。connectedAccountId 應放在商家資訊呼叫的 JSON 主體中；若將它作為查詢參數，則會遭到忽略，您取得的將是第一個已連結帳戶的商家資訊。

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>"  }}'

每筆商家資訊記錄都包含 id、locationName、address 和 liveLink。其中的 id 就是 connect-listing 接受的 connectedAccountListingId；該欄位的名稱並非 listingId。連結失敗時會傳回 success: false，並附上 message，例如 Listing record not found。

6. 客戶離開時中斷帳號連結

中斷連結會套用至整個帳號：透過該帳號連結的所有粉絲專頁都會停止同步，也不再接收 Facebook 互動資料。若要解除單一地點的連結並保留帳號，請改用 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" } }'

回應為 data.fbBulkDisconnect，並包含 success。即使 connectedAccountId 未知，回應仍為 true，因此這表示「已處理」，而非「已移除有效連線」。若您需要確認，請再次列出已連結帳戶。

7. 接下來會發生什麼事

每個已連結的地點都會觸發包含 data.platform: "facebook" 的 connection.location_connected 事件，而解除連結時則會觸發 connection.location_disconnected。如果 Facebook 撤銷授權，您會收到 connection.reauth_required：請建立新連結（步驟 1），並請擁有者再次同意授予所有權限。連結完成後，地點的進階商家資訊中，Facebook 那一列會變為 SYNCED，postSites: ["FACEBOOK"] 會成為有效目標，且 Facebook 分析端點會開始傳回資料。

後續步驟