Visão geral da Venddor Intelligence

A Venddor Intelligence (VI) é a assistente de IA embutida na plataforma. O administrador da loja conversa com ela em linguagem natural: ela responde perguntas sobre os dados da loja e, quando o administrador confirma, executa alterações no painel (criar um cadastro, ajustar preços, desativar promoções em lote). Esta seção documenta o contrato das rotas de conversa, para quem precisa construir uma interface própria, automatizar um fluxo ou apenas entender o que a plataforma entrega.

O que a VI faz por dentro não faz parte deste contrato. Aqui estão as entradas, as saídas, as permissões e os limites.

Como funciona

O laço da conversa

1. Abra uma sessão
   POST /sessions cria a conversa e devolve o id (UUID). Opcionalmente informe um título e a tela em que o administrador está.
2. Envie a mensagem
   POST /sessions/{id}/messages com o texto. Com stream: true a resposta chega em eventos SSE; sem ele, em um JSON único.
3. Leia a resposta
   O campo content é Markdown. Ele pode conter blocos especiais entre cercas de código, como o vi:confirm.
4. Confirme (ou recuse) a ação
   Se houver um bloco vi:confirm, mostre a descrição ao administrador e chame POST /agent-actions/confirm com o token e approved.
5. Consulte o histórico
   GET /sessions/{id}/messages devolve a conversa inteira, e GET /agent-actions lista o que foi (e o que não foi) executado.

O bloco de confirmação

Quando a VI propõe uma alteração, o content da resposta inclui um bloco assim:

{"token":"83a02587a9546e662ecac4df02acc928","description":"Desativar 12 promoções vencidas","risk":"sensitive"}

O bloco pode trazer campos extras (por exemplo, o resumo de um lote). Ignore o que não conhece.

Conceitos-chave

Privilégios

Todas as rotas exigem um token de administrador e pelo menos um dos privilégios listados na própria rota. A maioria das rotas de conversa aceita intelligence_use_chat ou manage_settings. Um administrador total passa em qualquer verificação. Sem o privilégio, a resposta é 403 com a lista privilege_required_any.

Quem enxerga o quê

GET /sessions e a busca devolvem só as conversas de quem chama. As rotas que recebem o id da sessão (ler, arquivar, listar mensagens) não conferem o dono: guarde os ids como dados sensíveis. As memórias, a base de conhecimento e as configurações são da loja inteira.

Dinheiro, datas e ids

Ids são UUIDs em texto. Datas são RFC 3339 em UTC. Valores monetários, quando aparecem em campos próprios, são inteiros em centavos (4990 = R$ 49,90). Veja Ids, dinheiro e datas.

Idioma das respostas

A VI responde no idioma da conversa. Mensagens de erro desta API chegam em inglês ou em português conforme a rota, e as que vêm em português estão assim indicadas nas páginas.

Rotas

Todas exigem Authorization: Bearer $TOKEN de um administrador.

Erros comuns

• Esperar a resposta com o timeout padrão do cliente. Um turno com várias consultas pode passar de um minuto. Use stream: true ou um timeout de vários minutos.
• Tratar a resposta como se a ação já tivesse sido feita. Enquanto houver um bloco vi:confirm sem a chamada de confirmação, nada mudou na loja.
• Reutilizar um token de confirmação. Ele é de uso único e vence em 60 minutos; depois disso a confirmação responde com status: 410 dentro de um 200.
• Esquecer que o 200 da confirmação não garante sucesso. O resultado real está no campo status do corpo.
• Guardar o histórico por GET /sessions e achar que é de todos. A lista é só do usuário do token.
• Mandar PUT /settings parcial. A rota substitui o documento inteiro (veja Configurações).

Próximos passos