Importer des photos pour un établissement

Associe une ou plusieurs images à un établissement. Fournissez un tableau photos dont chaque élément contient au minimum photo, une URL d’image publique à partir de laquelle Listings API récupère et stocke l’image. locationId et un tableau photos non vide sont toujours requis.

Deux formes de réponse de succès

Un petit lot est importé directement pendant l’appel : photos contient les médias dont l’importation est terminée et request est un objet vide, comme dans l’exemple ci-dessus. Un grand lot est plutôt mis en file d’attente, et le même 200 se présente alors ainsi :

{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {        "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",        "status": "PROCCESSING"      },      "photos": [],      "errors": null    }  }}

Les deux cas correspondent à un succès ; traitez-les donc en vérifiant la présence de request.requestId plutôt qu’en supposant que photos contient des données.

Le champ URL est photo. Ce n’est ni url ni image. En complément, chaque élément accepte les champs facultatifs type (LOGO, COVER ou ADDITIONAL), starred et source ; publisherOverride et partnerMediaId sont également acceptés pour les intégrations partenaires. Une photo renvoyée ne comporte pas de champ caption.

Cas d’utilisation : ajouter les premières images d’un nouvel établissement. Juste après avoir créé un établissement tel que « Jenny Home », utilisez POST pour importer son logo et ses photos de devanture à partir de leurs URL en un seul appel. La réponse renvoie le id de chaque nouvelle photo, que vous transmettez ensuite aux endpoints de mise en favori et de suppression.

Cas d’utilisation : réutiliser une ressource approuvée pour plusieurs établissements. Indiquez la même URL d’image hébergée dans les tableaux photos de plusieurs établissements afin que chaque établissement partage la même ressource source.

Points d’attention.

• Les images doivent être au format JPEG ou PNG. Les règles de taille des plateformes de publication s’appliquent par catégorie (le minimum habituel est d’environ 10 Ko et le maximum de quelques Mo).
• Les grands lots sont traités de manière asynchrone. Au-delà d’une taille de lot définie côté serveur, l’appel met le travail en file d’attente au lieu d’effectuer l’importation directement : photos est renvoyé vide et request.requestId est renseigné. Interrogez régulièrement GET /locations/photos/requests/{requestId} avec cet identifiant pour suivre l’avancement jusqu’à la fin du traitement. Le seuil est configuré côté serveur ; considérez donc que « les grands lots peuvent être mis en file d’attente » plutôt que de vous baser sur un nombre fixe, et choisissez le traitement à appliquer selon la présence de request.requestId.
• Ne choisissez pas le traitement à appliquer en fonction de request.status. Dans la réponse de mise en file d’attente, sa valeur est la chaîne littérale PROCCESSING, dont l’orthographe diffère de celle de PROCESSING, que l’endpoint de suivi renvoie pour la même tâche. La présence de request.requestId est l’indicateur fiable.
• Transmettre starred: true pour un nombre de photos favorites dépassant la limite de 4 fait échouer l’appel entier avec SY15012. La vérification compte les photos favorites déjà présentes pour l’établissement ainsi que les éléments marqués comme favoris dans cette requête.
• Un établissement conserve un seul logo et une seule image de couverture ; une nouvelle importation dans l’une de ces catégories remplace l’image existante.
• Définissez explicitement type lorsque vous souhaitez utiliser une image comme logo ou comme image de couverture. Sans ce champ, l’image est stockée comme photo supplémentaire.