API atual/Referência completa/Imagens do Google

Configuração e histórico

Lê e grava a chave de API do Google e os filtros da pesquisa de imagens, e consulta o histórico de pesquisas e importações.

Antes da primeira pesquisa, a loja informa a chave de API do Google e o ID do mecanismo de busca (Search Engine ID, o cx do Programmable Search). A chave nunca é devolvida em texto puro. O histórico registra cada pesquisa e importação, útil para auditar quem gastou cota e por que uma chamada falhou. Exigem o módulo google-product-images e o privilégio manage_catalog.

GET/api/v1/admin/google-product-images/settingsAdmin

Lê a configuração

Devolve a configuração atual, com a chave mascarada (os 4 primeiros e os 4 últimos caracteres, com bolinhas no meio). has_api_key diz se existe uma chave guardada.

PUT/api/v1/admin/google-product-images/settingsAdmin

Grava a configuração

Grava a configuração inteira. Valores fora dos limites são ajustados em silêncio, sem erro. Responde {"status":"ok"}.

Corpo da requisição (JSON)

api_keystring

Chave de API do Google. Vazia, omitida ou igual à versão mascarada que você recebeu no GET, a chave guardada é mantida. Uma chave nova substitui a antiga. O texto __clear__ apaga a chave.

engine_idstring

ID do mecanismo de busca (cx). Espaços nas pontas são removidos. A API aceita vazio, mas sem ele a pesquisa responde 412.

default_query_templatestringpadrão: {name} {brand}

Modelo da consulta quando a pesquisa parte de um produto. {name} e {brand} são trocados pelo nome e pela marca.

max_resultsintegerpadrão: 10

Máximo de resultados por pesquisa, de 1 a 30. Fora disso, volta a 10.

min_image_widthintegerpadrão: 600

Largura mínima em pixels dos resultados, de 100 a 10000. Fora disso, volta a 600.

safe_searchstringpadrão: high

offmediumhigh

Filtro de conteúdo adulto. medium e high ligam o filtro do Google; off desliga.

GET/api/v1/admin/google-product-images/logsAdmin

Histórico de pesquisas e importações

Do mais novo para o mais antigo.

Parâmetros de consulta

product_iduuid

Só os registros deste produto.

user_iduuid

Só os registros deste usuário.

statusstring

searchdownloaderror

search pesquisa, download importação, error falha.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 100. Fora disso volta a 25.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/google-product-images/settings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "api_key": "AIzaSyEXEMPLO0000000000000000000000000",
    "engine_id": "0123456789abcdef0",
    "default_query_template": "{name} {brand}",
    "max_results": 10,
    "min_image_width": 800,
    "safe_search": "high"
  }'

curl "$BASE_URL/api/v1/admin/google-product-images/logs?status=error" -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração

json

{
  "has_api_key": true,
  "settings": {
    "api_key": "AIza••••••••0000",
    "engine_id": "0123456789abcdef0",
    "default_query_template": "{name} {brand}",
    "max_results": 10,
    "min_image_width": 800,
    "safe_search": "high"
  }
}

200Configuração gravada

json

{ "status": "ok" }

200Histórico

json

