VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dashboards

Insights da Venddor Intelligence

Lê observações automáticas sobre a loja, fixa uma delas como card e gera um parágrafo explicativo para um card.

A Venddor Intelligence (VI) acompanha a loja e escreve insights: "a receita caiu 85% em 30 dias", "2 pedidos estão atrasados". Cada insight vem com uma frase explicativa, números de apoio (facts) e, quando faz sentido, a especificação de um card que mostra o dado (spec). Estas rotas permitem ler os insights, fixar um deles numa aba como card comum e pedir um parágrafo de análise para qualquer card existente.

Ler insights

GET/api/v1/admin/dashboards/insightsAdmin

Ler os insights da loja

Parâmetros de consulta

langstring
Idioma dos textos gerados (pt-BR, en...). Sem isso, usa Accept-Language.
refreshbooleanpadrão: false
true ignora o cache e recalcula.

Exemplo de requisição (ler)

bash
curl "$BASE_URL/api/v1/admin/dashboards/insights?lang=pt-BR" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler)

200Insights
json
{
  "available": true,
  "insights": [
    {
      "key": "signal:late_orders",
      "source": "signal",
      "severity": "warning",
      "title_key": "admin.dashboards.vi.signal.lateOrders.title",
      "body_key": "admin.dashboards.vi.signal.lateOrders.body",
      "body_params": { "count": "2" },
      "narrative": "Foram identificados 2 pedidos com atraso na entrega.",
      "narrative_source": "llm",
      "icon": "alerta",
      "facts": [ { "label_key": "admin.dashboards.vi.fact.lateOrders", "value": "2", "raw": 2, "unit": "count", "tone": "down" } ],
      "cta_url": "/admin/orders",
      "pinnable": true,
      "spec": { "spec_version": 1, "kind": "query", "title": "Pedidos atrasados", "viz": { "type": "kpi", "snippet_id": "vi-late-orders" }, "query": { "entity": "orders" } },
      "width": 1,
      "height": 1,
      "generated_at": "2026-10-11T21:10:02Z"
    }
  ],
  "generated_at": "2026-10-11T21:10:02Z",
  "cached": false,
  "narrator_ready": true
}

Campos da resposta

availableboolean
false quando não há como gerar insights; veja reason.
reasonstring
vi_not_configured ou no_data. Só quando available é false.
insightsarray
Os insights, já ordenados. [] se não houver.
insights[].keystring
Identificador estável do insight, usado em Fixar.
insights[].sourcestring
signalpulseproactive
Origem do insight.
insights[].severitystring
infowarningopportunity
Gravidade.
insights[].title_keystring
Chave de tradução do título, com title_params. Alguns insights trazem title já em texto.
insights[].body_keystring
Chave de tradução do corpo, com body_params. Alguns trazem body em texto.
insights[].narrativestring
Frase explicativa pronta.
insights[].narrative_sourcestring
llmtemplate
Como narrative foi produzida: texto gerado pela VI ou modelo de texto fixo.
insights[].iconstring
Ícone.
insights[].factsarray
Números de apoio: label_key, value (formatado), raw (número), unit (cents, percent, count...) e tone (up/down).
insights[].cta_urlstring
Tela do painel para agir sobre o insight.
insights[].pinnableboolean
Se pode ser fixado como card.
insights[].specobject
Especificação do card que mostra o dado.
insights[].widthinteger
Largura sugerida do card, 1 a 3.
insights[].heightinteger
Altura sugerida, 1 a 3.
insights[].generated_atstring
Quando foi gerado.
generated_atstring
Quando a lista foi gerada.
cachedboolean
true se veio do cache.
narrator_readyboolean
false quando a geração de texto pela VI está indisponível; as frases vêm de modelos fixos.

Erros (ler)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Criar a aba de insights

POST/api/v1/admin/dashboards/insights/tabAdmin

Garantir a aba de insights

Corpo da requisição

namestring
Nome da aba, se ela ainda não existir. Sem isso, usa o nome padrão.

Exemplo de requisição (aba)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/insights/tab" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (aba)

200Aba pronta
json
{
  "dashboard": {
    "id": "42475577-6012-42d8-bd1e-d60375205f42",
    "slug": "vi-insights",
    "name": "Insights da VI",
    "panel": "A",
    "visibility": "G",
    "kind": "vi_insights"
  },
  "kind": "vi_insights"
}

Campos da resposta

dashboardobject
A aba de insights, com os campos de Abas.
kindstring
Sempre vi_insights.

