Enviar fotos para um local

Parâmetros

Corpo

Um campo aninhado marcado como obrigatório só se aplica quando você envia o campo pai. Se o campo pai for opcional e você o omitir, os campos filhos obrigatórios não se aplicam.

Nome	Tipo	Obrigatório	Descrição
input.locationId	string	obrigatório	The location's Base64-encoded Relay ID to attach media to.
input.photos	array of objects	obrigatório	Images to attach. `photo` is the only required key on each item.
input.photos[].photo	string	obrigatório	A publicly accessible JPEG or PNG URL that Listings API fetches and stores. The field is named `photo`, not `url`.
input.photos[].type	string	opcional	Which slot the image fills: `LOGO`, `COVER`, or `ADDITIONAL`. Defaults to an additional photo.
input.photos[].starred	boolean	opcional	Star the photo as it is attached, instead of a follow-up call to the star endpoint. Only additional photos can be starred, at most 4 per location.
input.photos[].source	string	opcional	Free-text label recording where the image came from.

Exemplo de requisição

Corpo pronto para colar. Substitua os IDs e valores de exemplo pelos seus.

Request body

{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}

Respostas

200Photos attached inline. Returns the created photo records; `errors` is null on success and `request` is empty because nothing was queued.

Response

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

401Unauthenticated, missing or invalid API key.

Anexa uma ou mais imagens a um local. Forneça um array photos em que cada item contenha pelo menos photo, uma URL pública de imagem que a Listings API busca e armazena. locationId e um array photos não vazio são sempre obrigatórios.

Dois formatos de resposta de sucesso

Um lote pequeno é enviado durante a própria chamada: photos contém a mídia já processada e request é um objeto vazio, como no exemplo acima. Um lote grande é colocado na fila, e o mesmo 200 tem este formato:

JSON

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

Ambos indicam sucesso, então trate-os verificando se request.requestId está presente, em vez de presumir que photos está preenchido.

O campo de URL é photo. Não é url nem image. Além dele, cada item aceita os campos opcionais type (LOGO, COVER ou ADDITIONAL), starred e source; publisherOverride e partnerMediaId também são aceitos para integrações de parceiros. Uma foto retornada não tem o campo caption.

Caso de uso: adicionar as imagens iniciais de um novo local. Logo após criar um local como "Jenny Home", use POST para enviar o logotipo e as fotos da fachada por URL em uma única chamada. A resposta retorna o id de cada nova foto, que você passa posteriormente aos endpoints de destaque e remoção.

Caso de uso: reutilizar um recurso aprovado em vários locais. Aponte vários locais para a mesma URL de imagem hospedada nos respectivos arrays photos para que todos os locais compartilhem o mesmo recurso de origem.

Pontos de atenção.

As imagens devem estar em JPEG ou PNG. As regras de tamanho das plataformas de publicação se aplicam por categoria (um mínimo típico é de ~10 KB e o máximo é de alguns MB).
Lotes grandes são processados de forma assíncrona. Quando o tamanho do lote ultrapassa o limite definido no servidor, a chamada coloca o trabalho na fila em vez de realizar o envio durante a própria chamada: photos retorna vazio e request.requestId é definido. Consulte periodicamente GET /locations/photos/requests/{requestId} com esse id para acompanhar a conclusão. O limite é uma configuração do servidor, então considere que "lotes grandes podem ser colocados na fila", em vez de adotar um número fixo, e escolha o fluxo de execução com base na presença de request.requestId.
Não escolha o fluxo de execução com base em request.status. Na resposta de enfileiramento, ele é a string literal PROCCESSING, cuja grafia difere de PROCESSING, que o endpoint de consulta periódica informa para o mesmo trabalho. A presença de request.requestId é o sinal confiável.
Passar starred: true para mais do que as 4 fotos em destaque permitidas faz a chamada inteira falhar com SY15012. A verificação conta as fotos em destaque já existentes no local mais os itens em destaque nesta requisição.
Um local mantém um único logotipo e uma única capa; reenviar uma imagem de qualquer uma dessas categorias substitui a imagem existente.
Defina type explicitamente quando quiser que uma imagem seja o logotipo ou a capa. Sem esse campo, a imagem é armazenada como uma 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/storefront.jpg", "type": "ADDITIONAL" } ] } }'