Listings APIListings API
Iniciar sesión

Conectar páginas de Facebook

Crea un enlace de conexión a Facebook, vincula páginas del dueño a tus ubicaciones, confirma o elige vínculos y desconecta la cuenta si el cliente se va.

Una cuenta de Facebook conectada permite publicar y generar informes para una ubicación en Facebook. Una vez vinculada una página, las publicaciones pueden dirigirse a FACEBOOK en postSites, el endpoint de analíticas de Facebook devuelve métricas de la página en lugar de null, la página se añade como fuente de reseñas para que sus reseñas lleguen junto con las demás y la fila de Facebook en las fichas premium de la ubicación deja de estar en REQUIRING_ACTION.

El flujo es el mismo que con Google: crea un enlace, deja que el propietario dé su consentimiento, empareja y confirma. Se indica cada valor que es diferente para Facebook.

La página de Facebook ya debe tener un horario de apertura configurado en Facebook. Facebook rechaza una actualización de ListingsAPI a una página que no tenga horario, incluso cuando la ubicación tenga businessHours. En ese caso, la ficha de Facebook permanece en IN_PROGRESS con un syncIssue sobre la falta de horario. Para solucionarlo, añade el horario de apertura a la página en Facebook y luego envía una actualización de la ubicación.

El cuerpo solo contiene tus dos URL de redirección. El enlace está limitado a la cuenta a la que pertenece la clave y tiene una validez de 24 horas.

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

El url anterior es un marcador de posición. Envía al propietario al url que recibas en tu propia respuesta.

Redirige al propietario a url. Este acepta las condiciones de Facebook, concede los permisos de la página y llega a tu successUrl.

2. Lista las cuentas conectadas tras el retorno de OAuth

Filtra por publisher=FacebookAccount. Esta es una página con desplazamiento: records[] más pageInfo.totalRecords, paginada mediante page y 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        }      ]    }  }}

Guarda el connectedAccountId. status es CONNECTED, MATCH_IN_PROGRESS o CONNECTIVITY_ISSUE; cualquier valor distinto de CONNECTED significa que el propietario debe volver a autorizar la conexión para que funcionen los siguientes pasos.

3. Inicia el emparejamiento y espera a que termine

El emparejamiento recupera las páginas a las que puede acceder la cuenta y empareja cada una con una de tus ubicaciones. Se ejecuta en segundo plano, así que consulta periódicamente los detalles de la cuenta hasta que requestMatchesStatus sea MATCH_COMPLETED. Consultar las sugerencias antes de ese momento devuelve un array records vacío que parece indicar que «no hay coincidencias».

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"

El registro de detalles se devuelve en data.connectedAccountDetails.details. MATCH_COMPLETED significa que el proceso de emparejamiento ha terminado; no se vincula nada hasta que lo confirmes, por lo que connectedLocationsCount permanece en 0 por ahora.

4. Revisa y confirma las sugerencias

Cada registro empareja tu ubicación (locationInfo, locationId) con una página (suggestedLocationInfo). Para una cuenta de Facebook, accountType es FB en lugar de GMB, y eso cambia el identificador que envías para confirmar.

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"

Una sugerencia no tiene id. Crea uno codificando <MatchRecordType>:<matchedDataDatabaseId> en base64 y eligiendo el tipo de accountType. La referencia solo muestra un ejemplo de Google, que al decodificarse da GmbLocationMatchedData:...; el tipo varía según la plataforma de publicación. Para Facebook es FbLocationMatchedData, por lo que FB con 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc se codifica como RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==.

accountTypeTipo de registro de emparejamiento
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 respuesta es data.confirmConnectMatches con success y failedIds, los identificadores decodificados de la base de datos que no se pudieron confirmar. Un identificador creado con el tipo incorrecto devuelve 200 con success: false y sin failedIds, así que comprueba siempre success.

5. Vincula una página a una ubicación manualmente

Cuando el proceso de emparejamiento no tiene certeza, o se ha creado una página después de ejecutarlo, lista las páginas que la cuenta puede ver y vincula una directamente. connectedAccountId va en el cuerpo JSON de la llamada de fichas; si se envía como parámetro de consulta, se ignora y obtienes las fichas de la primera cuenta conectada.

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

Cada registro de ficha contiene id, locationName, address y liveLink. Su id es el connectedAccountListingId que acepta connect-listing; el campo no se llama listingId. Un intento de vinculación fallido devuelve success: false con un message como Listing record not found.

6. Desconecta la cuenta cuando un cliente se vaya

La desconexión es total: todas las páginas vinculadas a través de la cuenta dejan de sincronizarse y las interacciones de Facebook dejan de llegar. Para desvincular una ubicación y conservar la cuenta, usa 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 respuesta es data.fbBulkDisconnect con success. Es true incluso si connectedAccountId es desconocido, por lo que significa "procesado", no "se ha eliminado una conexión activa". Vuelve a consultar la lista de cuentas conectadas si necesitas asegurarte.

7. Qué ocurre después

Se emite un evento connection.location_connected con data.platform: "facebook" por cada ubicación vinculada, y se emite connection.location_disconnected cuando desvinculas. Si Facebook invalida la autorización, recibes connection.reauth_required: crea un nuevo enlace (paso 1) y pide al propietario que vuelva a dar su consentimiento con todos los permisos. Una vez establecida la vinculación, la fila de Facebook en las fichas prémium de la ubicación pasa a SYNCED, postSites: ["FACEBOOK"] se convierte en un destino válido y el endpoint de analítica de Facebook empieza a devolver datos.

Próximos pasos