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

Conversar com o assistente

Envia uma mensagem do cliente e lê a resposta do assistente em fluxo SSE.

Esta é a rota principal do assistente. Cada chamada é um turno da conversa: o cliente escreve, o assistente pensa, consulta o catálogo e a conta do cliente e responde. Quando precisa, ele executa ações de compra (adicionar ao carrinho, aplicar cupom) e mostra cartões para o cliente escolher.

POST/api/v1/storefront/intelligence/assistAutenticada

Envia uma mensagem ao assistente

Envia uma mensagem do cliente e recebe a resposta do assistente. O corpo da resposta é um fluxo text/event-stream quando o cliente HTTP suporta streaming; caso contrário vem um único JSON com a resposta final.

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado. Opcional.

X-Session-IDuuid

Identifica o visitante sem conta. Ignorado quando há token.

Corpo da requisição

promptstringobrigatório

A mensagem do cliente. Obrigatória; só espaços conta como vazia.

session_iduuid

Conversa a continuar. Omita na primeira mensagem. Um id inexistente ou de outro cliente é descartado e uma conversa nova começa.

page_contextobject

Onde o cliente está, para o assistente responder sobre o que ele vê.

page_context.kindstring

Tipo da página: product, cart, checkout, category, account, order, quote, wishlist, home.

page_context.idstring

Id da entidade (produto, pedido) ou slug da categoria.

page_context.labelstring

Nome legível (nome do produto, da categoria).

page_context.urlstring

Caminho da página, sem query string (evite dados pessoais).

page_context.extraobject

Dados do tipo de página: quantidade, variação, itens e subtotal do carrinho, etapa.

imagestring

Foto anexada, como data URL (data:image/jpeg;base64,...). Uma lista escrita à mão ou a foto de um pedido vira itens para o carrinho.

localestring

Força o idioma da resposta (pt-BR, en, es).

opening_nudgeobject

Aviso proativo que o seu front-end mostrou como primeira fala do assistente. Mande-o na primeira mensagem para o assistente lembrar do assunto.

opening_nudge.kindstring

O kind do aviso (veja Aviso proativo e foto).

opening_nudge.textstring

O texto do aviso.

Exemplo de requisição

bash

curl -N -X POST "$BASE_URL/api/v1/storefront/intelligence/assist" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: $SESSION_ID" \
  -d '{"prompt": "Tem parecido mais barato?", "page_context": {"kind": "product", "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"}}'

Resposta

A resposta é uma sequência de eventos SSE. Cada evento tem uma linha event: e uma linha data: com JSON, separados por linha em branco.

200Fluxo de eventos

http

event: tool
data: {"name":"search products","id":"call_1"}

event: token
data: {"delta":"Encontrei "}

event: token
data: {"delta":"duas opções mais baratas."}

event: done
data: {"session_id":"11111111-1111-4111-8111-111111111111","message_id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","user_message_id":"6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d","reply":{"content":"Encontrei duas opções mais baratas. ..."}}

Event	Quando	`data`
`tool`	O assistente começou a usar uma ferramenta (mostre "consultando...").	`name` (rótulo legível), `id`
`token`	Um pedaço do texto da resposta.	`delta`
`done`	Fim do turno. Traz a resposta completa e definitiva.	`session_id`, `message_id`, `user_message_id`, `reply.content`
`error`	O turno falhou. O fluxo termina.	`message` (texto para o cliente)

Sem suporte a streaming no cliente, a resposta é um único JSON com 200:

200Resposta única

json

{
  "session_id": "11111111-1111-4111-8111-111111111111",
  "message_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "user_message_id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
  "reply": { "content": "Encontrei duas opções mais baratas. ..." }
}

Campos da resposta

session_iduuid

Conversa. Guarde e mande nas próximas mensagens.

message_iduuid

Id da mensagem do assistente.

user_message_iduuid

Id da mensagem do cliente. Use-o em Histórico e edição para editar a mensagem.

reply.contentstring

Texto da resposta, em Markdown. Pode conter blocos de código com linguagem sf:choice: são cartões de escolha. O widget oficial os desenha; um front-end próprio deve desenhá-los ou ocultá-los (veja Cartões de escolha).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON (ou maior que 24 MB).	`{"error":"corpo inválido"}`
400	`prompt` vazio.	`{"error":"prompt obrigatório"}`
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
500	Não foi possível abrir a conversa.	`{"error":"não foi possível iniciar a conversa"}`
502	Falha ao gerar a resposta (só no modo sem streaming; com streaming vira o evento `error`).	`{"error":"..."}`
503	Assistente indisponível na plataforma.	`{"error":"assistente indisponível"}`

