API atual/Referência completa/Imagens do Google

Pesquisar e importar imagens

Pesquisa imagens no Google para um produto e importa as escolhidas para a galeria, com o resultado de cada URL.

São os dois passos do fluxo: pesquisar devolve candidatos sem gravar nada, e importar baixa as URLs que você escolheu e as anexa ao produto. Exigem o módulo google-product-images, o privilégio manage_catalog e a configuração feita (chave e mecanismo de busca).

POST/api/v1/admin/google-product-images/searchAdmin

Pesquisa imagens no Google

Consulta o Google Imagens e devolve os candidatos, sem baixar nem gravar nada no produto. Cada chamada gasta cota da sua chave do Google (uma requisição por até 10 resultados, no máximo 3) e entra no histórico.

Corpo da requisição (JSON)

product_iduuid

Produto de referência. Serve para montar a consulta (pelo modelo da configuração, como {name} {brand}) e para o histórico. Opcional se você mandar query.

querystring

Texto da pesquisa. Quando vazio, a consulta é montada a partir do produto. Sem query e sem product_id, a resposta é 400.

max_resultsinteger

Quantos resultados no máximo. Nunca passa do max_results da configuração, e o teto absoluto é 30. Omitido, vale o da configuração.

POST/api/v1/admin/google-product-images/downloadAdmin

Importa imagens escolhidas para um produto

Baixa cada URL no servidor, confere o tipo (JPEG, PNG, WebP ou GIF) e o tamanho (até 10 MiB), grava o arquivo e o anexa à galeria do produto. É tolerante a falhas: cada URL tem o seu resultado, e uma que falha não impede as outras. O tempo total é limitado a 90 segundos.

Corpo da requisição (JSON)

product_iduuidobrigatório

Produto que recebe as imagens. Precisa existir.

image_urlsarrayobrigatório

URLs das imagens (campo link dos resultados da pesquisa). Só http:// e https://. Até 30; as demais são ignoradas.

Exemplo de requisição

bash

# 1) pesquisar
curl -X POST "$BASE_URL/api/v1/admin/google-product-images/search" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035"}'

# 2) importar as escolhidas
curl -X POST "$BASE_URL/api/v1/admin/google-product-images/download" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","image_urls":["https://cdn.example.com/cafeteira-frente.jpg"]}'

Resposta

200Resultados da pesquisa

json

{
  "query": "Cafeteira Elétrica Acme",
  "total": 2,
  "results": [
    {
      "title": "Cafeteira Elétrica Acme 15 Xícaras",
      "link": "https://cdn.example.com/cafeteira-frente.jpg",
      "width": 1200,
      "height": 1200,
      "byte_size": 184320,
      "mime": "image/jpeg",
      "thumbnail_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:abc",
      "thumbnail_width": 150,
      "thumbnail_height": 150,
      "source_page_url": "https://loja.example.com/cafeteira-acme"
    }
  ]
}

200Importação

json

{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "imported": 1,
  "failed": 1,
  "results": [
    {
      "url": "https://cdn.example.com/cafeteira-frente.jpg",
      "success": true,
      "media_id": "5d2c0a7e-8b1f-4c3d-9e6a-2f1b7c8d9e01",
      "image_id": "a1f0c9d8-7e6b-4a5c-8d3e-9f2b1c0d4e56"
    },
    {
      "url": "https://cdn.example.com/removida.jpg",
      "success": false,
      "error": "download: status 404"
    }
  ],
  "media_ids": ["5d2c0a7e-8b1f-4c3d-9e6a-2f1b7c8d9e01"],
  "image_ids": ["a1f0c9d8-7e6b-4a5c-8d3e-9f2b1c0d4e56"]
}

Campos da pesquisa

querystring

Texto efetivamente pesquisado.

totalinteger

Número de resultados devolvidos.

resultsarray

Candidatos, já sem os menores que min_image_width.

Campos de cada resultado

titlestring

Título da imagem no Google.

linkstring

Endereço da imagem original. É o que vai em image_urls.

widthinteger

Largura em pixels.

heightinteger

Altura em pixels.

byte_sizeinteger

Tamanho em bytes, quando o Google informa.

mimestring

Tipo da imagem, como image/jpeg.

thumbnail_urlstring

Miniatura para mostrar em tela.

thumbnail_widthinteger

Largura da miniatura.

thumbnail_heightinteger

Altura da miniatura.

source_page_urlstring

Página onde a imagem foi encontrada. Útil para conferir os direitos de uso.

Campos da importação

product_iduuid

O produto.

importedinteger

Imagens anexadas.

failedinteger

URLs que falharam.

resultsarray

Um item por URL: url, success, media_id e image_id (quando deu certo) ou error (quando falhou).

media_idsarray

Ids dos arquivos gravados na mídia da loja.

image_idsarray

