Listings APIListings API
Accedi

Collega le Pagine Facebook

Crea un link per collegare Facebook, abbina le Pagine del titolare alle tue sedi, conferma o scegli i link e scollega l'account quando il cliente va via.

Un account Facebook collegato consente la pubblicazione e la creazione di report per una sede su Facebook. Una volta collegata una Pagina, i post possono avere come destinazione FACEBOOK in postSites, l'endpoint di analisi di Facebook restituisce le metriche della Pagina anziché null, la Pagina viene aggiunta come fonte di recensioni in modo che le sue recensioni arrivino insieme alle altre e la riga Facebook nelle schede premium della sede esce dallo stato REQUIRING_ACTION.

La procedura è la stessa di Google: crea un link, lascia che il proprietario dia il consenso, esegui l'abbinamento e conferma. I valori che differiscono per Facebook sono indicati esplicitamente.

La Pagina Facebook deve avere già gli orari di apertura impostati su Facebook. Facebook rifiuta un aggiornamento da ListingsAPI a una Pagina priva di orari, anche quando la sede ha businessHours. La scheda Facebook rimane quindi nello stato IN_PROGRESS con un syncIssue relativo agli orari mancanti. Per risolvere il problema, aggiungi gli orari di apertura alla Pagina su Facebook, quindi invia un aggiornamento della sede.

Il corpo contiene solo i tuoi due URL di reindirizzamento. Il link è limitato all'account a cui appartiene la chiave ed è valido per 24 ore.

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

Il valore url riportato sopra è un segnaposto. Indirizza il proprietario al valore url restituito nella tua risposta.

Reindirizza il proprietario a url. Il proprietario accetta i termini di Facebook, concede le autorizzazioni per le Pagine e viene reindirizzato al tuo successUrl.

2. Elenca gli account collegati dopo il ritorno da OAuth

Filtra per publisher=FacebookAccount. Si tratta di una pagina con offset: records[] più pageInfo.totalRecords, con paginazione tramite page e 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        }      ]    }  }}

Conserva connectedAccountId. status può essere CONNECTED, MATCH_IN_PROGRESS o CONNECTIVITY_ISSUE; qualsiasi valore diverso da CONNECTED significa che il proprietario deve autorizzare di nuovo il collegamento affinché i passaggi successivi funzionino.

3. Avvia l'abbinamento e attendi che termini

L'abbinamento recupera le Pagine a cui l'account può accedere e associa ciascuna a una delle tue sedi. Viene eseguito in background, quindi interroga periodicamente i dettagli dell'account finché requestMatchesStatus non è MATCH_COMPLETED. Leggere i suggerimenti prima di quel momento restituisce un array records vuoto che sembra indicare "nessun abbinamento".

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"

Il record dei dettagli viene restituito in data.connectedAccountDetails.details. MATCH_COMPLETED significa che il processo di abbinamento è terminato; nulla viene collegato finché non confermi, quindi per ora connectedLocationsCount rimane 0.

4. Esamina e conferma i suggerimenti

Ogni record abbina la tua sede (locationInfo, locationId) a una Pagina (suggestedLocationInfo). Per un account Facebook, accountType è FB anziché GMB e questo cambia l'id che invii per confermare.

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"

Un suggerimento non ha un id. Creane uno codificando <MatchRecordType>:<matchedDataDatabaseId> in base64 e scegliendo il tipo da accountType. La documentazione di riferimento mostra solo un esempio di Google, che una volta decodificato dà GmbLocationMatchedData:...; il tipo varia in base alla piattaforma di pubblicazione. Per Facebook è FbLocationMatchedData, quindi FB con 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc viene codificato come RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==.

accountTypeTipo di record di abbinamento
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 risposta è data.confirmConnectMatches con success e failedIds, gli id decodificati del database che non è stato possibile confermare. Un id creato con il tipo sbagliato restituisce 200 con success: false e senza failedIds, quindi controlla sempre success.

5. Collega manualmente una Pagina a una sede

Quando il processo di abbinamento non è sicuro del risultato, oppure una Pagina è stata creata dopo la sua esecuzione, elenca le Pagine visibili all'account e collegane una direttamente. connectedAccountId va nel corpo JSON della chiamata per le schede; come parametro di query viene ignorato e ottieni le schede del primo account collegato.

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

Ogni record di scheda contiene id, locationName, address e liveLink. Il suo id è il connectedAccountListingId accettato da connect-listing; il campo non si chiama listingId. Un collegamento non riuscito restituisce success: false con un message come Listing record not found.

6. Disconnetti l'account quando un cliente se ne va

La disconnessione è totale: tutte le Pagine collegate tramite l'account smettono di sincronizzarsi e le interazioni di Facebook smettono di arrivare. Per scollegare una sola sede mantenendo l'account, usa invece 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 risposta è data.fbBulkDisconnect con success. È true anche per un connectedAccountId sconosciuto, quindi significa "elaborato", non "è stata rimossa una connessione attiva". Elenca di nuovo gli account collegati se hai bisogno di una conferma.

7. Cosa succede dopo

Viene generato un evento connection.location_connected con data.platform: "facebook" per ogni sede collegata, e viene generato connection.location_disconnected quando rimuovi il collegamento. Se Facebook invalida l'autorizzazione, ricevi connection.reauth_required: crea un nuovo link (passaggio 1) e chiedi al proprietario di dare nuovamente il consenso concedendo tutti i permessi. Una volta stabilito il collegamento, la riga di Facebook nelle schede premium della sede passa a SYNCED, postSites: ["FACEBOOK"] diventa una destinazione valida e l'endpoint di analisi di Facebook inizia a restituire dati.

Passaggi successivi