Account collegati

Ogni endpoint con cURL ed esempi Python e Node: collega Google e Facebook, elenca account, abbina e collega schede, cartelle, creazione GMB, scollegamenti.

Un account connesso è un'autorizzazione OAuth concessa dal proprietario di un profilo Google Business Profile o di pagine Facebook, che consente all'API di leggere e gestire le schede a cui tale account può accedere. La risorsa svolge tre funzioni: creare i link OAuth, abbinare o collegare le schede dell'account alle tue sedi e rimuovere la connessione. Le due operazioni di lettura GET per l'elenco e i dettagli funzionano con una chiave Read (lettura); ogni POST, incluso il recupero delle schede in sola lettura, richiede una chiave Write (scrittura), e l'uso di una chiave Read per un'operazione di scrittura restituisce HTTP 400 con SY90016.

Tutti gli esempi seguenti presuppongono che il client venga creato una sola volta, come mostrato nel primo esempio, e leggono LISTINGSAPI_KEY dall'ambiente. Gli identificatori sono l'UUID connectedAccountId restituito dall'endpoint di elenco e l'identificatore della sede in base64 (TG9jYXRpb246MTgwMDI4OQ==); non applicare mai la codifica URL a nessuno dei due.

Panoramica degli endpoint

MetodoPercorsoFunzioneRiferimento
POST/connected-accounts/connect-googleCrea un link per la connessione in blocco di un account Google, valido per 24 ore.Connetti un account Google
POST/connected-accounts/connect-facebookCrea un link per la connessione in blocco di un account Facebook, valido per 24 ore.Connetti un account Facebook
POST/locations/oauth_connect_urlCrea un link di connessione monouso associato a una sola sede.URL di connessione OAuth per una sede
GET/connected-accountsElenca gli account connessi con il relativo stato di funzionamento e il numero di collegamenti.Elenca gli account connessi
GET/connected-accounts/{connectedAccountId}/detailsLegge un account, incluso lo stato del processo di abbinamento.Ottieni i dettagli di un account connesso
POST/connected-accounts/connected-account-listingsElenca le schede sulle piattaforme di pubblicazione a cui un account può accedere.Recupera le schede di un account connesso
POST/connected-accounts/trigger-matchesMette in coda il processo di recupero e abbinamento per uno o più account.Avvia l'abbinamento delle sedi
GET/connected-accounts/{connectedAccountId}/connection-suggestionsLegge gli abbinamenti suggeriti tra sedi e schede.Elenca i collegamenti suggeriti
POST/connected-accounts/confirm-matchesAccetta i suggerimenti e crea i collegamenti attivi.Conferma gli abbinamenti per la connessione
POST/connected-accounts/connect-listingCollega una scheda selezionata a una sede.Collega una scheda a una sede
POST/connected-accounts/disconnect-listingScollega una sede da una piattaforma di pubblicazione.Scollega una scheda da una sede
POST/connected-accounts/create-location-from-listingCrea una nuova sede a partire da una scheda su una piattaforma di pubblicazione.Crea una sede da una scheda
GET/connected-accounts/{connectedAccountId}/foldersElenca i gruppi dell'account Google (cartelle).Elenca le cartelle GMB
POST/locations/create/gmb-listingCrea un nuovo profilo Google Business Profile per una sede.Crea una scheda GMB
POST/connected-accounts/disconnect-googleDisconnette un intero account Google.Disconnetti un account Google
POST/connected-accounts/disconnect-facebookDisconnette un intero account Facebook.Disconnetti un account Facebook
POST/locations/oauth-disconnectDisconnette una sede da una piattaforma di pubblicazione (stessa operazione di disconnect-listing).Disconnetti una sede da una piattaforma di pubblicazione

POST /connected-accounts/connect-google

Restituisce un URL OAuth di breve durata. Reindirizza il proprietario dell'account a questo URL; Google lo riporta al tuo successUrl o errorUrl. Il link è limitato all'account a cui appartiene la chiave API, quindi il corpo contiene solo i tuoi due URL di reindirizzamento. La generazione di un nuovo link per un account la cui autorizzazione è scaduta aggiorna la connessione esistente anziché duplicarla.

