Envie um logotipo, uma capa e fotos

Anexe logotipo, capa e fotos da galeria a um local por URL, liste os anexos, marque a imagem principal com estrela e remova itens desatualizados.

As fotos são anexadas a um local por URL pública: você hospeda a imagem, a API a busca e armazena, e as plataformas de publicação a recuperam de lá. Um local mantém um logotipo, uma capa e qualquer quantidade de fotos adicionais, e até quatro das fotos adicionais podem ser marcadas com uma estrela para receber posicionamento prioritário.

1. Envie por URL

POST /locations/photos recebe input.locationId e um array input.photos. A URL de cada item vai em um campo chamado photo, não url. Defina type explicitamente como LOGO, COVER ou ADDITIONAL; um item sem type é armazenado 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/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    }  }}

Guarde o id de cada foto: é o que os endpoints de marcação com estrela e remoção recebem. Reenviar um LOGO ou COVER substitui o existente. Um lote pequeno é armazenado diretamente durante a requisição, desta forma. Já um lote grande é colocado na fila: photos retorna vazio e request.requestId é definido. Escolha o fluxo conforme a presença de requestId e, em seguida, consulte GET /locations/photos/requests/{requestId} periodicamente.

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

2. Liste o que está anexado

GET /locations/{locationId}/photos retorna todos os arquivos de mídia do local como um array simples. Use-o para verificar se falta um logotipo ou uma capa antes de enviar e para coletar os ids para as próximas duas etapas. O caminho aceita o id em base64 ou o número sem codificação.

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 é Logo, Cover ou Additional. Um local sem mídia retorna um array vazio, não um erro.

3. Marque fotos adicionais com uma estrela

POST /locations/photos/star marca fotos adicionais para posicionamento prioritário nas plataformas de publicação que oferecem suporte a imagens em destaque. Somente fotos ADDITIONAL podem ser marcadas com uma estrela, no máximo 4 por local; uma quinta faz toda a chamada falhar com SY15012. Você também pode passar starred: true em um item no momento do envio.

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    }  }}

A chave da resposta é starUnstarLocationPhotos e contém um único error, não um array errors. O sinalizador starred no corpo controla a ação: envie false para remover a estrela. Os métodos do SDK recebem o mesmo booleano.

4. Remova uma foto

POST /locations/photos/remove desvincula fotos adicionais por id. removedCount informa quantas foram desvinculadas, então 0 com errors: null significa que nenhum desses ids estava vinculado a este local.

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    }  }}

Somente fotos ADDITIONAL podem ser removidas aqui. Para alterar o logotipo ou a capa, envie uma nova imagem com esse type e ela substituirá a antiga. A remoção desvincula o arquivo do local; ela não necessariamente o exclui da sua biblioteca de mídia.

5. O que as plataformas de publicação fazem com cada posição

Próximos passos

• Atualize um local: horários, fechamentos e categorias do Google no mesmo registro.
• Verifique o status das listagens e os links ativos: veja quando as plataformas de publicação tiverem publicado as novas imagens.
• Enviar fotos, Obter fotos, Marcar fotos com estrela, Remover fotos e Status do envio em massa: as páginas de referência.
• Referências dos SDKs: Fotos em Python e Fotos em Node.