Venddor Intelligence do seller
A assistente de IA do painel do seller: conversas, voz, briefing diário, dicas proativas e as rotas de apoio.
A Venddor Intelligence (VI) é a assistente de IA embutida na plataforma. No painel do seller (lojista), ela responde em linguagem natural sobre os dados do seu seller: produtos, pedidos, estoque, vendas. Esta seção documenta o contrato das rotas que o painel usa para conversar com ela, para quem precisa construir uma interface própria ou automatizar um fluxo. 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
- Abra uma sessão
POST /sessionscria a conversa e devolve oid(UUID). Opcionalmente informe um título e a tela em que o seller está. - Avise em que tela o seller está
PUT /sessions/{id}/page-contextmanda a estrutura da tela (nunca os valores digitados). Assim a pergunta "o que é este campo?" faz sentido. - Envie a mensagem
POST /sessions/{id}/messagescom o texto. Comstream: truea resposta chega em eventos SSE; sem ele, em um JSON único. - Leia a resposta
O campo
contenté Markdown e pode conter blocos especiais entre cercas de código. Ignore os que não conhece.GET /sessions/{id}/messagesdevolve a conversa inteira.
Conceitos-chave
Quem pode chamar
Todas as rotas exigem o token de um usuário seller (papel vendor). Nenhum privilégio de administrador é necessário. Um token de administrador da loja ou de cliente recebe 403 com {{"error":"insufficient permissions"}}. Se o cadastro do seller ainda estiver em análise, as rotas respondem 403 com vendor_pending_review até a aprovação.
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 listas de opções (selection) são a exceção: só funcionam na própria sessão do usuário. O briefing diário e as previsões são do seller; as configurações são da loja.
Recursos ligados e desligados
Cada recurso (conversa, voz, exportação, briefing, pedido por conversa...) pode ser ligado ou desligado na loja pelo administrador. O seller lê o estado em Ferramentas e configurações. Um recurso desligado responde 403 na rota correspondente.
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.
Rotas
Todas exigem Authorization: Bearer $TOKEN de um seller.
| Método | Caminho (após /api/v1/vendor/intelligence) | Para que serve | Página |
|---|---|---|---|
| POST | /sessions | Abrir uma conversa | sessions |
| GET | /sessions | Listar as conversas de quem chama | sessions |
| GET | /sessions/search | Buscar conversas pelo texto | sessions |
| GET | /sessions/{id} | Ler uma conversa | sessions |
| PATCH | /sessions/{id} | Arquivar uma conversa | sessions |
| GET | /sessions/{id}/messages | Listar as mensagens | messages |
| POST | /sessions/{id}/messages | Enviar uma mensagem à VI | messages |
| POST | /sessions/{id}/truncate | Apagar a partir de uma mensagem | messages |
| POST | /sessions/{id}/bulk-continuation | Retomar a conversa após um lote | messages |
| PUT | /sessions/{id}/page-context | Informar a tela atual | page-context |
| POST | /sessions/{id}/snippets/{snippetId}/close | Recolher um trecho interativo | page-context |
| POST | /attachments | Converter um anexo | attachments |
| POST | /sessions/{id}/export | Exportar a conversa em DOCX | attachments |
| POST | /sessions/{id}/selection | Responder a uma lista de opções | selection |
| POST | /sessions/{id}/selection/search | Buscar dentro de uma lista | selection |
| GET | /sessions/{id}/selection/{selectionId} | Ler o estado de uma lista | selection |
| GET | /sessions/{id}/fsm | Estado do pedido em montagem | order-draft |
| POST | /sessions/{id}/order/add-item | Adicionar item ao pedido em montagem | order-draft |
| POST | /voice/transcribe | Transcrever áudio | voice |
| POST | /voice/speak | Transformar texto em áudio | voice |
| POST | /realtime/token | Credencial de voz em tempo real | voice |
| POST | /realtime/usage | Registrar o tempo de voz usado | voice |
| POST | /triggers/proactive-message | Dica proativa na conversa | proactive |
| POST | /triggers/evaluate | Alertas para a tela | proactive |
| GET | /insights/history | Histórico de sugestões | proactive |
| GET | /venddor-pulse | Listar o briefing diário | pulse |
| GET | /venddor-pulse/{id} | Ler uma edição | pulse |
| POST | /venddor-pulse/{id}/read | Marcar como lida | pulse |
| GET | /settings | Ler configurações | tools |
| GET | /search/products | Buscar produtos por sentido | tools |
| GET | /api/v1/vendor/suggested-prompts (fora do prefixo) | Perguntas sugeridas da tela inicial | tools |
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: trueou um timeout de vários minutos. - Usar um token de administrador. Estas rotas são do seller; o administrador usa o prefixo
/api/v1/admin/intelligence. - Achar que a ação proposta foi executada. Um bloco
vi:confirmna resposta é só uma proposta, e esta API não tem rota para confirmá-la. - Reenviar a mesma mensagem depois de um timeout. O servidor conclui o turno mesmo que o cliente desconecte; reenviar cria um segundo turno. Leia as mensagens antes.
- Guardar o histórico por
GET /sessionse achar que é de todos. A lista é só do usuário do token. - Mandar a estrutura da tela com valores digitados. Mande só rótulos e títulos; dados pessoais são removidos no servidor, mas não dependa disso.