Venddor Intelligence na vitrine

Venddor Intelligence é o assistente de compras embutido na vitrine. O cliente pergunta em linguagem natural ("tem algo parecido mais barato?", "cadê meu pedido?"), fala ou manda uma foto, e o assistente responde e executa ações de compra em nome dele. Estas rotas são o contrato que o widget oficial usa; elas permitem que um front-end próprio ofereça a mesma experiência.

Como funciona

1. Ver se o assistente está ligado

   Chame Configuração. Ela devolve enabled, as capacidades (flags), o nome da marca do assistente, a saudação e sugestões de perguntas no idioma do cliente.

2. Conversar

   Envie cada mensagem em Conversar. Na primeira, não mande session_id; guarde o que vier no evento done e mande nas seguintes.

3. Responder cartões de escolha

   Quando a resposta traz um cartão (por exemplo, "qual destes produtos?"), o cliente clica e você envia a escolha por Cartões de escolha.

4. Restaurar após recarregar

   Com o session_id guardado, Histórico e edição reconstrói a conversa.

Conceitos-chave

Quem é o cliente

Com token, o assistente sabe quem é o cliente (pedidos, endereços, preços de contrato). Sem token, o visitante é identificado só pelo X-Session-ID. Uma conversa de cliente logado só pode ser lida pelo próprio cliente; a de visitante, por quem tem o session_id. Um session_id que não é seu responde 404, o mesmo de um que não existe.

Idioma

O idioma vem, nesta ordem, do idioma gravado na conta do cliente, do cookie venddor_language e do cabeçalho Accept-Language (pt-BR, en ou es). Cartões e textos fixos saem nesse idioma.

Custo e limites

Cada mensagem à conversa consome o plano de inteligência da loja. Não chame a rota em laço nem a cada tecla digitada. As rotas de configuração e de aviso proativo são leves.

Endpoints

Erros comuns

1. Ler a resposta de assist como JSON. Com Accept de fluxo, ela é text/event-stream. Leia evento por evento (veja Conversar).
2. Mandar um session_id antigo ou de outro cliente. Em assist, ele é ignorado e uma conversa nova começa (confira o session_id do evento done). Nas demais rotas responde 404.
3. Mostrar o botão sem checar enabled. A conversa não verifica essa chave; um assistente desligado ainda pode responder se alguém chamar a rota direto.
4. Enviar áudio ou imagem grandes. Áudio até 8 MB, foto de busca até 12 MB, corpo da conversa até 24 MB.
5. Reenviar a escolha de um cartão. A segunda vez responde 409 com o resultado da primeira; a ação nunca roda duas vezes.

Próximos passos