API atual/Referência completa/Venddor Intelligence

Ferramentas e configurações

Configurações do recurso, busca de produtos por sentido e perguntas sugeridas da tela inicial.

Rotas de apoio ao assistente: as configurações que dizem quais recursos estão ligados, a busca de produtos por sentido (acha "tênis de corrida" mesmo que o cadastro diga "calçado esportivo") e as perguntas sugeridas da tela inicial.

Ler configurações

A VI tem um documento de configurações por loja, com interruptores que ligam e desligam cada recurso. O painel do seller lê esse documento para decidir quais botões desenhar (voz, exportar, briefing...). O seller só lê: não existe rota para o seller alterar; quem muda é o administrador da loja.

Chave	Sem valor gravado	Controla
`enable_chat_widget`	ligada	A conversa da VI no painel.
`enable_chat_voice_mode`	ligada	Voz no chat (Voz).
`enable_page_context_awareness`	ligada	A VI enxerga a tela aberta (Tela atual).
`enable_conversational_analytics`	ligada	Perguntas de análise sobre os números do seller.
`enable_conversational_order_creation`	ligada	Montar pedidos pela conversa (Pedido na conversa).
`enable_docx_export`	ligada	Exportar a conversa em DOCX (Anexos).
`enable_proactive_insights`	ligada	Dicas proativas (Alertas).
`enable_venddor_pulse`	ligada	Briefing diário (Briefing).
`proactive_nudges_enabled`	desligada	Alertas por tela (Alertas).

Além dos interruptores, o documento guarda parâmetros como assistant_brand_name (nome que a assistente usa para se apresentar) e venddor_pulse_display_title (rótulo do cartão do briefing). Ignore as chaves que você não conhece: o conjunto pode crescer.

GET/api/v1/vendor/intelligence/settingsSeller

Ler configurações

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configurações

json

{
  "enable_chat_voice_mode": true,
  "enable_docx_export": false,
  "realtime_voice_enabled": true
}

200Loja sem nada gravado

json

{
  "realtime_voice_enabled": true
}

Campos da resposta

realtime_voice_enabledboolean

Calculado: se a conversa por voz em tempo real está liberada para a loja pela Venddor. Somente leitura. Decide se o botão de falar aparece (Voz).

(other keys)any

