API atual/Referência completa/Venddor Intelligence na vitrine

Aviso proativo e foto

Obtém o aviso contextual da página e busca produtos a partir de uma foto.

Duas rotas de apoio à conversa: um aviso que o assistente mostra sozinho enquanto o cliente navega, e a busca de produtos a partir de uma foto.

Aviso proativo

O aviso proativo é uma frase curta, escolhida pelas regras da loja (não pela conversa), que o botão do assistente exibe como um balão: "faltam R$ 40 para frete grátis", "o preço de um item da sua lista caiu". Clicar no balão abre a conversa.

POST/api/v1/storefront/intelligence/proactiveAutenticada

Aviso contextual para a página atual

Pergunta ao servidor se há algo útil a dizer ao cliente na página atual. Chame em cada navegação; a resposta é barata e rápida (o servidor desiste em 2 segundos e devolve {}).

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado. Opcional.

X-Session-IDuuid

Obrigatório para visitante: sem token e sem este cabeçalho a resposta é sempre {}.

Corpo da requisição

page_contextobject

Onde o cliente está, no mesmo formato de Conversar (kind, id, label, url, extra).

seen_kindsstring[]

Tipos de aviso que o cliente já viu, para não repetir.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/proactive" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "page_context": {
    "kind": "cart"
  },
  "seen_kinds": [
    "browse"
  ]
}'

Resposta

200Há um aviso

json

{
  "nudge": {
    "kind": "free-shipping",
    "text": "Faltam R$ 40,00 para você ganhar frete grátis.",
    "cta": { "label": "Ver produtos", "href": "/produtos" }
  }
}

200Nada a dizer

json

{}

Campos da resposta

nudgeobject

Ausente quando não há aviso (o corpo é {}).

nudge.kindstring

Tipo do aviso: product-b2b, product, credit, free-shipping, abandoned-cart, price-drop ou browse.

nudge.textstring

Texto para o balão.

nudge.ctaobject

Botão de ação opcional.

nudge.cta.labelstring

Rótulo do botão.

nudge.cta.hrefstring

Caminho de destino na loja.

Erros

Status	Quando	Corpo
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`

Corpo inválido não gera erro: a rota o trata como vazio e responde 200.

Busca por foto

POST/api/v1/storefront/intelligence/snapAutenticada

Busca produtos a partir de uma foto

Recebe uma foto (e/ou uma dica em texto) e devolve a descrição do que aparece nela e os produtos da loja que mais combinam, em até 8 resultados.

Corpo da requisição

imagefile

Foto, enviada como multipart/form-data. Até 12 MB.

hintstring

Termo de busca. Usado quando não há foto ou quando a foto não pôde ser descrita. Pelo menos um entre image e hint é obrigatório.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/snap" \
  -F "image=@tenis.jpg" \
  -F "hint=tênis branco"

Resposta

200Produtos parecidos

json

{
  "description": "tênis esportivo branco com solado de borracha",
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Tênis Run Branco",
      "slug": "tenis-run-branco",
      "price": 29990,
      "rating": 4.6,
      "list_price": 34990,
      "image": "https://cdn.example.com/tenis-run-branco.jpg"
    }
  ]
}

Campos da resposta

descriptionstring

O que a foto mostra, em texto. Se a foto não pôde ser descrita, repete hint.

productsobject[]

Até 8 produtos da loja que combinam com a descrição, do mais ao menos parecido. Cada produto traz id, name, slug, price (centavos), rating (média de avaliações) e, quando existem, list_price (preço "de", em centavos, só se maior que price) e image.

Erros

Status	Quando	Corpo
400	Corpo que não é `multipart/form-data` (ou maior que 12 MB).	`{"error":"imagem inválida"}`
400	Sem `image` e sem `hint` (ou foto que não pôde ser descrita e sem `hint`).	`{"error":"envie uma foto (campo 'image') ou um termo ('hint')"}`
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
503	Busca por foto indisponível na plataforma.	`{"error":"busca por foto indisponível"}`

Veja também

API atual/Referência completa/Venddor Intelligence na vitrine

Aviso proativo e foto

Obtém o aviso contextual da página e busca produtos a partir de uma foto.

Duas rotas de apoio à conversa: um aviso que o assistente mostra sozinho enquanto o cliente navega, e a busca de produtos a partir de uma foto.

Aviso proativo

POST/api/v1/storefront/intelligence/proactiveAutenticada

Aviso contextual para a página atual

Pergunta ao servidor se há algo útil a dizer ao cliente na página atual. Chame em cada navegação; a resposta é barata e rápida (o servidor desiste em 2 segundos e devolve {}).

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado. Opcional.

X-Session-IDuuid

Obrigatório para visitante: sem token e sem este cabeçalho a resposta é sempre {}.

Corpo da requisição

page_contextobject

Onde o cliente está, no mesmo formato de Conversar (kind, id, label, url, extra).

seen_kindsstring[]

Tipos de aviso que o cliente já viu, para não repetir.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/proactive" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "page_context": {
    "kind": "cart"
  },
  "seen_kinds": [
    "browse"
  ]
}'

Resposta

200Há um aviso

json

{
  "nudge": {
    "kind": "free-shipping",
    "text": "Faltam R$ 40,00 para você ganhar frete grátis.",
    "cta": { "label": "Ver produtos", "href": "/produtos" }
  }
}

200Nada a dizer

json

{}

Campos da resposta

nudgeobject

Ausente quando não há aviso (o corpo é {}).

nudge.kindstring

Tipo do aviso: product-b2b, product, credit, free-shipping, abandoned-cart, price-drop ou browse.

nudge.textstring

Texto para o balão.

nudge.ctaobject

Botão de ação opcional.

nudge.cta.labelstring

Rótulo do botão.

nudge.cta.hrefstring

Caminho de destino na loja.

Erros

Status	Quando	Corpo
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`

Corpo inválido não gera erro: a rota o trata como vazio e responde 200.

Busca por foto

POST/api/v1/storefront/intelligence/snapAutenticada

Busca produtos a partir de uma foto

Recebe uma foto (e/ou uma dica em texto) e devolve a descrição do que aparece nela e os produtos da loja que mais combinam, em até 8 resultados.

Corpo da requisição

imagefile

Foto, enviada como multipart/form-data. Até 12 MB.

hintstring

Termo de busca. Usado quando não há foto ou quando a foto não pôde ser descrita. Pelo menos um entre image e hint é obrigatório.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/snap" \
  -F "image=@tenis.jpg" \
  -F "hint=tênis branco"

Resposta

200Produtos parecidos

json

{
  "description": "tênis esportivo branco com solado de borracha",
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Tênis Run Branco",
      "slug": "tenis-run-branco",
      "price": 29990,
      "rating": 4.6,
      "list_price": 34990,
      "image": "https://cdn.example.com/tenis-run-branco.jpg"
    }
  ]
}

Campos da resposta

descriptionstring

O que a foto mostra, em texto. Se a foto não pôde ser descrita, repete hint.

productsobject[]

Erros

Status	Quando	Corpo
400	Corpo que não é `multipart/form-data` (ou maior que 12 MB).	`{"error":"imagem inválida"}`
400	Sem `image` e sem `hint` (ou foto que não pôde ser descrita e sem `hint`).	`{"error":"envie uma foto (campo 'image') ou um termo ('hint')"}`
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
503	Busca por foto indisponível na plataforma.	`{"error":"busca por foto indisponível"}`