NomePosizioneObbligatorioNote
inputbodysìOggetto contenitore; racchiude l'intero corpo.
input.successUrlbodysìURL https assoluto sotto il tuo controllo. Viene raggiunto dopo il consenso.
input.errorUrlbodysìURL https assoluto sotto il tuo controllo. Viene raggiunto in caso di annullamento o errore.
Connect Google
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/google/success",    "errorUrl": "https://app.example.com/connect/google/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForGoogle": {      "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 risposta alla tua richiesta.

Il link è valido per 24 ore. errors viene valorizzato solo quando la generazione non riesce, quindi verifica che url non sia null. Un corpo senza annidamento, o che contiene un accountId, viene rifiutato con HTTP 400.

POST /connected-accounts/connect-facebook

L'equivalente per Facebook, con lo stesso corpo. Durante la procedura, il proprietario accetta i termini di Facebook e concede le autorizzazioni per la gestione delle pagine necessarie all'API; se non concede una delle autorizzazioni, la connessione non può eseguire la sincronizzazione, quindi genera nuovamente il link e chiedigli di dare di nuovo il consenso.

NomePosizioneObbligatorioNote
inputbodysìOggetto contenitore.
input.successUrlbodysìURL https assoluto sotto il tuo controllo.
input.errorUrlbodysìURL https assoluto sotto il tuo controllo.
Connect Facebook
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 risposta alla tua richiesta.

La chiave della risposta è bulkConnectLinkForFacebook; per il resto, leggila esattamente come per il link Google. Una volta che il proprietario ha terminato, l'account compare nell'endpoint di elenco come FacebookAccount.

POST /locations/oauth_connect_url

Usa questa opzione quando sai già quale sede sta collegando il proprietario. Il link è associato alla sede che specifichi, quindi non segue alcun passaggio di abbinamento: quando il proprietario dà il consenso, le credenziali vengono associate direttamente a quella sede. Entrambi i link per il collegamento in blocco descritti sopra collegano invece un intero account.

NomePosizioneObbligatorioNote
inputbodysìOggetto contenitore.
input.locationIdbodysìID della sede in Base64 o ID numerico non codificato.
input.sitebodysìGOOGLE, FACEBOOK o APPLE.
input.successUrlbodysìURL assoluto di destinazione dopo la concessione dell'autorizzazione.
input.errorUrlbodysìURL assoluto di destinazione in caso di annullamento o errore.
Single-location link
curl -X POST https://listingsapi.com/api/v4/locations/oauth_connect_url \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'
JSON
{  "data": {    "createConnectUrl": {      "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 risposta alla tua richiesta.

Il link è monouso, quindi creane uno nuovo per ogni tentativo anziché memorizzarlo nella cache. Un URL di reindirizzamento relativo o non interpretabile viene restituito come success: true con null url, quindi controlla url e non solo success. Una chiave non autorizzata a operare su questa sede riceve un 403 con SY90003. Gli SDK convertono automaticamente site in maiuscolo.

Elenca gli account collegati

GET /connected-accounts

Restituisce tutti gli account autorizzati sul tuo account API, con lo stato della connessione e il numero di sedi collegate a ciascuno. Questa è una pagina con paginazione basata su offset: records[] più pageInfo.totalRecords, con paginazione tramite i parametri di query non annidati page e perPage. L'ordinamento è fisso, per email dell'account in ordine crescente.

NomePosizioneObbligatorioNote
pagequerynoNumero di pagina a partire da 1. Valore predefinito: 1.
perPagequerynoRecord per pagina. Valore predefinito: 20.
publisherquerynoGoogleAccount, FacebookAccount, AppleAccount, YelpAccount, TripadvisorAccount, LinkedinAccount, PinterestAccount o TwitterAccount.
statusquerynoConnected, NotConnected o ConnectionIssue. Combinazione di maiuscole e minuscole.
List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&status=Connected&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "totalPages": 1, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "connectedAccountType": "GoogleAccount",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "connectivityIssue": null,          "connectedLocationsCount": 0,          "requestMatchesStatus": "MATCH_COMPLETED",          "lastFetchMatchesRequestedAt": "2026-07-06 21:43:07 UTC"        }      ]    }  }}

Scegli il record il cui email corrisponde al proprietario che ha dato il consenso e conserva il relativo connectedAccountId; ogni chiamata successiva lo richiede. Qualsiasi elemento diverso dai quattro parametri di query viene ignorato anziché rifiutato, quindi un pageInfo JSON restituisce la pagina 1 senza segnalazioni.

