Encontre e corrija erros de listagem

Filtre listagens do local que exigem atenção, veja o motivo da plataforma de publicação, corrija, consulte de novo com segurança e verifique toda a conta.

A maioria das listagens é sincronizada sem intervenção. As que não são informam o motivo em displayStatus e syncIssue, e quase todas as causas correspondem a uma de cinco correções. Este guia parte das linhas de listagem brutas até chegar a um relatório por conta sobre o que está bloqueado e o que fazer a respeito.

1. Busque as listagens e mantenha as linhas com problemas

Busque as listagens premium e descarte todas as que estão sem problemas. Uma linha precisa de atenção quando actionRequired é true ou quando syncStatus é FAILED, CANNOT_SUBMIT ou REQUIRING_ACTION. IN_PROGRESS e PENDING_APPROVAL não são erros; indicam a fila da plataforma de publicação.

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. Leia o motivo

Dois campos explicam uma linha com problema. displayStatus é o resumo da plataforma sobre o estado atual da linha. syncIssue é o motivo informado pela própria plataforma de publicação, quando ela fornece um. Leia ambos: no exemplo acima, o displayStatus da Local Mint diz que o parceiro está enfrentando problemas, mas syncIssue informa a causa real, a ausência de um site.

Campo	Exemplo	Use para
`displayStatus`	`Connect your account to sync the listing`	O texto que você mostra a uma pessoa.
`syncIssue`	`Publisher requires website URL`	Escolher a correção. `null` quando a plataforma de publicação não informou um motivo.
`actionRequired`	`true`	Ordenação: `true` significa que nada avança até você agir.

O próprio local também inclui um array createErrors em cada leitura de Listar todos os locais. Ele contém problemas de validação encontrados quando o registro foi criado e é um segundo lugar para consultar quando uma linha falha sem syncIssue.

3. Associe a causa à correção

Um pequeno conjunto de causas explica quase todas as linhas bloqueadas.

Causa	Como se manifesta	Correção
Conta não conectada	Google Maps ou Facebook em `REQUIRING_ACTION` com `Connect your account to sync the listing`.	Conecte a conta dessa plataforma de publicação: Conectar o Google e importar locais ou Conectar Páginas do Facebook. O Apple Maps não precisa de uma conexão; consulte Conectar o Apple Business Connect.
Site ausente	`FAILED` com `syncIssue: Publisher requires website URL`.	Defina `bizUrl` no local. Consulte Atualizar um local.
País não aceito pela plataforma de publicação	`CANNOT_SUBMIT`, sem `syncIssue`.	Compare o `countryIso` do local com o `supportedCountries` desse site, obtido em Listar sites do plano. Não há nada a corrigir; a plataforma de publicação não aceitará o local.
Endereço oculto não aceito	`CANNOT_SUBMIT` ou `FAILED` em uma empresa com área de atendimento e `hideAddress: true`.	Verifique o `hideAddressSupportedCountries` do site. Exiba o endereço ou aceite que essa plataforma de publicação seja ignorada.
Página do Facebook sem horários	Facebook em `IN_PROGRESS` com `syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information`.	Adicione os horários de funcionamento à Página no Facebook e envie uma atualização do local. Consulte Atualizar um local.
Descrição ou categoria rejeitada	`FAILED` com um `syncIssue` que identifica o campo.	Atualize a descrição ou `subCategoryId` no local e consulte novamente.

Para verificar as regras de país e de endereço oculto, busque os sites do plano uma vez e armazene-os em cache; a lista não é paginada e raramente muda.

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 o countryIso do local não estiver em supportedCountries, a linha dessa plataforma de publicação nunca sairá de CANNOT_SUBMIT. Exclua-a do seu cálculo de cobertura em vez de tentar novamente.

4. Consulte novamente após a correção

Uma atualização do local aciona um novo envio às plataformas de publicação afetadas. A linha sai de FAILED ou REQUIRING_ACTION e volta para IN_PROGRESS, depois passa para SYNCED quando a plataforma de publicação a aceita. As plataformas de publicação levam de minutos a semanas, então faça consultas periódicas com intervalos de horas, não de segundos.

Cada consulta conta para o limite de requisições. Ao receber 429, leia Retry-After e aguarde essa quantidade de segundos; os SDKs lançam RateLimitError com o mesmo 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"

O avanço de lastUpdate é o sinal de que a plataforma de publicação processou o novo envio, mesmo antes de syncStatus mudar. Se você tiver webhooks, o evento listing.submission substitui esse ciclo.

5. Faça uma varredura em toda a conta

Para encontrar todas as linhas bloqueadas na conta, percorra as páginas de GET /locations (uma conexão por cursor: first, after, edges[].node) e chame o endpoint premium uma vez por local. Reúna as linhas com problemas em um único relatório organizado por local. O Python SDK percorre os cursores com auto_paging_iter(); o Node SDK faz isso com fetchAll: true. Os exemplos reutilizam a função auxiliar de backoff da etapa 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

O relatório agrupa linhas que ainda estão em processamento com linhas que estão de fato bloqueadas. Separe-as de acordo com a tabela da etapa 3 antes de entregar o relatório a alguém: IN_PROGRESS e PENDING_APPROVAL exigem paciência, REQUIRING_ACTION exige uma conexão e FAILED exige um campo no local.

Próximas etapas

Verifique o status das listagens e os links ativos: o lado sem problemas dos mesmos dados.
Atualize um local: defina bizUrl, a descrição e as categorias.
Conecte o Google e importe locais e Conecte Páginas do Facebook: resolva as linhas com REQUIRING_ACTION.
Referência: Obtenha listagens premium, Liste os sites do plano, Liste todos os locais, Códigos de erro.