{
  "logs": [
    {
      "id": "cb858f38-9586-4e9c-939c-21b9cfe06874",
      "product_id": "bbd65a85-1057-41fc-b652-683bfefba97f",
      "user_id": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "search_query": "camiseta teste",
      "results_count": 0,
      "downloaded_count": 0,
      "status": "search",
      "error_msg": "google-product-images: upstream Google CSE error: status 400: API key not valid. Please pass a valid API key.",
      "created_at": "2026-07-13T08:14:19.978994Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 25,
  "total_pages": 1
}

Campos da configuração

api_keystring

Chave mascarada: 4 primeiros caracteres, 8 bolinhas e 4 últimos. Vazia quando não há chave.

engine_idstring

ID do mecanismo de busca.

default_query_templatestring

Modelo da consulta.

max_resultsinteger

Máximo de resultados por pesquisa.

min_image_widthinteger

Largura mínima, em pixels.

safe_searchstring

offmediumhigh

Filtro de conteúdo adulto.

has_api_keyboolean

Se há uma chave guardada.

Campos de cada registro do histórico

iduuid

Id do registro.

product_iduuid

Produto da pesquisa ou importação. Ausente em pesquisas livres.

user_iduuid

Usuário que fez a chamada.

search_querystring

Texto pesquisado. Vazio nas importações.

results_countinteger

Resultados devolvidos (pesquisa) ou URLs recebidas (importação).

downloaded_countinteger

Imagens importadas.

statusstring

searchdownloaderror

Tipo e resultado do registro.

error_msgstring

Mensagem do erro, quando houve.

created_atstring

Quando aconteceu, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid_input","detail":"malformed JSON"}`
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"}`
500	Falha ao ler ou gravar	`{"error":"internal_error","detail":"..."}`

Veja também

Configuração e histórico

Lê e grava a chave de API do Google e os filtros da pesquisa de imagens, e consulta o histórico de pesquisas e importações.

GET/api/v1/admin/google-product-images/settingsAdmin

Lê a configuração

Devolve a configuração atual, com a chave mascarada (os 4 primeiros e os 4 últimos caracteres, com bolinhas no meio). has_api_key diz se existe uma chave guardada.

PUT/api/v1/admin/google-product-images/settingsAdmin

Grava a configuração

Grava a configuração inteira. Valores fora dos limites são ajustados em silêncio, sem erro. Responde {"status":"ok"}.

Corpo da requisição (JSON)

api_keystring

Chave de API do Google. Vazia, omitida ou igual à versão mascarada que você recebeu no GET, a chave guardada é mantida. Uma chave nova substitui a antiga. O texto __clear__ apaga a chave.

engine_idstring

ID do mecanismo de busca (cx). Espaços nas pontas são removidos. A API aceita vazio, mas sem ele a pesquisa responde 412.

default_query_templatestringpadrão: {name} {brand}

Modelo da consulta quando a pesquisa parte de um produto. {name} e {brand} são trocados pelo nome e pela marca.

max_resultsintegerpadrão: 10

Máximo de resultados por pesquisa, de 1 a 30. Fora disso, volta a 10.

min_image_widthintegerpadrão: 600

Largura mínima em pixels dos resultados, de 100 a 10000. Fora disso, volta a 600.

safe_searchstringpadrão: high

offmediumhigh

Filtro de conteúdo adulto. medium e high ligam o filtro do Google; off desliga.

GET/api/v1/admin/google-product-images/logsAdmin

Histórico de pesquisas e importações

Do mais novo para o mais antigo.

Parâmetros de consulta

product_iduuid

Só os registros deste produto.

user_iduuid

Só os registros deste usuário.

statusstring

searchdownloaderror

search pesquisa, download importação, error falha.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 100. Fora disso volta a 25.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/google-product-images/settings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "api_key": "AIzaSyEXEMPLO0000000000000000000000000",
    "engine_id": "0123456789abcdef0",
    "default_query_template": "{name} {brand}",
    "max_results": 10,
    "min_image_width": 800,
    "safe_search": "high"
  }'

curl "$BASE_URL/api/v1/admin/google-product-images/logs?status=error" -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração

json

{
  "has_api_key": true,
  "settings": {
    "api_key": "AIza••••••••0000",
    "engine_id": "0123456789abcdef0",
    "default_query_template": "{name} {brand}",
    "max_results": 10,
    "min_image_width": 800,
    "safe_search": "high"
  }
}

200Configuração gravada

json

{ "status": "ok" }

200Histórico

json

{
  "logs": [
    {
      "id": "cb858f38-9586-4e9c-939c-21b9cfe06874",
      "product_id": "bbd65a85-1057-41fc-b652-683bfefba97f",
      "user_id": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "search_query": "camiseta teste",
      "results_count": 0,
      "downloaded_count": 0,
      "status": "search",
      "error_msg": "google-product-images: upstream Google CSE error: status 400: API key not valid. Please pass a valid API key.",
      "created_at": "2026-07-13T08:14:19.978994Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 25,
  "total_pages": 1
}

Campos da configuração

api_keystring

Chave mascarada: 4 primeiros caracteres, 8 bolinhas e 4 últimos. Vazia quando não há chave.

engine_idstring

ID do mecanismo de busca.

default_query_templatestring

Modelo da consulta.

max_resultsinteger

Máximo de resultados por pesquisa.

min_image_widthinteger

Largura mínima, em pixels.

safe_searchstring

offmediumhigh

Filtro de conteúdo adulto.

has_api_keyboolean

Se há uma chave guardada.

Campos de cada registro do histórico

iduuid

Id do registro.

product_iduuid

Produto da pesquisa ou importação. Ausente em pesquisas livres.

user_iduuid

Usuário que fez a chamada.

search_querystring

Texto pesquisado. Vazio nas importações.

results_countinteger

Resultados devolvidos (pesquisa) ou URLs recebidas (importação).

downloaded_countinteger

Imagens importadas.

statusstring

searchdownloaderror

Tipo e resultado do registro.

error_msgstring

Mensagem do erro, quando houve.

created_atstring

Quando aconteceu, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid_input","detail":"malformed JSON"}`
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"}`
500	Falha ao ler ou gravar	`{"error":"internal_error","detail":"..."}`