status del recordSignificato
CONNECTEDLe credenziali sono valide. Puoi avviare l'abbinamento o pubblicare.
MATCH_IN_PROGRESSUn'esecuzione dell'abbinamento è in coda o in corso.
CONNECTIVITY_ISSUEL'autorizzazione è scaduta. connectivityIssue ne indica il motivo; genera nuovamente il link di collegamento.

Il filtro status e il campo status del record non usano lo stesso insieme di valori. Se passi CONNECTED come filtro, il valore enum non è valido e viene restituito un 400.

Ottieni i dettagli di un account

GET /connected-accounts/{connectedAccountId}/details

Restituisce gli stessi campi di un record dell'elenco, limitati a un solo account. Usalo per controllare periodicamente requestMatchesStatus dopo aver avviato gli abbinamenti o per verificare status e connectivityIssue prima di inviare un aggiornamento tramite l'account.

NomePosizioneObbligatorioNote
connectedAccountIdpathsìUUID restituito dall'endpoint dell'elenco.
Account details
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountDetails": {      "details": {        "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",        "connectedAccountType": "GoogleAccount",        "status": "CONNECTED",        "connectivityIssue": null,        "connectedLocationsCount": 0,        "requestMatchesStatus": "MATCH_COMPLETED"      }    }  }}

Il record si trova un livello più in basso, in data.connectedAccountDetails.details. requestMatchesStatus passa da MATCH_IN_PROGRESS a MATCH_COMPLETED quando i suggerimenti sono pronti. Completed significa che il processo di abbinamento è terminato, non che sia stato effettuato un collegamento: connectedLocationsCount rimane 0 finché non confermi o colleghi una scheda.

Recupera le schede a cui un account può accedere

POST /connected-accounts/connected-account-listings

Elenca tutte le schede Google Business Profile o Facebook a cui l'account ha accesso, indipendentemente dal fatto che siano collegate a una delle tue sedi. Il valore id di ogni record è il valore connectedAccountListingId accettato da connect-listing e create-location-from-listing. Questa è una richiesta POST di sola lettura e restituisce una pagina con paginazione basata su offset: records[] più pageInfo, con paginazione tramite le chiavi non annidate page e perPage nel corpo.

