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

Insights

Lê os insights da Venddor Intelligence para o seller, cria a aba de insights, fixa um insight como card e pede o texto explicativo de um card.

A Venddor Intelligence observa a operação do seller e aponta o que merece atenção, por exemplo pedidos atrasados ou estoque baixo. Cada aviso é um insight: um número com um texto curto. Insights não são guardados: são calculados a cada leitura (com cache curto). Para guardar um, fixe-o (pin) e ele vira um card normal.

Listar insights

GET/api/v1/vendor/dashboards/insightsSeller

Listar insights

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

langstring
Idioma do texto. Omitido, vale o Accept-Language.
refreshbooleanpadrão: false
true ignora o cache e recalcula.

Exemplo de requisição

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

Resposta

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 registrados 2 pedidos com atraso na entrega. Revise a logística para cumprir os prazos.",
      "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",
          "period": {
            "mode": "relative",
            "last_n_days": 90
          },
          "metrics": [
            {
              "id": "atrasados",
              "kind": "agg",
              "agg": "count",
              "field": "orders.id"
            }
          ],
          "filter": {
            "field": "orders.promised_delivery_at",
            "cmp": "overdue"
          }
        }
      },
      "width": 1,
      "height": 1,
      "generated_at": "2026-10-11T21:04:42.204782955Z"
    }
  ],
  "generated_at": "2026-10-11T21:04:42.204782955Z",
  "cached": false,
  "narrator_ready": true
}

Campos da resposta

availableboolean
false quando não há insights a mostrar; veja reason.
reasonstring
Quando available é false: vi_not_configured ou no_data.
insightsobject[]

Os avisos.

insights[].keystring
Identificador do insight (por exemplo signal:late_orders). Use-o em pin.
insights[].sourcestring
signalpulseproactive
Origem.
insights[].severitystring
infowarningopportunity
Gravidade.
insights[].title_keystring
Chave de tradução do título, nos avisos do tipo signal. Nos demais vêm title e body já escritos.
insights[].body_keystring
Chave de tradução do corpo, com os valores em body_params.
insights[].narrativestring
Parágrafo explicativo em texto pronto.
insights[].narrative_sourcestring
llm se o parágrafo foi escrito pela Venddor Intelligence, template se é um texto padrão.
insights[].iconstring
Ícone.
insights[].factsobject[]
Números de apoio: label_key, value (formatado), raw, unit (cents, count, percent, text) e tone.
insights[].cta_urlstring
Tela do painel onde agir.
insights[].pinnableboolean
Se pode virar card.
insights[].specobject
A spec do card que o insight geraria.
insights[].widthinteger
Largura sugerida.
insights[].heightinteger
Altura sugerida.
insights[].generated_atstring
Quando foi calculado.
generated_atstring
Quando a lista foi gerada.
cachedboolean
true se veio do cache.
narrator_readyboolean
false quando a redação automática não está disponível e os textos vêm padronizados.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
500Falha ao gerar.{"error":"failed to generate insights"}

Criar a aba de insights

Garante que o seller tenha a aba especial de insights, criando-a se faltar. Repetir a chamada é seguro.

POST/api/v1/vendor/dashboards/insights/tabSeller

Criar a aba de insights

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

namestring
Nome da aba. Omitido, usa o padrão.

Exemplo de requisição

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

Resposta

200Aba de insights
json
{
  "dashboard": {
    "id": "f35b536f-51cc-4468-b5fc-198c81bbe910",
    "slug": "vi-insights",
    "name": "Insights da VI",
    "panel": "V",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "visibility": "P",
    "is_system": false,
    "is_default": false,
    "position": 900,
    "icon": "brilho",
    "color": "",
    "default_period": {
      "mode": "preset",
      "preset": "last30"
    },
    "kind": "vi_insights"
  },
  "kind": "vi_insights"
}

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
503Motor de insights não configurado nesta loja.{"error":"insights engine not configured"}
500Falha ao criar.{"error":"failed to ensure insights tab"}

Fixar insight como card

Transforma um insight em card normal numa das abas do seller. O card guarda a mesma spec do insight, então mostra o mesmo número que o usuário viu.

POST/api/v1/vendor/dashboards/insights/pinSeller

