Busca por imagem

Recebe a foto de um produto e devolve produtos parecidos da loja, com um texto de apoio opcional.

Use esta rota para o botão "buscar por foto" do aplicativo ou da vitrine. O cliente tira ou escolhe uma foto, a plataforma interpreta o que aparece nela, transforma em uma consulta de texto e roda a busca normal da loja, com as mesmas regras de visibilidade e de preço de Buscar produtos. A imagem não é guardada.

Se a plataforma não conseguir interpretar a foto, mas você mandou o campo hint (um texto de apoio), a busca roda com ele. Em lojas onde o recurso não está disponível, a resposta traz stub: true e nenhum resultado: esconda o botão de câmera nesse caso.

POST/api/v1/storefront/search/imagePública

Buscar produtos a partir de uma foto

Corpo da requisição (multipart/form-data)

imagefile

A foto. O nome do campo é livre: a rota usa o primeiro arquivo enviado. Máximo 8 MiB. Use JPEG, PNG ou WebP.

hintstring

Texto de apoio, por exemplo o rótulo detectado pelo seu aplicativo. É usado quando não há foto ou quando ela não pôde ser interpretada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/search/image" \
  -F "image=@foto-camiseta.jpg" \
  -F "hint=camiseta"

Resposta

200Resultados

json

{
  "stub": false,
  "message": "",
  "query": "camiseta",
  "results": [
    {
      "id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
      "name": "Camiseta Lite Verde 00146",
      "slug": "camiseta-lite-verde-00146-146",
      "price": 39990,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "rating_avg": 4.9,
      "rating_count": 17,
      "status": "A",
      "quantity": 1,
      "track_inventory": true
    }
  ],
  "log_id": "95309ad4-eda4-487c-9d27-fa7e574eb914",
  "search_event_id": "c38e0c8a-ba7e-4236-b1cd-dc5cbf6f215b"
}

200Recurso indisponível na loja

json

{
  "stub": true,
  "message": "image-search is in preview — submit text or use voice search for the best results",
  "query": "camiseta",
  "results": []
}

Campos da resposta

stubboolean

true quando a busca por imagem não está disponível na loja. Esconda o botão de câmera. A message vem em inglês, como retornada pelo servidor.

messagestring

Vazio quando a busca rodou.

querystring

O texto de busca que foi de fato usado: o interpretado da foto ou o seu hint. Mostre-o ao cliente ("Resultados para camiseta") para que ele possa refinar.

resultsarray

Até 20 produtos, no formato descrito em Buscar produtos. Não há paginação.

log_iduuid

Id do registro da busca, para Registrar cliques. Ausente se não houve texto.

search_event_iduuid

Id do evento da busca. Ausente se não houve texto.

Erros

Status	Quando	Corpo
400	O corpo não é `multipart/form-data`	`{"error":"invalid multipart payload","detail":"request Content-Type isn't multipart/form-data"}`
401	A loja exige login para navegar e a chamada não tem token	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
413	O arquivo passa de 8 MiB	`{"error":"image too large"}`
429	Mais de 10 buscas por minuto na mesma sessão	`{"error":"rate limit exceeded ..."}` (mensagem em inglês)

Sem foto e sem hint, a resposta é 200 com results: [] e query vazio.

Veja também

Busca por imagem

Recebe a foto de um produto e devolve produtos parecidos da loja, com um texto de apoio opcional.

POST/api/v1/storefront/search/imagePública

Buscar produtos a partir de uma foto

Corpo da requisição (multipart/form-data)

imagefile

A foto. O nome do campo é livre: a rota usa o primeiro arquivo enviado. Máximo 8 MiB. Use JPEG, PNG ou WebP.

hintstring

Texto de apoio, por exemplo o rótulo detectado pelo seu aplicativo. É usado quando não há foto ou quando ela não pôde ser interpretada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/search/image" \
  -F "image=@foto-camiseta.jpg" \
  -F "hint=camiseta"

Resposta

200Resultados

json

{
  "stub": false,
  "message": "",
  "query": "camiseta",
  "results": [
    {
      "id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
      "name": "Camiseta Lite Verde 00146",
      "slug": "camiseta-lite-verde-00146-146",
      "price": 39990,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "rating_avg": 4.9,
      "rating_count": 17,
      "status": "A",
      "quantity": 1,
      "track_inventory": true
    }
  ],
  "log_id": "95309ad4-eda4-487c-9d27-fa7e574eb914",
  "search_event_id": "c38e0c8a-ba7e-4236-b1cd-dc5cbf6f215b"
}

200Recurso indisponível na loja

json

{
  "stub": true,
  "message": "image-search is in preview — submit text or use voice search for the best results",
  "query": "camiseta",
  "results": []
}

Campos da resposta

stubboolean

true quando a busca por imagem não está disponível na loja. Esconda o botão de câmera. A message vem em inglês, como retornada pelo servidor.

messagestring

Vazio quando a busca rodou.

querystring

O texto de busca que foi de fato usado: o interpretado da foto ou o seu hint. Mostre-o ao cliente ("Resultados para camiseta") para que ele possa refinar.

resultsarray

Até 20 produtos, no formato descrito em Buscar produtos. Não há paginação.

log_iduuid

Id do registro da busca, para Registrar cliques. Ausente se não houve texto.

search_event_iduuid

Id do evento da busca. Ausente se não houve texto.

Erros

Status	Quando	Corpo
400	O corpo não é `multipart/form-data`	`{"error":"invalid multipart payload","detail":"request Content-Type isn't multipart/form-data"}`
401	A loja exige login para navegar e a chamada não tem token	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
413	O arquivo passa de 8 MiB	`{"error":"image too large"}`
429	Mais de 10 buscas por minuto na mesma sessão	`{"error":"rate limit exceeded ..."}` (mensagem em inglês)

Sem foto e sem hint, a resposta é 200 com results: [] e query vazio.