Listings APIListings API
Se connecter

Connecter des Pages Facebook

Créez un lien Facebook, liez les Pages du propriétaire à vos établissements, validez ou choisissez les liens, déconnectez le compte au départ du client.

Un compte Facebook connecté permet de publier du contenu et d'obtenir des rapports pour un établissement sur Facebook. Une fois une Page associée, les publications peuvent cibler FACEBOOK dans postSites, l'endpoint d'analyse Facebook renvoie les métriques de la Page au lieu de null, la Page est ajoutée comme source d'avis pour que ses avis arrivent avec les autres, et la ligne Facebook dans les fiches premium de l'établissement quitte l'état REQUIRING_ACTION.

Le processus est le même que pour Google : créer un lien, laisser le propriétaire donner son consentement, rechercher les correspondances, puis confirmer. Toute valeur différente pour Facebook est signalée.

Les horaires d'ouverture de la Page Facebook doivent déjà être définis sur Facebook. Facebook refuse toute mise à jour envoyée par ListingsAPI à une Page sans horaires, même lorsque l'établissement dispose de businessHours. La fiche Facebook reste alors à l'état IN_PROGRESS avec un syncIssue concernant les horaires manquants. Pour résoudre ce problème, ajoutez les horaires d'ouverture à la Page sur Facebook, puis envoyez une mise à jour de l'établissement.

Le corps contient uniquement vos deux URL de redirection. Le lien est limité au compte auquel appartient la clé et reste valide pendant 24 heures.

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

La valeur url ci-dessus est un exemple à remplacer. Dirigez le propriétaire vers url renvoyé dans votre propre réponse.

Redirigez le propriétaire vers url. Il accepte les conditions de Facebook, accorde les autorisations relatives aux Pages et arrive sur votre successUrl.

2. Lister les comptes connectés après le retour OAuth

Filtrez par publisher=FacebookAccount. Il s'agit d'une page de résultats avec pagination par décalage : records[] et pageInfo.totalRecords, paginés avec page et 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        }      ]    }  }}

Conservez connectedAccountId. status vaut CONNECTED, MATCH_IN_PROGRESS ou CONNECTIVITY_ISSUE ; toute valeur autre que CONNECTED signifie que le propriétaire doit accorder à nouveau son autorisation pour que les étapes suivantes fonctionnent.

3. Lancer la recherche de correspondances et attendre qu'elle se termine

La recherche de correspondances récupère les Pages accessibles au compte et associe chacune à l'un de vos établissements. Elle s'exécute en arrière-plan ; interrogez donc régulièrement les détails du compte jusqu'à ce que requestMatchesStatus vaille MATCH_COMPLETED. Consulter les suggestions avant ce moment renvoie un tableau records vide qui donne l'impression qu'il n'y a « aucune correspondance ».

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"

L'enregistrement contenant les détails est renvoyé à l'emplacement data.connectedAccountDetails.details. MATCH_COMPLETED signifie que la recherche de correspondances est terminée ; aucune association n'est établie tant que vous n'avez pas confirmé, donc connectedLocationsCount reste à 0 pour le moment.

4. Examiner et confirmer les suggestions

Chaque enregistrement associe votre établissement (locationInfo, locationId) à une Page (suggestedLocationInfo). Pour un compte Facebook, accountType vaut FB plutôt que GMB, ce qui change l'identifiant que vous envoyez pour confirmer.

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"

Une suggestion n'a pas de id. Construisez-en un en encodant <MatchRecordType>:<matchedDataDatabaseId> en base64 et en choisissant le type dans accountType. La documentation de référence ne présente qu'un exemple Google, qui se décode en GmbLocationMatchedData:... ; le type varie selon la plateforme de publication. Pour Facebook, il s'agit de FbLocationMatchedData, donc FB avec 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc s'encode en RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==.

accountTypeType d'enregistrement de correspondance
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=="] } }'

La réponse est data.confirmConnectMatches avec success et failedIds, les identifiants décodés de la base de données qui n'ont pas pu être confirmés. Un identifiant construit avec le mauvais type entraîne une réponse 200 avec success: false et sans failedIds ; vérifiez donc toujours success.

5. Associer manuellement une Page à un établissement

Lorsque la recherche de correspondances est incertaine, ou qu'une Page a été créée après son exécution, listez les Pages visibles par le compte et associez-en une directement. connectedAccountId doit figurer dans le corps JSON de l'appel de récupération des fiches ; s'il est passé comme paramètre de requête, il est ignoré et vous obtenez les fiches du premier compte connecté.

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

Chaque enregistrement de fiche contient id, locationName, address et liveLink. Son champ id correspond au connectedAccountListingId attendu par connect-listing ; le champ ne s'appelle pas listingId. En cas d'échec de l'association, la réponse est success: false avec un message tel que Listing record not found.

6. Déconnecter le compte lorsqu’un client vous quitte

La déconnexion est totale : toutes les Pages liées via le compte cessent de se synchroniser et les interactions Facebook cessent d’arriver. Pour dissocier un seul établissement tout en conservant le compte, utilisez plutôt 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" } }'

La réponse est data.fbBulkDisconnect avec success. Elle est true même pour un connectedAccountId inconnu : elle signifie donc « traité », et non « une connexion active a été supprimée ». Listez à nouveau les comptes connectés si vous avez besoin d’une certitude.

7. Ce qui se passe ensuite

Un événement connection.location_connected avec data.platform: "facebook" est déclenché pour chaque établissement lié, et connection.location_disconnected est déclenché lorsque vous supprimez le lien. Si Facebook invalide l’autorisation accordée, vous recevez connection.reauth_required : créez un nouveau lien (étape 1) et demandez au propriétaire de donner à nouveau son consentement en accordant toutes les autorisations. Une fois la connexion établie, la ligne Facebook dans les fiches premium de l’établissement passe à SYNCED, postSites: ["FACEBOOK"] devient une cible valide et l’endpoint d’analyse Facebook commence à renvoyer des données.

Étapes suivantes