API atual/Referência completa/Dashboards do seller

POSTCard por pedido em texto

Gera a spec de um card a partir de uma frase em português, já com uma pré-visualização com dados reais.

Em vez de montar a spec à mão, o seller descreve o que quer ("vendas por dia nos últimos 15 dias") e a plataforma devolve uma spec válida e executada. A spec não é salva: mostre a pré-visualização, deixe o usuário ajustar e só então use Criar card. A conversa pode continuar mandando history, para refinar o pedido.

POST/api/v1/vendor/dashboards/ai/specSeller

Gerar spec a partir de texto

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

promptstringobrigatório

O pedido em linguagem natural.

historyobject[]

Turnos anteriores para refinar o pedido, cada um com role (user ou assistant) e content.

allow_sqlbooleanpadrão: false

Permite que a geração use um card SQL. Só vale para quem tem o privilégio manage_reports; para os demais é ignorado em silêncio.

periodobject

Período usado na pré-visualização (formato de query.period).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/dashboards/ai/spec" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Receita por dia nos últimos 15 dias, em linha"}'

Resposta

200Spec gerada

json

{
  "spec": {
    "spec_version": 1,
    "kind": "query",
    "title": "Receita por dia",
    "viz": {
      "type": "line",
      "snippet_id": "receita-por-dia",
      "number_format": {
        "style": "currency_cents"
      }
    },
    "query": {
      "entity": "orders",
      "period": {
        "mode": "relative",
        "last_n_days": 15
      },
      "metrics": [
        {
          "id": "receita",
          "kind": "catalog",
          "ref": "orders.revenue"
        }
      ],
      "dimensions": [
        {
          "id": "dia",
          "field": "orders.created_at",
          "grain": "day"
        }
      ],
      "order": [
        {
          "by": "dia",
          "dir": "asc"
        }
      ],
      "limit": 100
    }
  },
  "explanation_pt": "Linha com a receita de cada dia dos últimos 15 dias.",
  "warnings": [],
  "served_by": "primary",
  "preview": {
    "columns": [
      {
        "key": "dia",
        "label": "dia",
        "type": "timestamp",
        "role": "dimension",
        "unit": "",
        "grain": "day"
      },
      {
        "key": "receita",
        "label": "receita",
        "type": "money_cents",
        "role": "metric",
        "unit": "cents"
      }
    ],
    "rows": [
      [
        "2026-10-09T00:00:00Z",
        "13587"
      ],
      [
        "2026-10-10T00:00:00Z",
        "45000"
      ]
    ],
    "meta": {
      "row_count": 2,
      "truncated": false,
      "limit": 100,
      "elapsed_ms": 1,
      "cached": false,
      "spec_hash": "cab740ceeb25ef1607e5db1c076a8dcb28667660b5927805b55da0361d0eae30"
    }
  }
}

Campos da resposta

specobject

A spec, já validada e compilável.

explanation_ptstring

Explicação curta, em português, do que foi montado.

warningsstring[]

Avisos, por exemplo "o período não tem dados".

served_bystring

Identificador interno do caminho de geração. Use só para registro; não dependa do valor.

previewobject

Dataset da pré-visualização (veja Executar dados). Pode faltar.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
403	A geração resultou num card SQL, mas `allow_sql` está desligado (ou você não tem `manage_reports`, caso em que ele é ignorado).	`{"error":"ai_sql_not_allowed","detail":"..."}`
422	Não foi possível gerar uma spec válida para o pedido.	`{"error":"ai_generation_failed","detail":"..."}`
503	Geração indisponível no momento. Use o construtor manual.	`{"error":"ai_unavailable","detail":"..."}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O 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