Fixar insight como card

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

keystringobrigatório
key do insight, de Listar insights.
dashboard_iduuid
Aba de destino. Omitido, usa a primeira aba editável (nunca a de insights).
widthinteger
Largura, de 1 a 3. Omitido, a sugerida pelo insight.
heightinteger
Altura, de 1 a 3.
orderinteger
Ordem. Omitido: vai para o fim.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/insights/pin" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "signal:late_orders", "dashboard_id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8"}'

Resposta

201Card criado
json
{
  "card": {
    "id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
    "dashboard_id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8",
    "spec": {
      "spec_version": 1,
      "kind": "query",
      "title": "Receita do Mês",
      "viz": {
        "type": "kpi",
        "snippet_id": "seller-kpi-revenue-month",
        "icon": "cifrao",
        "accent": "#0044FF",
        "number_format": {
          "style": "currency_cents"
        }
      },
      "query": {
        "entity": "orders",
        "period": {
          "mode": "preset",
          "preset": "thisMonth"
        },
        "metrics": [
          {
            "id": "receita",
            "kind": "catalog",
            "ref": "orders.revenue"
          }
        ]
      }
    },
    "spec_version": 1,
    "kind": "Q",
    "title": "Pedidos atrasados",
    "grid_row": 0,
    "grid_col": 0,
    "width": 1,
    "height": 1,
    "order": 0,
    "status": "A",
    "source": "M",
    "template_slug": "fab-v-kpi-revenue-month",
    "created_at": "2026-10-11T21:04:20.327443Z",
    "updated_at": "2026-10-11T21:04:20.327443Z"
  },
  "dashboard_id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8"
}

Erros

StatusQuandoCorpo de exemplo
404Insight não encontrado (talvez já não se aplique) ou aba inexistente.{"error":"insight not found"}
422key ausente, insight que não pode virar card, aba de destino é a de insights, ou nenhuma aba editável.{"error":"insight is not pinnable"}
503Motor de insights não configurado.{"error":"insights engine not configured"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Texto explicativo de um card

Executa o card e devolve um parágrafo curto que comenta os números dele. O texto é guardado por um tempo; a mesma leitura repetida volta do cache.

POST/api/v1/vendor/dashboards/cards/{cardId}/narrativeSeller

Texto explicativo de um card

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

cardIduuidobrigatório
Id do card (UUID).

Corpo da requisição

periodobject
Período que substitui o da aba. Omitido, vale o período padrão da aba. Campos: mode (inherit, preset, fixed, relative), preset, from, to, last_n_days.
refreshboolean
true gera um texto novo.
langstring
Idioma do texto.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57/narrative" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lang": "pt-BR"}'

Resposta

200Texto
json
{
  "text": "A receita do mês soma R$ 225,00 até agora. É um começo de mês tranquilo; vale acompanhar os pedidos pendentes.",
  "source": "llm",
  "dataset_hash": "312585e798d265cb65d345c4d71a3b89fe7b2858565202c0a164d1381b3547fd",
  "cached": false,
  "generated_at": "2026-10-11T21:10:00Z",
  "narrator_ready": true
}

Campos da resposta

textstring
O parágrafo.
sourcestring
llm ou template.
dataset_hashstring
Identifica os dados comentados; o mesmo hash significa os mesmos números.
cachedboolean
Se veio do cache.
generated_atstring
Quando foi gerado.
narrator_readyboolean
Se a redação automática está disponível.
errorobject
No lugar de tudo isso, se a execução do card falhou (resposta 200): code e message_key.

Erros

StatusQuandoCorpo de exemplo
404Card inexistente ou de aba que o seller não vê.{"error":"card not found"}
422Spec guardada inválida.{"error":"invalid stored spec"}
503Motor de insights não configurado.{"error":"insights engine not configured"}
500Falha ao executar ou redigir.{"error":"failed to narrate card"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Veja também

  • Cards
  • Executar dados
Anterior
Compartilhamento
Próxima
Card por pedido em texto
Nesta página
  • Listar insights
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar a aba de insights
  • Exemplo de requisição
  • Resposta
  • Erros
  • Fixar insight como card
  • Exemplo de requisição
  • Resposta
  • Erros
  • Texto explicativo de um card
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também