Subir fotos a una ubicación

Adjunta una o más imágenes a una ubicación. Proporciona un array photos en el que cada elemento incluya al menos photo, una URL pública de imagen que Listings API descarga y almacena. Siempre se requieren locationId y un array photos que no esté vacío.

Dos formas de éxito

Un lote pequeño se sube de forma síncrona: photos contiene el contenido multimedia ya procesado y request es un objeto vacío, como en el ejemplo anterior. En cambio, un lote grande se pone en cola y el mismo 200 tiene este aspecto:

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

Ambos casos indican éxito, así que gestiónalos comprobando si request.requestId está presente en lugar de suponer que photos contiene datos.

El campo de URL es photo. No es url ni image. Además, cada elemento admite los campos opcionales type (LOGO, COVER o ADDITIONAL), starred y source; también se aceptan publisherOverride y partnerMediaId para integraciones con socios. Una foto devuelta no tiene el campo caption.

Caso de uso: añadir las imágenes iniciales de una nueva ubicación. Justo después de crear una ubicación como "Jenny Home", sube su logotipo y las fotos de su fachada por URL mediante POST en una sola llamada. La respuesta devuelve el id de cada foto nueva, que luego pasas a los endpoints para destacar y eliminar fotos.

Caso de uso: reutilizar un recurso aprobado en varias ubicaciones. Usa la misma URL de imagen alojada en los arrays photos de varias ubicaciones para que todas compartan el mismo recurso de origen.

Aspectos que debes tener en cuenta.

• Las imágenes deben ser JPEG o PNG. Las reglas de tamaño de las plataformas de publicación se aplican por categoría (un mínimo habitual es de unos 10 KB y un máximo de unos pocos MB).
• Los lotes grandes se procesan de forma asíncrona. Si se supera el tamaño de lote establecido en el servidor, la llamada pone el trabajo en cola en lugar de subir las imágenes de forma síncrona: photos se devuelve vacío y se establece request.requestId. Consulta periódicamente GET /locations/photos/requests/{requestId} con ese id para comprobar cuándo se completa el trabajo. El umbral se configura en el servidor, así que interprétalo como "los lotes grandes pueden ponerse en cola" en lugar de asumir un número fijo, y elige la rama de ejecución según si request.requestId está presente.
• No bases la lógica condicional en request.status. En la respuesta de un trabajo en cola, su valor es la cadena literal PROCCESSING, que se escribe de forma distinta a PROCESSING, el valor que devuelve el endpoint de consulta periódica para el mismo trabajo. La presencia de request.requestId es el indicador fiable.
• Pasar starred: true para más de las 4 fotos destacadas permitidas hace que falle toda la llamada con SY15012. La comprobación cuenta las fotos destacadas que ya tiene la ubicación más los elementos destacados de esta solicitud.
• Una ubicación conserva un único logotipo y una única imagen de portada; volver a subir una imagen de cualquiera de estas categorías reemplaza la imagen existente.
• Establece type explícitamente cuando quieras que una imagen sea el logotipo o la portada. Sin este campo, la imagen se almacena como una foto adicional.