Erros (aba)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
503O recurso de insights não está configurado neste ambiente.{"error":"insights engine not configured"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Fixar um insight

POST/api/v1/admin/dashboards/insights/pinAdmin

Fixar um insight como card

Corpo da requisição

keystringobrigatório
key do insight (de Ler insights).
dashboard_iduuid
Aba que receberá o card. Sem isso, usa a aba padrão (ou a primeira aba editável). Não pode ser a aba de insights.
widthinteger
Largura, 1 a 3. Padrão: a do insight.
heightinteger
Altura, 1 a 3. Padrão: a do insight.
orderinteger
Ordem. Sem isso, vai para o fim da aba.

Exemplo de requisição (fixar)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/insights/pin" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "signal:late_orders", "width": 1, "height": 1}'

Resposta (fixar)

201Card criado
json
{
  "card": {
    "id": "dd3470e6-dc16-4b41-9393-23797b50d7ba",
    "dashboard_id": "8da0f9c1-b05b-4809-b07d-0b36573489e7",
    "spec": {
      "spec_version": 1,
      "kind": "query",
      "title": "Receita",
      "viz": { "type": "kpi", "snippet_id": "receita-semana", "number_format": { "style": "currency_cents" } },
      "query": {
        "entity": "orders",
        "period": { "mode": "inherit" },
        "metrics": [ { "id": "receita", "kind": "catalog", "ref": "orders.revenue", "status_scope": { "mode": "store_default", "include": ["Paid", "shipped", "delivered"] } } ]
      }
    },
    "spec_version": 1,
    "kind": "Q",
    "title": "Receita",
    "grid_row": 0,
    "grid_col": 0,
    "width": 1,
    "height": 1,
    "order": 0,
    "status": "A",
    "source": "M",
    "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "created_at": "2026-10-11T21:10:41.552Z",
    "updated_at": "2026-10-11T21:10:41.552Z"
  },
  "dashboard_id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a"
}

Campos da resposta

cardobject
O card criado, com os campos de Cards.
dashboard_iduuid
A aba que recebeu o card.

Erros (fixar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
404Insight não encontrado (a chave muda com o tempo), ou aba inexistente.{"error":"insight not found"}
422key vazia, insight não fixável, aba de insights como destino, nenhuma aba editável, ou falha ao criar o card.{"error":"insight is not pinnable"}
503O recurso de insights não está configurado neste ambiente.{"error":"insights engine not configured"}

Narrativa de um card

POST/api/v1/admin/dashboards/cards/{cardId}/narrativeAdmin

Gerar um parágrafo de análise de um card

Parâmetros de caminho

cardIduuidobrigatório
Id do card (UUID).

Corpo da requisição

periodobject

Período a aplicar aos cards com período inherit. Mesmo formato de period na especificação. Cards com período próprio ignoram este.

modestringobrigatório
inheritpresetfixedrelative
Como o período é definido.
presetstring
todayyesterdaylast7last30last90thisMonthlastMonththisQuarterthisYearlastYear
Obrigatório com mode=preset.
fromstring
Com mode=fixed: primeiro dia, YYYY-MM-DD.
tostring
Com mode=fixed: último dia, YYYY-MM-DD.
last_n_daysinteger
Com mode=relative: quantos dias para trás, até 1095.
fieldstring
Campo de data da entidade a usar como referência (entidade.campo). Padrão: o campo de data principal da entidade.
refreshbooleanpadrão: false
true ignora o cache.
langstring
Idioma do texto.

Exemplo de requisição (narrativa)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/cards/f4368e4f-e696-4a57-9ca8-a026ba5ad694/narrative" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lang": "pt-BR"}'

Resposta (narrativa)

200Narrativa
json
{
  "text": "A maior parte dos pedidos está entregue; 145 seguem pendentes.",
  "source": "llm",
  "dataset_hash": "909130ef2a69eb9d303cbad672e6197dcafab6653d010c0223462d25a0dbd00a",
  "cached": false,
  "generated_at": "2026-10-11T21:20:00Z",
  "narrator_ready": true
}
200O card falhou ao executar
json
{
  "error": { "code": "no_dataset", "message_key": "admin.dashboards.err.no_dataset" }
}

Campos da resposta

textstring
O parágrafo.
sourcestring
llmtemplate
Como foi produzido: texto gerado pela VI ou modelo fixo.
dataset_hashstring
Identificador dos dados que originaram o texto.
cachedboolean
Se veio do cache.
generated_atstring
Quando foi gerado.
narrator_readyboolean
Se a geração de texto está disponível.
errorobject
No lugar dos campos acima, com HTTP 200, quando o card não pôde ser executado: code e message_key.

Erros (narrativa)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
404O card não existe ou a aba dele não é sua.{"error":"card not found"}
422A especificação gravada do card é inválida.{"error":"invalid stored spec"}
503O recurso de insights não está configurado neste ambiente.{"error":"insights engine not configured"}
500Falha inesperada no servidor.{"error":"failed to ..."}
As frases dependem de um serviço externo

Se a geração de texto da VI estiver indisponível, os insights continuam saindo, com narrator_ready: false e frases de modelos fixos. Sem a VI configurada na loja, GET devolve available: false com reason: vi_not_configured (e as demais rotas, 503).

Veja também

  • Abas
  • Cards
  • Executar a aba
Anterior
Assinaturas: executar e histórico
Próxima
Registro de atividades
Nesta página
  • Ler insights
  • Exemplo de requisição (ler)
  • Resposta (ler)
  • Erros (ler)
  • Criar a aba de insights
  • Exemplo de requisição (aba)
  • Resposta (aba)
  • Erros (aba)
  • Fixar um insight
  • Exemplo de requisição (fixar)
  • Resposta (fixar)
  • Erros (fixar)
  • Narrativa de um card
  • Exemplo de requisição (narrativa)
  • Resposta (narrativa)
  • Erros (narrativa)
  • Veja também