Repérer et corriger les erreurs des fiches

Filtrez les fiches d’établissement à traiter, lisez le motif de la plateforme de publication, corrigez, revérifiez sans risque et contrôlez tout le compte.

La plupart des fiches se synchronisent sans intervention. Celles qui ne se synchronisent pas en indiquent la raison dans displayStatus et syncIssue, et presque chaque cause correspond à l'une des cinq corrections possibles. Ce guide vous accompagne depuis les lignes brutes des fiches jusqu'à un rapport par compte indiquant les blocages et les mesures à prendre.

1. Récupérer les fiches et conserver les lignes problématiques

Récupérez les fiches premium et écartez toutes celles qui ne présentent aucun problème. Une ligne nécessite votre attention lorsque actionRequired vaut true, ou lorsque syncStatus vaut FAILED, CANNOT_SUBMIT ou REQUIRING_ACTION. IN_PROGRESS et PENDING_APPROVAL ne sont pas des erreurs ; ils correspondent à la file d'attente de la plateforme de publication.

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. Lire la raison

Deux champs expliquent le problème d'une ligne. displayStatus est le résumé fourni par la plateforme sur l'état de la ligne. syncIssue est la raison fournie par la plateforme de publication elle-même, lorsqu'elle en a donné une. Lisez les deux : dans l'exemple ci-dessus, le champ displayStatus de Local Mint indique que le partenaire rencontre des problèmes, mais syncIssue donne la véritable cause, à savoir l'absence de site web.

Champ	Exemple	Utilité
`displayStatus`	`Connect your account to sync the listing`	Le texte à présenter à une personne.
`syncIssue`	`Publisher requires website URL`	Choisir la correction. `null` lorsque la plateforme de publication n'a fourni aucune raison.
`actionRequired`	`true`	Trier : `true` signifie que rien ne progresse tant que vous n'intervenez pas.

L'établissement lui-même comporte également un tableau createErrors à chaque lecture via Répertorier tous les établissements. Il contient les problèmes de validation détectés lors de la création de l'enregistrement et constitue une deuxième source à consulter lorsqu'une ligne échoue sans syncIssue.

3. Associer la cause à la correction

Un petit nombre de causes explique presque toutes les lignes bloquées.

Cause	Manifestation	Correction
Compte non connecté	Google Maps ou Facebook à l'état `REQUIRING_ACTION` avec `Connect your account to sync the listing`.	Connectez le compte de cette plateforme de publication : Connecter Google et importer des établissements ou Connecter des Pages Facebook. Apple Maps ne nécessite pas de connexion ; consultez Connecter Apple Business Connect.
Site web manquant	`FAILED` avec `syncIssue: Publisher requires website URL`.	Renseignez `bizUrl` pour l'établissement. Consultez Mettre à jour un établissement.
Pays non pris en charge par la plateforme de publication	`CANNOT_SUBMIT`, sans `syncIssue`.	Comparez le champ `countryIso` de l'établissement au champ `supportedCountries` de ce site, obtenu via Répertorier les sites du forfait. Il n'y a rien à corriger ; la plateforme de publication n'acceptera pas cette fiche.
Adresse masquée non prise en charge	`CANNOT_SUBMIT` ou `FAILED` pour une entreprise desservant une zone géographique avec `hideAddress: true`.	Vérifiez le champ `hideAddressSupportedCountries` du site. Affichez l'adresse ou acceptez que cette plateforme de publication soit ignorée.
La Page Facebook n'a pas d'horaires	Facebook à l'état `IN_PROGRESS` avec `syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information`.	Ajoutez des horaires d'ouverture à la Page sur Facebook, puis envoyez une mise à jour de l'établissement. Consultez Mettre à jour un établissement.
Description ou catégorie refusée	`FAILED` avec un `syncIssue` indiquant le nom du champ.	Mettez à jour la description ou `subCategoryId` de l'établissement, puis relancez les vérifications.

Pour vérifier les règles relatives aux pays et aux adresses masquées, récupérez les sites du forfait une seule fois et mettez-les en cache ; la liste n'est pas paginée et change rarement.

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 le champ countryIso de l'établissement ne figure pas dans supportedCountries, la ligne de cette plateforme de publication ne quittera jamais l'état CANNOT_SUBMIT. Excluez-la de votre indicateur de couverture plutôt que de réessayer.

4. Relancer les vérifications après la correction

Une mise à jour de l'établissement déclenche un nouvel envoi aux plateformes de publication concernées. La ligne passe de FAILED ou REQUIRING_ACTION à IN_PROGRESS, puis à SYNCED lorsque la plateforme de publication l'accepte. Les plateformes de publication peuvent prendre de quelques minutes à plusieurs semaines ; espacez donc les vérifications de plusieurs heures, et non de quelques secondes.

Chaque vérification est comptabilisée dans la limite de débit. En cas de 429, lisez Retry-After et attendez le nombre de secondes indiqué ; les SDK lèvent RateLimitError avec la même valeur.

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"

La progression de lastUpdate indique que la plateforme de publication a traité le nouvel envoi, avant même que syncStatus ne change. Si vous disposez de webhooks, l'événement listing.submission remplace cette boucle.

5. Effectuez une vérification à l’échelle du compte

Pour trouver toutes les lignes bloquées dans le compte, parcourez les pages de GET /locations (une connexion à curseur : first, after, edges[].node) et appelez le point de terminaison premium une fois par établissement. Rassemblez les lignes problématiques dans un seul rapport organisé par établissement. Le Python SDK suit les curseurs avec auto_paging_iter() ; le Node SDK le fait avec fetchAll: true. Les exemples réutilisent la fonction auxiliaire de temporisation entre les tentatives de l’étape 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

Le rapport regroupe les lignes encore en cours de traitement avec celles qui sont réellement bloquées. Séparez-les selon le tableau de l’étape 3 avant de transmettre le rapport à qui que ce soit : IN_PROGRESS et PENDING_APPROVAL demandent de la patience, REQUIRING_ACTION nécessite une connexion et FAILED nécessite un champ sur l’établissement.

Étapes suivantes

Vérifier l’état des fiches et les liens actifs : les mêmes données, du côté des fiches sans problème.
Mettre à jour un établissement : définir bizUrl, la description et les catégories.
Connecter Google et importer des établissements et Connecter des pages Facebook : résoudre les problèmes des fiches à l’état REQUIRING_ACTION.
Référence : Obtenir les fiches premium, Lister les sites du forfait, Lister tous les établissements, Codes d’erreur.