As chaves gravadas, com o tipo em que foram gravadas. Chaves que nunca foram gravadas não aparecem e valem o padrão da tabela.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`

Buscar produtos

Devolve os produtos mais parecidos com o texto, com preço em centavos e um índice de semelhança. Se o recurso estiver desligado, devolve lista vazia (não um erro). Você só vê os produtos do seu seller.

GET/api/v1/vendor/intelligence/search/productsSeller

Buscar produtos por sentido

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de consulta

qstringobrigatório

Texto da busca.

limitintegerpadrão: 20

Quantidade. Padrão 20, teto 100.

vendor_iduuid

Aceito, mas ignorado: o seller do token é sempre o filtro.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/search/products?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos

json

{
  "count": 1,
  "hits": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "price": 30000,
      "status": "A",
      "similarity": 0.6,
      "source": "ilike"
    }
  ],
  "source": "ilike",
  "took_ms": 577
}

Campos da resposta

hits[].product_iduuid

Id do produto.

hits[].vendor_iduuid

Seller dono do produto (o seu).

hits[].namestring

Nome.

hits[].skustring

SKU. Pode faltar.

hits[].priceinteger

Preço em centavos.

hits[].statusstring

Estado do produto (letra, como A ativo).

hits[].similaritynumber

0 a 1; maior é mais parecido.

hits[].sourcestring

vectorilike

De onde veio o resultado.

countinteger

Quantidade de resultados.

sourcestring

Fonte do primeiro resultado, ou empty se não houve nenhum.

took_msinteger

Tempo da busca, em milissegundos.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	`q` ausente.	`{"error":"query parameter 'q' is required"}`
500	Falha na busca.	`{"error":"search failed: ..."}`

Perguntas sugeridas

A tela inicial do assistente mostra algumas perguntas sugeridas ("Quais produtos vendem melhor?") para o seller clicar em vez de digitar. A loja guarda um conjunto delas e a tela sorteia algumas a cada visita. Esta rota devolve o conjunto inteiro ativo, na ordem configurada pela loja; cada texto pode ser enviado como está ao assistente, como se o seller o tivesse digitado.

GET/api/v1/vendor/suggested-promptsSeller

Listar perguntas sugeridas

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/suggested-prompts" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Perguntas retornadas

json

{
  "prompts": [
    "Quais produtos vendem melhor?",
    "Que categorias devo focar?",
    "Quais produtos estão sem estoque?",
    "Quais pedidos estão pendentes?"
  ]
}

Campos da resposta

promptsarray

Textos das perguntas ativas, em ordem, no idioma em que foram cadastradas (em geral português). Pode ser []. Uma loja típica tem dezenas.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
500	Falha ao consultar.	`{"error":"failed to list suggested prompts","detail":"..."}`

Veja também

API atual/Referência completa/Venddor Intelligence

Ferramentas e configurações

Configurações do recurso, busca de produtos por sentido e perguntas sugeridas da tela inicial.

Ler configurações

Chave	Sem valor gravado	Controla
`enable_chat_widget`	ligada	A conversa da VI no painel.
`enable_chat_voice_mode`	ligada	Voz no chat (Voz).
`enable_page_context_awareness`	ligada	A VI enxerga a tela aberta (Tela atual).
`enable_conversational_analytics`	ligada	Perguntas de análise sobre os números do seller.
`enable_conversational_order_creation`	ligada	Montar pedidos pela conversa (Pedido na conversa).
`enable_docx_export`	ligada	Exportar a conversa em DOCX (Anexos).
`enable_proactive_insights`	ligada	Dicas proativas (Alertas).
`enable_venddor_pulse`	ligada	Briefing diário (Briefing).
`proactive_nudges_enabled`	desligada	Alertas por tela (Alertas).

GET/api/v1/vendor/intelligence/settingsSeller

Ler configurações

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configurações

json

{
  "enable_chat_voice_mode": true,
  "enable_docx_export": false,
  "realtime_voice_enabled": true
}

200Loja sem nada gravado

json

{
  "realtime_voice_enabled": true
}

Campos da resposta

realtime_voice_enabledboolean

Calculado: se a conversa por voz em tempo real está liberada para a loja pela Venddor. Somente leitura. Decide se o botão de falar aparece (Voz).

(other keys)any

As chaves gravadas, com o tipo em que foram gravadas. Chaves que nunca foram gravadas não aparecem e valem o padrão da tabela.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`

Buscar produtos

GET/api/v1/vendor/intelligence/search/productsSeller

Buscar produtos por sentido

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de consulta

qstringobrigatório

Texto da busca.

limitintegerpadrão: 20

Quantidade. Padrão 20, teto 100.

vendor_iduuid

Aceito, mas ignorado: o seller do token é sempre o filtro.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/search/products?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos

json

{
  "count": 1,
  "hits": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "price": 30000,
      "status": "A",
      "similarity": 0.6,
      "source": "ilike"
    }
  ],
  "source": "ilike",
  "took_ms": 577
}

Campos da resposta

hits[].product_iduuid

Id do produto.

hits[].vendor_iduuid

Seller dono do produto (o seu).

hits[].namestring

Nome.

hits[].skustring

SKU. Pode faltar.

hits[].priceinteger

Preço em centavos.

hits[].statusstring

Estado do produto (letra, como A ativo).

hits[].similaritynumber

0 a 1; maior é mais parecido.

hits[].sourcestring

vectorilike

De onde veio o resultado.

countinteger

Quantidade de resultados.

sourcestring

Fonte do primeiro resultado, ou empty se não houve nenhum.

took_msinteger

Tempo da busca, em milissegundos.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	`q` ausente.	`{"error":"query parameter 'q' is required"}`
500	Falha na busca.	`{"error":"search failed: ..."}`

Perguntas sugeridas

GET/api/v1/vendor/suggested-promptsSeller

Listar perguntas sugeridas

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/suggested-prompts" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Perguntas retornadas

json

{
  "prompts": [
    "Quais produtos vendem melhor?",
    "Que categorias devo focar?",
    "Quais produtos estão sem estoque?",
    "Quais pedidos estão pendentes?"
  ]
}

Campos da resposta

promptsarray

Textos das perguntas ativas, em ordem, no idioma em que foram cadastradas (em geral português). Pode ser []. Uma loja típica tem dezenas.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
500	Falha ao consultar.	`{"error":"failed to list suggested prompts","detail":"..."}`