Listings APIListings API
Accedi

Trova e correggi gli errori delle schede

Filtra le schede problematiche per sede, leggi il motivo della piattaforma di pubblicazione, correggi, ripeti il polling in sicurezza e verifica l’account.

La maggior parte delle schede si sincronizza senza interventi. Quelle che non si sincronizzano ne indicano il motivo in displayStatus e syncIssue, e quasi ogni causa corrisponde a una di cinque correzioni. Questa guida parte dalle righe delle schede così come vengono restituite e arriva a un report per account su ciò che è bloccato e su come intervenire.

1. Recupera le schede e conserva le righe problematiche

Recupera le schede premium ed escludi tutte quelle senza problemi. Una riga richiede attenzione quando actionRequired è true oppure quando syncStatus è FAILED, CANNOT_SUBMIT o REQUIRING_ACTION. IN_PROGRESS e PENDING_APPROVAL non sono errori; indicano che la scheda è nella coda della piattaforma di pubblicazione.

Problem rows
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.actionRequired                or (.syncStatus | IN("FAILED", "CANNOT_SUBMIT", "REQUIRING_ACTION")))]'
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "syncIssue": null      },      {        "site": { "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "syncIssue": "Publisher requires website URL"      }    ]  }}

2. Leggi il motivo

Due campi spiegano il problema di una riga. displayStatus è il riepilogo fornito dalla piattaforma sullo stato della riga. syncIssue è il motivo indicato dalla piattaforma di pubblicazione stessa, quando ne ha fornito uno. Leggili entrambi: nell'esempio sopra, displayStatus di Local Mint indica che il partner sta riscontrando problemi, ma syncIssue fornisce la causa reale, ovvero un sito web mancante.

CampoEsempioA cosa serve
displayStatusConnect your account to sync the listingLa riga di testo da mostrare a una persona.
syncIssuePublisher requires website URLScegliere la correzione. null quando la piattaforma di pubblicazione non ha fornito alcun motivo.
actionRequiredtrueOrdinamento: true significa che nulla procede finché non intervieni.

Anche la sede stessa include un array createErrors a ogni lettura da Elenca tutte le sedi. Contiene i problemi di validazione rilevati alla creazione del record ed è un altro punto da controllare quando una riga presenta un errore senza syncIssue.

3. Associa la causa alla correzione

Un numero ristretto di cause spiega quasi tutte le righe bloccate.

CausaCome si manifestaCorrezione
Account non collegatoGoogle Maps o Facebook nello stato REQUIRING_ACTION con Connect your account to sync the listing.Collega l'account della piattaforma di pubblicazione: Collega Google e importa le sedi oppure Collega le Pagine Facebook. Apple Maps non richiede un collegamento; consulta Collega Apple Business Connect.
Sito web mancanteFAILED con syncIssue: Publisher requires website URL.Imposta bizUrl sulla sede. Consulta Aggiorna una sede.
Paese non supportato dalla piattaforma di pubblicazioneCANNOT_SUBMIT, senza syncIssue.Confronta countryIso della sede con supportedCountries di quel sito, disponibile in Elenca i siti del piano. Non c'è nulla da correggere; la piattaforma di pubblicazione non accetterà la scheda.
Indirizzo nascosto non supportatoCANNOT_SUBMIT o FAILED per un'attività con area di servizio e con hideAddress: true.Controlla hideAddressSupportedCountries del sito. Mostra l'indirizzo oppure accetta che questa piattaforma di pubblicazione venga saltata.
La Pagina Facebook non ha orariFacebook nello stato IN_PROGRESS con syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information.Aggiungi gli orari di apertura alla Pagina su Facebook, poi invia un aggiornamento della sede. Consulta Aggiorna una sede.
Descrizione o categoria rifiutataFAILED con un valore di syncIssue che indica il campo.Aggiorna la descrizione o subCategoryId sulla sede, poi ripeti il polling.

Per verificare le regole relative al paese e all'indirizzo nascosto, recupera i siti del piano una sola volta e memorizzali nella cache; l'elenco non è paginato e cambia raramente.

Plan sites
curl -s https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.name == "Yelp")      | {name, supportedCountries, hideAddressSupportedCountries}'
JSON
{  "name": "Yelp",  "supportedCountries": ["US", "CA", "GB", "DE", "FR"],  "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]}

Se countryIso della sede non è presente in supportedCountries, la riga di quella piattaforma di pubblicazione non uscirà mai dallo stato CANNOT_SUBMIT. Escludila dal calcolo della copertura anziché riprovare.

4. Ripeti il polling dopo la correzione

Un aggiornamento della sede attiva un nuovo invio alle piattaforme di pubblicazione interessate. La riga passa da FAILED o REQUIRING_ACTION di nuovo a IN_PROGRESS, poi a SYNCED quando la piattaforma di pubblicazione accetta l'invio. Le piattaforme di pubblicazione impiegano da pochi minuti a settimane, quindi esegui il polling a intervalli di ore, non di secondi.

Ogni richiesta di polling viene conteggiata ai fini del limite di richieste. Quando ricevi 429, leggi Retry-After e attendi il numero di secondi indicato; gli SDK sollevano RateLimitError con lo stesso valore.

Re-poll
# -D - prints response headers so you can see Retry-After on a 429curl -s -D - https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| grep -i -E "^HTTP|^Retry-After"

L'avanzamento di lastUpdate indica che la piattaforma di pubblicazione ha elaborato il nuovo invio, anche prima che syncStatus cambi. Se hai dei webhook, l'evento listing.submission sostituisce questo ciclo.

5. Esegui un controllo dell'intero account

Per trovare tutte le righe bloccate nell'intero account, scorri le pagine di GET /locations (una connessione con cursore: first, after, edges[].node) e chiama l'endpoint premium una volta per sede. Raccogli le righe problematiche in un unico report indicizzato per sede. Il Python SDK segue i cursori con auto_paging_iter(); il Node SDK lo fa con fetchAll: true. Gli esempi riutilizzano la funzione ausiliaria di backoff del passaggio 4.

Account sweep
# One page of locations, then one listings call per location.# Repeat with &after=<pageInfo.endCursor> while hasNextPage is true.curl -s "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq -r '.data.allLocations.edges[].node.id' \| while read -r id; do    curl -s "https://listingsapi.com/api/v4/locations/$id/listings/premium" \      -H "Authorization: API $LISTINGSAPI_KEY" \      | jq --arg id "$id" '[.data.listingsForLocation[]           | select(.syncStatus != "SYNCED" and .syncStatus != "COMPLETED")           | {location: $id, site: .site.name, status: .syncStatus, issue: .syncIssue}]'    sleep 6   # stay under 10 requests a minute on Launch  done

Il report raggruppa le righe ancora in elaborazione insieme a quelle effettivamente bloccate. Suddividilo secondo la tabella del passaggio 3 prima di condividerlo con chiunque: IN_PROGRESS e PENDING_APPROVAL richiedono pazienza, REQUIRING_ACTION richiede una connessione e FAILED richiede un campo nella sede.

Passaggi successivi