Ids das imagens criadas na galeria do produto.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid_input","detail":"malformed JSON"}`
400	`search` sem `query` e sem `product_id`; `download` sem `product_id` ou sem `image_urls`	`{"error":"invalid_input","detail":"google-product-images: invalid input"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta `manage_catalog`	`{"error":"module_disabled","module":"google-product-images"}`
207	`download` em que nenhuma imagem foi importada e ao menos uma falhou	corpo igual ao de 200, com `imported: 0`
412	Chave ou mecanismo de busca não configurados	`{"error":"not_configured","detail":"Google API key or engine ID not set. Configure under Modules → Google Product Images."}`
500	Produto do `download` não existe	`{"error":"internal_error","detail":"google-product-images: product not found: ..."}`
502	O Google recusou a consulta (chave inválida, cota esgotada)	`{"error":"upstream_error","detail":"google-product-images: upstream Google CSE error: status 400: API key not valid. ..."}`

Veja também

Pesquisar e importar imagens

Pesquisa imagens no Google para um produto e importa as escolhidas para a galeria, com o resultado de cada URL.

POST/api/v1/admin/google-product-images/searchAdmin

Pesquisa imagens no Google

Corpo da requisição (JSON)

product_iduuid

Produto de referência. Serve para montar a consulta (pelo modelo da configuração, como {name} {brand}) e para o histórico. Opcional se você mandar query.

querystring

Texto da pesquisa. Quando vazio, a consulta é montada a partir do produto. Sem query e sem product_id, a resposta é 400.

max_resultsinteger

Quantos resultados no máximo. Nunca passa do max_results da configuração, e o teto absoluto é 30. Omitido, vale o da configuração.

POST/api/v1/admin/google-product-images/downloadAdmin

Importa imagens escolhidas para um produto

Corpo da requisição (JSON)

product_iduuidobrigatório

Produto que recebe as imagens. Precisa existir.

image_urlsarrayobrigatório

URLs das imagens (campo link dos resultados da pesquisa). Só http:// e https://. Até 30; as demais são ignoradas.

Exemplo de requisição

bash

# 1) pesquisar
curl -X POST "$BASE_URL/api/v1/admin/google-product-images/search" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035"}'

# 2) importar as escolhidas
curl -X POST "$BASE_URL/api/v1/admin/google-product-images/download" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","image_urls":["https://cdn.example.com/cafeteira-frente.jpg"]}'

Resposta

200Resultados da pesquisa

json

{
  "query": "Cafeteira Elétrica Acme",
  "total": 2,
  "results": [
    {
      "title": "Cafeteira Elétrica Acme 15 Xícaras",
      "link": "https://cdn.example.com/cafeteira-frente.jpg",
      "width": 1200,
      "height": 1200,
      "byte_size": 184320,
      "mime": "image/jpeg",
      "thumbnail_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:abc",
      "thumbnail_width": 150,
      "thumbnail_height": 150,
      "source_page_url": "https://loja.example.com/cafeteira-acme"
    }
  ]
}

200Importação

json

{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "imported": 1,
  "failed": 1,
  "results": [
    {
      "url": "https://cdn.example.com/cafeteira-frente.jpg",
      "success": true,
      "media_id": "5d2c0a7e-8b1f-4c3d-9e6a-2f1b7c8d9e01",
      "image_id": "a1f0c9d8-7e6b-4a5c-8d3e-9f2b1c0d4e56"
    },
    {
      "url": "https://cdn.example.com/removida.jpg",
      "success": false,
      "error": "download: status 404"
    }
  ],
  "media_ids": ["5d2c0a7e-8b1f-4c3d-9e6a-2f1b7c8d9e01"],
  "image_ids": ["a1f0c9d8-7e6b-4a5c-8d3e-9f2b1c0d4e56"]
}

Campos da pesquisa

querystring

Texto efetivamente pesquisado.

totalinteger

Número de resultados devolvidos.

resultsarray

Candidatos, já sem os menores que min_image_width.

Campos de cada resultado

titlestring

Título da imagem no Google.

linkstring

Endereço da imagem original. É o que vai em image_urls.

widthinteger

Largura em pixels.

heightinteger

Altura em pixels.

byte_sizeinteger

Tamanho em bytes, quando o Google informa.

mimestring

Tipo da imagem, como image/jpeg.

thumbnail_urlstring

Miniatura para mostrar em tela.

thumbnail_widthinteger

Largura da miniatura.

thumbnail_heightinteger

Altura da miniatura.

source_page_urlstring

Página onde a imagem foi encontrada. Útil para conferir os direitos de uso.

Campos da importação

product_iduuid

O produto.

importedinteger

Imagens anexadas.

failedinteger

URLs que falharam.

resultsarray

Um item por URL: url, success, media_id e image_id (quando deu certo) ou error (quando falhou).

media_idsarray

Ids dos arquivos gravados na mídia da loja.

image_idsarray

Ids das imagens criadas na galeria do produto.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid_input","detail":"malformed JSON"}`
400	`search` sem `query` e sem `product_id`; `download` sem `product_id` ou sem `image_urls`	`{"error":"invalid_input","detail":"google-product-images: invalid input"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta `manage_catalog`	`{"error":"module_disabled","module":"google-product-images"}`
207	`download` em que nenhuma imagem foi importada e ao menos uma falhou	corpo igual ao de 200, com `imported: 0`
412	Chave ou mecanismo de busca não configurados	`{"error":"not_configured","detail":"Google API key or engine ID not set. Configure under Modules → Google Product Images."}`
500	Produto do `download` não existe	`{"error":"internal_error","detail":"google-product-images: product not found: ..."}`
502	O Google recusou a consulta (chave inválida, cota esgotada)	`{"error":"upstream_error","detail":"google-product-images: upstream Google CSE error: status 400: API key not valid. ..."}`