Registrar cliques

Informa à loja qual resultado o cliente clicou depois de uma busca, para alimentar os relatórios de busca do painel.

Quando o cliente clica em um produto da lista de resultados, avise a plataforma. Com isso o painel da loja mostra quais termos geram clique, em que posição o clique acontece e quais termos não dão resultado. Nada muda para o cliente: as duas rotas só gravam um registro e respondem 204 sem corpo.

Há duas rotas, porque a plataforma guarda dois registros por busca:

POST /search/click atribui o clique ao log_id devolvido por Buscar produtos e por Busca por imagem. Informe também a posição do item na lista.
POST /search/events atribui o clique ao search_event_id devolvido por Buscar produtos, por Busca ao vivo e por Busca por imagem.

Na prática, uma vitrine completa chama as duas no clique de um resultado da página de busca, e só /search/events no clique de um item da busca ao vivo.

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

Registrar o clique em um resultado de busca

Corpo da requisição

log_iduuidobrigatório

log_id devolvido pela busca.

product_iduuidobrigatório

Produto clicado.

positioninteger

Posição do produto na lista, como você a exibiu. Use a mesma base (0 ou 1) em toda a vitrine.

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

Registrar o clique em um resultado da busca ao vivo

Corpo da requisição

search_event_iduuidobrigatório

search_event_id devolvido pela busca.

product_iduuidobrigatório

Produto clicado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/search/click" \
  -H "Content-Type: application/json" \
  -d '{"log_id":"e0e3b1ce-6cd2-4ddc-a847-e97af386a2f0","product_id":"db033935-75ea-4b6f-abbb-13d0fcd6386d","position":1}'

curl -X POST "$BASE_URL/api/v1/storefront/search/events" \
  -H "Content-Type: application/json" \
  -d '{"search_event_id":"3e19709e-6461-4f10-9e79-87e38f3d92b4","product_id":"db033935-75ea-4b6f-abbb-13d0fcd6386d"}'

Resposta

204Clique registrado

http

HTTP/1.1 204 No Content

Não há corpo. /search/click responde 204 mesmo quando o registro não pôde ser gravado (é "melhor esforço"): não repita a chamada.

Erros

Status	Quando	Corpo
400	`/search/click` sem `log_id` ou sem `product_id`	`{"error":"log_id and product_id are required"}`
400	`/search/events` com corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
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"}`
500	`/search/events` com `search_event_id` ou `product_id` que não é UUID válido, ou id que não existe	`{"error":"failed to record click","detail":"o valor \"x\" não é um uuid válido. ..."}`

Em detail, a plataforma devolve a mensagem em português.

Veja também

Registrar cliques

Informa à loja qual resultado o cliente clicou depois de uma busca, para alimentar os relatórios de busca do painel.

Há duas rotas, porque a plataforma guarda dois registros por busca:

POST /search/click atribui o clique ao log_id devolvido por Buscar produtos e por Busca por imagem. Informe também a posição do item na lista.
POST /search/events atribui o clique ao search_event_id devolvido por Buscar produtos, por Busca ao vivo e por Busca por imagem.

Na prática, uma vitrine completa chama as duas no clique de um resultado da página de busca, e só /search/events no clique de um item da busca ao vivo.

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

Registrar o clique em um resultado de busca

Corpo da requisição

log_iduuidobrigatório

log_id devolvido pela busca.

product_iduuidobrigatório

Produto clicado.

positioninteger

Posição do produto na lista, como você a exibiu. Use a mesma base (0 ou 1) em toda a vitrine.

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

Registrar o clique em um resultado da busca ao vivo

Corpo da requisição

search_event_iduuidobrigatório

search_event_id devolvido pela busca.

product_iduuidobrigatório

Produto clicado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/search/click" \
  -H "Content-Type: application/json" \
  -d '{"log_id":"e0e3b1ce-6cd2-4ddc-a847-e97af386a2f0","product_id":"db033935-75ea-4b6f-abbb-13d0fcd6386d","position":1}'

curl -X POST "$BASE_URL/api/v1/storefront/search/events" \
  -H "Content-Type: application/json" \
  -d '{"search_event_id":"3e19709e-6461-4f10-9e79-87e38f3d92b4","product_id":"db033935-75ea-4b6f-abbb-13d0fcd6386d"}'

Resposta

204Clique registrado

http

HTTP/1.1 204 No Content

Não há corpo. /search/click responde 204 mesmo quando o registro não pôde ser gravado (é "melhor esforço"): não repita a chamada.

Erros

Status	Quando	Corpo
400	`/search/click` sem `log_id` ou sem `product_id`	`{"error":"log_id and product_id are required"}`
400	`/search/events` com corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
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"}`
500	`/search/events` com `search_event_id` ou `product_id` que não é UUID válido, ou id que não existe	`{"error":"failed to record click","detail":"o valor \"x\" não é um uuid válido. ..."}`

Em detail, a plataforma devolve a mensagem em português.