Listings APIListings API
Anmelden

Facebook-Seiten verbinden

Erstellen Sie einen Facebook-Link, ordnen Sie Inhaberseiten Standorten zu, bestätigen oder wählen Sie Links; bei Kundenabgang trennen Sie das Konto.

Ein verbundenes Facebook-Konto ermöglicht die Veröffentlichung und Berichterstellung für einen Standort auf Facebook. Sobald eine Seite verknüpft ist, können Beiträge FACEBOOK in postSites als Ziel verwenden, der Facebook-Analyse-Endpunkt gibt Seitenkennzahlen statt null zurück, die Seite wird als Bewertungsquelle hinzugefügt, sodass ihre Bewertungen zusammen mit den übrigen eingehen, und die Facebook-Zeile in den Premium-Einträgen des Standorts verlässt den Status REQUIRING_ACTION.

Der Ablauf ist derselbe wie bei Google: Link erstellen, den Inhaber zustimmen lassen, Zuordnungen ermitteln und bestätigen. Wo sich ein Wert für Facebook unterscheidet, wird darauf hingewiesen.

Für die Facebook-Seite müssen bereits Öffnungszeiten auf Facebook hinterlegt sein. Facebook lehnt ein Update von ListingsAPI für eine Seite ohne Öffnungszeiten ab, selbst wenn der Standort businessHours hat. Der Facebook-Eintrag bleibt dann im Status IN_PROGRESS mit einem syncIssue zu fehlenden Öffnungszeiten. Um dies zu beheben, fügen Sie der Seite auf Facebook die Öffnungszeiten hinzu und senden Sie anschließend ein Standort-Update.

Der Anfragetext enthält nur Ihre beiden Weiterleitungs-URLs. Der Link ist auf das Konto beschränkt, dem der Schlüssel gehört, und ist 24 Stunden gültig.

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 oben ist ein Platzhalter. Leiten Sie den Inhaber zu url weiter, das in Ihrer eigenen Antwort zurückgegeben wird.

Leiten Sie den Inhaber zu url weiter. Er akzeptiert die Bedingungen von Facebook, erteilt die Seitenberechtigungen und gelangt zu Ihrem successUrl.

2. Verbundene Konten nach der Rückkehr von OAuth auflisten

Filtern Sie nach publisher=FacebookAccount. Dies ist eine offsetbasierte Ergebnisseite: records[] plus pageInfo.totalRecords, mit page und perPage paginiert.

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        }      ]    }  }}

Bewahren Sie connectedAccountId auf. status ist CONNECTED, MATCH_IN_PROGRESS oder CONNECTIVITY_ISSUE; jeder andere Wert als CONNECTED bedeutet, dass der Inhaber die Verbindung erneut autorisieren muss, bevor die nächsten Schritte funktionieren.

3. Zuordnung starten und auf den Abschluss warten

Die Zuordnung ruft die Seiten ab, auf die das Konto zugreifen kann, und ordnet jede einem Ihrer Standorte zu. Sie läuft im Hintergrund. Fragen Sie daher die Kontodetails wiederholt ab, bis requestMatchesStatus den Wert MATCH_COMPLETED hat. Wenn Sie die Vorschläge vorher abrufen, wird ein leeres records-Array zurückgegeben, das wie „keine Übereinstimmungen“ aussieht.

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"

Der Detaildatensatz wird unter data.connectedAccountDetails.details zurückgegeben. MATCH_COMPLETED bedeutet, dass der Zuordnungsprozess abgeschlossen ist; bis zu Ihrer Bestätigung wird nichts verknüpft, daher bleibt connectedLocationsCount vorerst auf 0.

4. Vorschläge prüfen und bestätigen

Jeder Datensatz ordnet Ihren Standort (locationInfo, locationId) einer Seite (suggestedLocationInfo) zu. Bei einem Facebook-Konto ist accountType gleich FB statt GMB, und dadurch ändert sich die ID, die Sie zur Bestätigung senden.

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"

Ein Vorschlag hat kein id. Erstellen Sie eines als Base64-Kodierung von <MatchRecordType>:<matchedDataDatabaseId> und wählen Sie dabei den Typ aus accountType. Die Referenz zeigt nur ein Google-Beispiel, das zu GmbLocationMatchedData:... dekodiert wird; der Typ unterscheidet sich je nach Plattform. Für Facebook lautet er FbLocationMatchedData, daher wird FB mit 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc als RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw== kodiert.

accountTypeTyp des Zuordnungsdatensatzes
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=="] } }'

Die Antwort ist data.confirmConnectMatches mit success und failedIds, den dekodierten Datenbank-IDs, die nicht bestätigt werden konnten. Bei einer ID, die mit dem falschen Typ erstellt wurde, wird 200 mit success: false und ohne failedIds zurückgegeben. Prüfen Sie daher immer success.

5. Eine Seite manuell mit einem Standort verknüpfen

Wenn der Zuordnungsprozess kein eindeutiges Ergebnis liefert oder eine Seite erst nach dessen Ausführung erstellt wurde, listen Sie die für das Konto sichtbaren Seiten auf und verknüpfen Sie eine davon direkt. connectedAccountId gehört in den JSON-Anfragetext des listings-Aufrufs; als Abfrageparameter wird es ignoriert, und Sie erhalten die Einträge des ersten verbundenen Kontos.

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

Jeder Eintragsdatensatz enthält id, locationName, address und liveLink. Sein id ist das connectedAccountListingId, das connect-listing entgegennimmt; das Feld heißt nicht listingId. Bei einer fehlgeschlagenen Verknüpfung wird success: false mit einem message wie Listing record not found zurückgegeben.

6. Trennen Sie das Konto, wenn ein Kunde die Zusammenarbeit beendet

Die Trennung erfolgt vollständig oder gar nicht: Für jede über das Konto verknüpfte Seite wird die Synchronisierung beendet, und Facebook-Interaktionen gehen nicht mehr ein. Um einen einzelnen Standort zu trennen und das Konto beizubehalten, verwenden Sie stattdessen 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" } }'

Die Antwort lautet data.fbBulkDisconnect mit success. Sie lautet auch bei einer unbekannten connectedAccountId true und bedeutet daher „verarbeitet“, nicht „eine aktive Verbindung wurde entfernt“. Listen Sie die verbundenen Konten erneut auf, wenn Sie Gewissheit benötigen.

7. Was als Nächstes passiert

Für jeden verknüpften Standort wird ein connection.location_connected-Ereignis mit data.platform: "facebook" ausgelöst, und beim Aufheben der Verknüpfung wird connection.location_disconnected ausgelöst. Wenn Facebook die erteilte Autorisierung für ungültig erklärt, erhalten Sie connection.reauth_required: Erstellen Sie einen neuen Link (Schritt 1) und bitten Sie den Inhaber, erneut mit sämtlichen Berechtigungen zuzustimmen. Nach der Verknüpfung wechselt die Facebook-Zeile in den Premium-Einträgen des Standorts zu SYNCED, postSites: ["FACEBOOK"] wird zu einem gültigen Ziel, und der Facebook-Analyse-Endpunkt beginnt, Daten zurückzugeben.

Nächste Schritte