NomePosizioneObbligatorioNote
connectedAccountIdbodysìUUID dell'account di cui recuperare le schede. Non racchiuso in input.
pagebodynoNumero di pagina. Valore predefinito: 1.
perPagebodynoRecord per pagina. Valore predefinito: 500, che è anche il massimo.
locationInfobodynoRicerca a testo libero per nome, indirizzo, località, codice postale, codice negozio e telefono.
Account listings
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": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50, "locationInfo": "William St" }'
JSON
{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalPages": 1, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "accountTypeName": "Google",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "phone": "(718) 667-7787",          "liveLink": null        }      ]    }  }}

Scorri le pagine dell'insieme con pageInfo.hasNextPage e pageInfo.totalPages. Gli SDK inseriscono automaticamente connectedAccountId nel corpo, quindi questo riguarda solo le chiamate REST scritte manualmente.

Avvia l'abbinamento

POST /connected-accounts/trigger-matches

Mette in coda il processo che recupera tutti i profili accessibili agli account indicati e abbina ciascuno a una delle tue sedi. L'abbinamento considera tutte le sedi attive, non archiviate e non ancora collegate. Registra solo suggerimenti; non viene creato alcun collegamento finché non confermi.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.connectedAccountIdsbodysìArray di UUID degli account restituiti dall'endpoint di elenco.
Trigger matches
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": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'
JSON
{  "data": {    "connectedAccountsTriggerMatches": {      "success": true,      "failedIds": null    }  }}

success: true significa che il processo è stato messo in coda, non che l'abbinamento è terminato. Ogni account che non è stato possibile mettere in coda è elencato in failedIds e success è false. Interroga periodicamente l'endpoint dei dettagli finché requestMatchesStatus non è MATCH_COMPLETED prima di leggere i suggerimenti; un intervallo di 15 secondi con un ciclo limitato mantiene il piano Launch entro il limite di 10 richieste al minuto.

Leggi i suggerimenti di collegamento

GET /connected-accounts/{connectedAccountId}/connection-suggestions

Restituisce gli abbinamenti proposti dal sistema: la tua sede da un lato (locationInfo, con locationId come valore di databaseId) e la scheda sulla piattaforma di pubblicazione dall'altro (suggestedLocationInfo). La paginazione è basata su offset e usa i parametri di query non annidati page e perPage; l'ordinamento è fisso e crescente in base alle informazioni della sede.

NomeInObbligatorioNote
connectedAccountIdpathsìUUID dell'account.
pagequerynoNumero di pagina a partire da 1. Valore predefinito: 1.
perPagequerynoRecord per pagina. Valore predefinito: 20.
Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalPages": 1, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

Un suggerimento non ha id. Conserva insieme matchedDataDatabaseId e accountType; confirm-matches ha bisogno di entrambi per costruire il proprio id. Se esegui la lettura troppo presto, prima di MATCH_COMPLETED, l'endpoint restituisce records: [] con totalRecords: 0, un risultato identico a quello che indica "nessun abbinamento trovato".

accountTypePiattaforma di pubblicazioneTipo di record di abbinamento
GMBGoogle Business ProfileGmbLocationMatchedData
FBPagine FacebookFbLocationMatchedData
APPLEApple Business ConnectAppleLocationMatchedData

Conferma gli abbinamenti

POST /connected-accounts/confirm-matches

Accetta i suggerimenti che approvi e crea i collegamenti effettivi. Ogni id è la codifica base64 di <MatchRecordType>:<matchedDataDatabaseId>, con il tipo scelto dalla tabella precedente. L'account viene dedotto dai record, quindi non esiste un campo connectedAccountId; un campo sconosciuto all'interno di input viene rifiutato con un codice 400.

NomeInObbligatorioNote
inputbodysìOggetto contenitore. È dichiarato solo matchRecordIds.
input.matchRecordIdsbodysìArray di id dei record di abbinamento codificati in base64. Almeno uno.
Confirm matches
# base64 of GmbLocationMatchedData: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": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'
JSON
{  "data": {    "confirmConnectMatches": {      "success": true,      "failedIds": null    }  }}

failedIds contiene i valori decodificati di matchedDataDatabaseId che non è stato possibile confermare, ad esempio per un record già utilizzato o una sede archiviata dopo l'abbinamento, quindi confrontali con i record dei suggerimenti per risalire a quelli corrispondenti. I suggerimenti non inviati rimangono invariati. La conferma collega la sede alla scheda; da sola non invia dati alla piattaforma di pubblicazione.

Collega una scheda a una sede

POST /connected-accounts/connect-listing

Collega una singola scheda che hai già scelto a una singola sede, senza passaggi di suggerimento o conferma. Usalo quando l'abbinamento è ambiguo, ad esempio in presenza di due negozi vicini con nomi simili, e un operatore sceglie la scheda corretta tra quelle dell'account.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.locationIdbodysìid della sede codificato in base64.
input.connectedAccountIdbodysìUUID dell'account proprietario della scheda.
input.connectedAccountListingIdbodysìIl valore id di un record restituito dall'endpoint delle schede dell'account. Non listingId.
Connect listing
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": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "connectListing": {      "success": true,      "message": null    }  }}

Un collegamento non riuscito restituisce success: false con message non nullo, ad esempio Listing record not found quando l'id della scheda non corrisponde ad alcuna scheda, oppure una nota che indica che la scheda è già collegata a un'altra sede. In entrambi gli SDK questo metodo si trova nella risorsa listings, non in quella degli account collegati.

Scollega una scheda da una sede

POST /connected-accounts/disconnect-listing

Rimuove il collegamento tra una sede e una piattaforma di pubblicazione. La sede e i suoi dati rimangono; si interrompe solo la sincronizzazione in uscita verso quella piattaforma di pubblicazione. Questo endpoint non supporta operazioni in blocco, quindi esegui un ciclo sulle sedi. Per collegare un negozio a un altro account Google, scollegalo prima con questo endpoint, poi esegui l'abbinamento o il collegamento sul nuovo account.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.locationIdbodysìid della singola sede codificato in base64.
input.sitebodyuno dei dueGOOGLE, FACEBOOK o APPLE. Obbligatorio se non viene inviato providerId.
input.providerIdbodyuno dei dueL'identificatore dell'account assegnato dalla piattaforma di pubblicazione, al posto di site.
Disconnect listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE" } }'
JSON
{  "data": {    "disconnectConnectedAccountsLocations": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

Se non invii né site né providerId, l'endpoint restituisce SY10056. Per una sede senza un collegamento attivo per quel sito, l'endpoint restituisce SY10057 anziché segnalare un esito positivo senza aver eseguito alcuna operazione, quindi success: true indica effettivamente che un collegamento è stato rimosso. Gli SDK accettano solo site e lo convertono in maiuscolo.

Creare una sede a partire da una scheda

POST /connected-accounts/create-location-from-listing

La corrispondenza associa le schede solo alle sedi che hai già. Per una scheda senza sede, questa operazione ne crea una a partire dai dati della piattaforma di pubblicazione e la collega subito alla scheda. Da Google vengono importati nome, indirizzo, coordinate, telefono, sito web, descrizione, orari regolari e speciali, categorie, data di apertura, codice negozio e fuso orario, oltre ai metodi di pagamento e ai link ai social ricavati dagli attributi Google della scheda. Da Facebook vengono importati nome, sede, orari, categorie, descrizione e informazioni di contatto.

Quando importi da Google, i dati non vengono inviati di nuovo a Google, quindi la relativa scheda rimane nello stato IN_PROGRESS finché il tuo primo aggiornamento della sede non viene pubblicato sulla scheda. I dati vengono inviati normalmente a tutte le altre piattaforme di pubblicazione e questo endpoint non accetta un ambito di siti, quindi la sede viene creata per l'intero insieme di piattaforme di pubblicazione del tuo account. Restringi questo insieme con enabledSiteIds subito dopo la creazione e invia immediatamente l'aggiornamento: le voci d'ordine per le altre piattaforme di pubblicazione vengono generate poco dopo la creazione e quelle già generate non vengono ritirate dall'aggiornamento.

Nessuno dei due SDK include ancora un metodo per questo endpoint, quindi gli esempi Python e Node chiamano REST con lo stesso header.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.connectedAccountIdbodysìUUID dell'account a cui appartiene la scheda.
input.connectedAccountListingIdbodysìIl valore id di un record restituito dall'endpoint delle schede dell'account. Non listingId.
Create from listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "createLocationFromConnectedAccountListing": {      "success": true,      "locationId": 88277,      "errors": null    }  }}

locationId è il semplice valore databaseId della nuova sede. In caso di errore, success è false, locationId è null e errors contiene un codice che indica il motivo, ad esempio SY81067 (l'id della scheda non corrisponde ad alcuna scheda); altre cause sono una scheda già collegata a un'altra sede o un account con credenziali scadute. Una volta creata, gestisci la sede come qualsiasi altra.

Elencare le cartelle di un account Google

GET /connected-accounts/{connectedAccountId}/folders

Restituisce i gruppi di account (cartelle) di Google Business Profile a cui l'account Google collegato può accedere. Usalo prima di creare una scheda GMB, in modo che il nuovo profilo venga inserito nel gruppo previsto dal proprietario. La risposta è un semplice array in getFoldersUnderGoogleAccount, non una pagina. Il percorso è valido solo per le connessioni GoogleAccount.

NomeInObbligatorioNote
connectedAccountIdpathsìUUID di un account di tipo Google.
Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

Usa folderId senza modificarlo; è la stringa accounts/{id}, non un numero. locationCount può essere null quando Google non lo fornisce, quindi consideralo facoltativo.

Creare un Google Business Profile per una sede

POST /locations/create/gmb-listing

Crea una nuova scheda Google per una sede che non ne ha, in un account Google collegato e, facoltativamente, all'interno di una cartella. A differenza di connect-listing, che collega una scheda già esistente. La sede deve già avere un nome, un indirizzo e un numero di telefono e può esistere una sola scheda Google per sede.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.locationIdbodysìId della sede in Base64.
input.connectedAccountIdbodysìUUID dell'account Google in cui creare la scheda.
input.folderIdbodynoStringa accounts/{id} restituita dall'endpoint delle cartelle. Omettila per usare la radice dell'account.
Create GMB listing
curl -X POST https://listingsapi.com/api/v4/locations/create/gmb-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

La creazione è asincrona: success: true significa che la richiesta è stata accettata e Google esamina i nuovi profili prima che vengano pubblicati. Quando success è false, errors indica il motivo: campi obbligatori mancanti, una scheda Google già esistente, una sede archiviata o un account inattivo.

Scollega un intero account Google

POST /connected-accounts/disconnect-google

Rimuove la connessione per l'intero account: tutte le sedi collegate tramite quell'account smettono di sincronizzarsi. Non è presente alcun campo locationIds; per scollegare una sola sede e mantenere l'account, usa invece disconnect-listing. Usa questa operazione quando un cliente interrompe il servizio oppure quando non riesci a rimuovere un'autorizzazione non funzionante e vuoi ricominciare con un nuovo link di connessione.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.connectedAccountIdbodysìUUID dell'account Google. Viene scollegato l'intero account.
Disconnect Google
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'
JSON
{  "data": {    "gmbBulkDisconnect": {      "success": true    }  }}

success: true viene restituito anche per un connectedAccountId sconosciuto, quindi significa "la richiesta è stata elaborata", non "è stata rimossa una connessione attiva". Recupera di nuovo l'elenco degli account collegati se vuoi averne la certezza.

Scollega un intero account Facebook

POST /connected-accounts/disconnect-facebook

L'operazione equivalente per Facebook, con lo stesso corpo della richiesta. Le Pagine collegate tramite l'account smettono di sincronizzarsi e le interazioni di Facebook non vengono più visualizzate.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.connectedAccountIdbodysìUUID dell'account Facebook. Viene scollegato l'intero account.
Disconnect Facebook
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" } }'
JSON
{  "data": {    "fbBulkDisconnect": {      "success": true    }  }}

La chiave della risposta è fbBulkDisconnect. Come per Google, success: true per un id sconosciuto indica che la richiesta è stata elaborata, non che la connessione è stata rimossa.

Scollega una sede da una piattaforma di pubblicazione

POST /locations/oauth-disconnect

La fase di disconnessione del flusso OAuth per singola sede. È la stessa operazione di disconnect-listing, disponibile tramite un secondo percorso: corpo input identico e stessa chiave di risposta disconnectConnectedAccountsLocations. Scegli il percorso che risulta più chiaro nella tua integrazione.

NomeInObbligatorioNote
inputbodysìOggetto contenitore.
input.locationIdbodysìid in Base64 della singola sede.
input.sitebodyuno dei dueGOOGLE, FACEBOOK o APPLE. Obbligatorio se non viene inviato providerId.
input.providerIdbodyuno dei dueL'identificatore dell'account assegnato dalla piattaforma di pubblicazione, al posto di site.
OAuth disconnect
curl -X POST https://listingsapi.com/api/v4/locations/oauth-disconnect \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE" } }'
JSON
{  "data": {    "disconnectConnectedAccountsLocations": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

Si applicano le stesse regole per SY10056 e SY10057 e una chiave non autorizzata a operare su questa sede riceve un 403 con SY90003. La disconnessione lascia intatti la sede e i suoi dati; si interrompe solo la sincronizzazione in uscita verso quella piattaforma di pubblicazione. Per collegare successivamente la scheda corretta, fai accedere di nuovo il proprietario tramite l'URL di connessione oppure esegui la ricerca delle corrispondenze e connect-listing.

Errori che puoi riscontrare

Le richieste non valide e le chiavi errate restituiscono un 4xx con un errors[] al livello principale il cui message inizia con il codice. Anche le operazioni di scrittura possono restituire 200 con success: false e il motivo all'interno di data.<operation>, quindi controlla il corpo della risposta di ogni operazione di scrittura. L'elenco completo è disponibile in Codici di errore.

Codice o statoSignificatoSoluzione
SY90016 (400)È stata usata una chiave Read su un POST.Usa una chiave Write.
SY90003 (403)La chiave non è autorizzata a collegare o scollegare questa sede.Usa una chiave con accesso alla sede.
SY10056 (200)La richiesta di disconnessione non conteneva né site né providerId.Invia uno dei due.
SY10057 (200)La sede non ha una connessione attiva per quel sito.Non c'è nulla da rimuovere; controlla le schede della sede.
SY81067 (200)Non è stato possibile risolvere connectedAccountListingId in create-from-listing.Recupera di nuovo le schede dell'account e usa il valore id di un record.
400, Variable "$input" ... was not providedIl corpo della richiesta non era racchiuso in input oppure mancava un campo obbligatorio.Inserisci il corpo della richiesta all'interno di input; usa connectedAccountListingId, non listingId.
400, invalid enumLo stato CONNECTED di un record è stato riutilizzato come filtro status dell'elenco.Filtra con Connected, NotConnected o ConnectionIssue.
429Limite di frequenza superato.Attendi Retry-After; consulta Limiti di frequenza.

Passaggi successivi