Sube un logotipo, una portada y fotos

Añade por URL un logo, una portada y fotos de galería a una ubicación; lista los adjuntos, marca con estrella la imagen principal y borra los obsoletos.

Las fotos se adjuntan a una ubicación mediante una URL pública: tú alojas la imagen, la API la descarga y la almacena, y las plataformas de publicación la recuperan desde allí. Una ubicación conserva un logotipo, una portada y cualquier número de fotos adicionales, y hasta cuatro de las fotos adicionales pueden marcarse con una estrella para darles prioridad de visualización.

1. Sube imágenes mediante URL

POST /locations/photos recibe input.locationId y un array input.photos. La URL de cada elemento va en un campo llamado photo, no url. Establece type explícitamente en LOGO, COVER o ADDITIONAL; un elemento sin type se almacena como foto adicional.

curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/cover.jpg", "type": "COVER" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

{  "data": {    "addLocationPhotos": {      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false }      ],      "errors": null    }  }}

Conserva el id de cada foto: es lo que reciben los endpoints para marcar con una estrella y eliminar. Volver a subir un LOGO o un COVER sustituye al existente. Un lote pequeño se almacena directamente, como se muestra aquí. Un lote grande, en cambio, se pone en cola: photos se devuelve vacío y se establece request.requestId. Elige la lógica que se ejecutará según si requestId está presente y, después, consulta periódicamente GET /locations/photos/requests/{requestId}.

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

2. Enumera los archivos adjuntos

GET /locations/{locationId}/photos devuelve todos los archivos multimedia de la ubicación en un array simple. Úsalo para comprobar si falta un logotipo o una portada antes de subir imágenes y para recopilar los identificadores de los dos pasos siguientes. La ruta acepta el identificador en base64 o el número sin codificar.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 }    ]  }}

categoryName es Logo, Cover o Additional. Una ubicación sin archivos multimedia devuelve un array vacío, no un error.

3. Marca fotos adicionales con una estrella

POST /locations/photos/star marca fotos adicionales para darles prioridad de visualización en las plataformas de publicación que admiten imágenes destacadas. Solo se pueden marcar con una estrella las fotos ADDITIONAL, con un máximo de 4 por ubicación; una quinta hace que falle toda la llamada con SY15012. También puedes pasar starred: true en un elemento al subirlo.

curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

La clave de la respuesta es starUnstarLocationPhotos y contiene un único error, no un array errors. El indicador starred del cuerpo controla la acción: envía false para quitar la estrella. Los métodos del SDK reciben el mismo valor booleano.

4. Elimina una foto

POST /locations/photos/remove desvincula fotos adicionales por identificador. removedCount indica cuántas se han desvinculado, por lo que 0 con errors: null significa que ninguno de esos identificadores estaba vinculado a esta ubicación.

curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="]  }}'

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

Aquí solo se pueden eliminar fotos ADDITIONAL. Para cambiar el logotipo o la portada, sube una imagen nueva con ese type y sustituirá a la anterior. La eliminación desvincula el archivo de la ubicación; no lo elimina necesariamente de tu biblioteca multimedia.

5. Qué hacen las plataformas de publicación con cada tipo de imagen

Próximos pasos

• Actualizar una ubicación: horarios, cierres y categorías de Google en el mismo registro.
• Consultar el estado de las fichas y los enlaces activos: consulta cuándo las plataformas de publicación han publicado las nuevas imágenes.
• Subir fotos, Obtener fotos, Marcar fotos como favoritas, Eliminar fotos y Estado de la carga masiva: las páginas de referencia.
• Referencias del SDK: Fotos en Python y Fotos en Node.