Listings APIListings API
Iniciar sesión

Encuentra y corrige errores en las fichas

Filtra fichas con problemas por ubicación, lee el motivo de la plataforma de publicación, corrige, reconsulta con seguridad y revisa toda la cuenta.

La mayoría de las fichas se sincronizan sin ayuda. Las que no lo hacen indican el motivo en displayStatus y syncIssue, y casi todas las causas se corresponden con una de cinco soluciones. Esta guía parte de las filas de fichas sin procesar y llega hasta un informe por cuenta sobre lo que está bloqueado y cómo resolverlo.

1. Obtén las fichas y conserva las filas con problemas

Obtén las fichas prémium y descarta todas las que estén en buen estado. Una fila necesita atención cuando actionRequired es true, o cuando syncStatus es FAILED, CANNOT_SUBMIT o REQUIRING_ACTION. IN_PROGRESS y PENDING_APPROVAL no son errores; indican que la ficha está en la cola de la plataforma de publicación.

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. Lee el motivo

Dos campos explican el problema de una fila. displayStatus es el resumen que ofrece la plataforma sobre el estado actual de la fila. syncIssue es el motivo indicado por la propia plataforma de publicación, cuando ha proporcionado uno. Lee ambos: en el ejemplo anterior, el campo displayStatus de Local Mint indica que el socio está teniendo problemas, pero syncIssue revela la causa real: falta el sitio web.

CampoEjemploÚsalo para
displayStatusConnect your account to sync the listingEl texto que muestras a una persona.
syncIssuePublisher requires website URLElegir la solución. null cuando la plataforma de publicación no ha indicado ningún motivo.
actionRequiredtrueOrdenar: true significa que nada avanza hasta que actúes.

La propia ubicación también incluye un array createErrors en cada lectura desde Listar todas las ubicaciones. Contiene los problemas de validación detectados al crear el registro y es otro lugar donde buscar cuando una fila falla sin ningún syncIssue.

3. Relaciona la causa con la solución

Un pequeño conjunto de causas explica casi todas las filas bloqueadas.

CausaCómo se manifiestaSolución
Cuenta no conectadaGoogle Maps o Facebook en REQUIRING_ACTION con Connect your account to sync the listing.Conecta la cuenta de esa plataforma de publicación: Conectar Google e importar ubicaciones o Conectar páginas de Facebook. Apple Maps no necesita una conexión; consulta Conectar Apple Business Connect.
Falta el sitio webFAILED con syncIssue: Publisher requires website URL.Establece bizUrl en la ubicación. Consulta Actualizar una ubicación.
País no admitido por la plataforma de publicaciónCANNOT_SUBMIT, sin syncIssue.Compara el campo countryIso de la ubicación con el campo supportedCountries de ese sitio, obtenido de Listar los sitios del plan. No hay nada que corregir; la plataforma de publicación no aceptará la ficha.
Dirección oculta no admitidaCANNOT_SUBMIT o FAILED en un negocio con área de servicio que tiene hideAddress: true.Comprueba el campo hideAddressSupportedCountries del sitio. Muestra la dirección o acepta que se omita esta plataforma de publicación.
La página de Facebook no tiene horarioFacebook en IN_PROGRESS con syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information.Añade el horario de apertura a la página en Facebook y luego envía una actualización de la ubicación. Consulta Actualizar una ubicación.
Descripción o categoría rechazadaFAILED con un syncIssue que indica el campo.Actualiza la descripción o subCategoryId en la ubicación y luego vuelve a consultar.

Para comprobar las reglas sobre países y direcciones ocultas, obtén los sitios del plan una vez y guárdalos en caché; la lista no está paginada y rara vez cambia.

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

Si el campo countryIso de la ubicación no está en supportedCountries, la fila de esa plataforma de publicación nunca saldrá de CANNOT_SUBMIT. Exclúyela de tu cifra de cobertura en lugar de volver a intentarlo.

4. Vuelve a consultar después de aplicar la solución

Una actualización de la ubicación activa un nuevo envío a las plataformas de publicación afectadas. La fila pasa de FAILED o REQUIRING_ACTION de nuevo a IN_PROGRESS y luego a SYNCED cuando la plataforma de publicación la acepta. Las plataformas de publicación tardan desde minutos hasta semanas, así que programa las consultas a intervalos de horas, no de segundos.

Cada consulta cuenta para el límite de solicitudes. Si recibes un 429, lee Retry-After y espera esa cantidad de segundos; los SDK lanzan RateLimitError con el mismo valor.

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"

El avance de lastUpdate indica que la plataforma de publicación ha procesado el nuevo envío, incluso antes de que cambie syncStatus. Si tienes webhooks, el evento listing.submission sustituye este bucle.

5. Realiza una revisión de toda la cuenta

Para encontrar todas las filas bloqueadas de la cuenta, recorre mediante paginación GET /locations (una conexión basada en cursores: first, after, edges[].node) y llama al endpoint premium una vez por ubicación. Recopila las filas problemáticas en un único informe organizado por ubicación. El Python SDK recorre los cursores con auto_paging_iter(); el Node SDK lo hace con fetchAll: true. Los ejemplos reutilizan la función auxiliar de espera incremental del paso 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

El informe agrupa las filas que siguen en curso con las que están realmente bloqueadas. Sepáralas según la tabla del paso 3 antes de entregar el informe a nadie: IN_PROGRESS y PENDING_APPROVAL requieren paciencia, REQUIRING_ACTION requiere una conexión y FAILED requiere un campo en la ubicación.

Siguientes pasos