As mensagens de erro desta rota saem em português, como o servidor as devolve.

Veja também

Conversar com o assistente

Envia uma mensagem do cliente e lê a resposta do assistente em fluxo SSE.

POST/api/v1/storefront/intelligence/assistAutenticada

Envia uma mensagem ao assistente

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado. Opcional.

X-Session-IDuuid

Identifica o visitante sem conta. Ignorado quando há token.

Corpo da requisição

promptstringobrigatório

A mensagem do cliente. Obrigatória; só espaços conta como vazia.

session_iduuid

Conversa a continuar. Omita na primeira mensagem. Um id inexistente ou de outro cliente é descartado e uma conversa nova começa.

page_contextobject

Onde o cliente está, para o assistente responder sobre o que ele vê.

page_context.kindstring

Tipo da página: product, cart, checkout, category, account, order, quote, wishlist, home.

page_context.idstring

Id da entidade (produto, pedido) ou slug da categoria.

page_context.labelstring

Nome legível (nome do produto, da categoria).

page_context.urlstring

Caminho da página, sem query string (evite dados pessoais).

page_context.extraobject

Dados do tipo de página: quantidade, variação, itens e subtotal do carrinho, etapa.

imagestring

Foto anexada, como data URL (data:image/jpeg;base64,...). Uma lista escrita à mão ou a foto de um pedido vira itens para o carrinho.

localestring

Força o idioma da resposta (pt-BR, en, es).

opening_nudgeobject

Aviso proativo que o seu front-end mostrou como primeira fala do assistente. Mande-o na primeira mensagem para o assistente lembrar do assunto.

opening_nudge.kindstring

O kind do aviso (veja Aviso proativo e foto).

opening_nudge.textstring

O texto do aviso.

Exemplo de requisição

bash

curl -N -X POST "$BASE_URL/api/v1/storefront/intelligence/assist" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: $SESSION_ID" \
  -d '{"prompt": "Tem parecido mais barato?", "page_context": {"kind": "product", "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"}}'

Resposta

A resposta é uma sequência de eventos SSE. Cada evento tem uma linha event: e uma linha data: com JSON, separados por linha em branco.

200Fluxo de eventos

http

event: tool
data: {"name":"search products","id":"call_1"}

event: token
data: {"delta":"Encontrei "}

event: token
data: {"delta":"duas opções mais baratas."}

event: done
data: {"session_id":"11111111-1111-4111-8111-111111111111","message_id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","user_message_id":"6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d","reply":{"content":"Encontrei duas opções mais baratas. ..."}}

Event	Quando	`data`
`tool`	O assistente começou a usar uma ferramenta (mostre "consultando...").	`name` (rótulo legível), `id`
`token`	Um pedaço do texto da resposta.	`delta`
`done`	Fim do turno. Traz a resposta completa e definitiva.	`session_id`, `message_id`, `user_message_id`, `reply.content`
`error`	O turno falhou. O fluxo termina.	`message` (texto para o cliente)

Sem suporte a streaming no cliente, a resposta é um único JSON com 200:

200Resposta única

json

{
  "session_id": "11111111-1111-4111-8111-111111111111",
  "message_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "user_message_id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
  "reply": { "content": "Encontrei duas opções mais baratas. ..." }
}

Campos da resposta

session_iduuid

Conversa. Guarde e mande nas próximas mensagens.

message_iduuid

Id da mensagem do assistente.

user_message_iduuid

Id da mensagem do cliente. Use-o em Histórico e edição para editar a mensagem.

reply.contentstring

Erros

Status	Quando	Corpo
400	Corpo que não é JSON (ou maior que 24 MB).	`{"error":"corpo inválido"}`
400	`prompt` vazio.	`{"error":"prompt obrigatório"}`
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
500	Não foi possível abrir a conversa.	`{"error":"não foi possível iniciar a conversa"}`
502	Falha ao gerar a resposta (só no modo sem streaming; com streaming vira o evento `error`).	`{"error":"..."}`
503	Assistente indisponível na plataforma.	`{"error":"assistente indisponível"}`

As mensagens de erro desta rota saem em português, como o servidor as devolve.