Analítico

Um dataset do BI, em JSON ou CSV, com a governança do painel

GET/api/v1/analitico/{dataset}

Executa um conjunto de dados do BI com a mesma governança do painel: regras de linha do dono da chave antes de qualquer filtro, colunas de valor só com Ver Valores, teto de linhas declarado. Sai em JSON ou CSV (Power BI e Metabase leem direto).

Executa o dataset curado pelo mesmo motor do painel: as regras de LINHA do grupo do dono da chave entram antes de qualquer filtro; colunas de valor só com Ver Valores; teto de 1000 linhas declarado em `truncado`. Cada consulta fica na trilha de auditoria.

Com formato=csv a resposta é text/csv (com BOM, vírgula e aspas dobradas), não JSON.

Escopo da chave

Qualquer chave da conta (leitura basta).

Parâmetros

Nome	Onde	Tipo	Obrigatório	Descrição
`Authorization`	header	string	sim	Bearer seguido da chave. Alternativa: cabeçalho X-API-Key.
`dataset`	path	string	sim	Chave do dataset (ver /analitico)
`formato`	query	string	não	json (padrão) ou csv — CSV com BOM, vírgula, aspas dobradas; Power BI e Metabase leem direto
`colunas`	query	string	não	Chaves ou rótulos separados por vírgula; vazio = as colunas do dataset. Campo criado pela empresa (campoDaEmpresa=true no catálogo, chave cc_*) só vem pedido pelo nome; sensível só com Ver Valores
`filtros`	query	string	não	campo=valor;campo2>valor2;campo3~contem (também <, >=, <=). Só colunas filtráveis; coluna sensível só com Ver Valores; o resto volta em `ignorados`
`agrupamento`	query	string	não	Coluna de texto ou data para agrupar (uma linha por valor, métricas agregadas)
`funcao`	query	string	não	Com agrupamento: SOMA (padrão) \| MEDIA \| CONTAGEM \| MAIOR \| MENOR \| MEDIANA
`fonte`	query	string	não	snapshot = o retrato diário (instantâneo, com atualizadoEm; só sem regra de linha, filtro e agrupamento — senão a API responde ao vivo e diz em `fonte`)
`atualizar`	query	string	não	1 com fonte=snapshot: regrava o retrato antes de responder
`pagina`	query	integer	não	Página (começa em 1) sobre o conjunto consultado; a resposta traz pagina, tamanho, totalNaConsulta e temMais
`tamanho`	query	integer	não	Linhas por página, 1..1000 (padrão = o teto)

Campos da resposta

Nome	Tipo	Descrição
`dataset`	string	O conjunto de dados consultado.
`colunas`	array	As colunas.
`data`	array	Os registros da página.
`count`	integer	Quantos registros vieram nesta página.
`pagina`	integer	Página devolvida (começa em 1).
`tamanho`	integer	Linhas por página.
`totalNaConsulta`	integer	Total de linhas da consulta inteira.
`temMais`	boolean	Há outra página.
`verValores`	boolean	true quando colunas de valor foram devolvidas.
`regrasDeLinhaAplicadas`	integer	Quantas regras de linha do dono da chave entraram.
`fonte`	string	Ao vivo ou snapshot (o retrato diário).
`atualizadoEm`	string (data e hora)	Só no modo incremental: quando o registro foi criado ou alterado pela última vez.
`agrupamento`	string	A coluna agrupada, quando houve agrupamento.
`ignorados`	string	Filtros ou colunas ignorados, com o motivo.
`truncado`	boolean	true quando o resultado passou do teto de linhas.
`aviso`	string	Aviso em texto sobre a resposta.
`mascara`	string	Aviso quando colunas sensíveis foram omitidas.

Códigos de status

HTTP	Descrição
200	JSON {dataset, colunas, data, count, truncado, regrasDeLinhaAplicadas, verValores} ou text/csv
404	dataset não encontrado

Mensagens de erro

HTTP	Mensagem (campo erro)	Quando acontece
401	`chave de API ausente ou inválida`	Sem cabeçalho de chave, chave revogada ou digitada errada.
401	`chave sem empresa vinculada`	A chave existe mas não está ligada a uma conta. Gere outra em Configurações › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	A chamada veio para a conta de demonstração: lá a API pública fica desligada.
403	`identidade da chave de API irregular`	A conta recusa chaves com identidade irregular (pessoa desligada ou chave sem dono). O corpo traz motivo e comoResolver.
429	`limite de requisições excedido (120/min)`	Passou do limite por minuto da chave. Espere o Retry-After.
400	`informe o dataset`	Faltou a chave do conjunto de dados no endereço.
404	`dataset não encontrado: {dataset}`	O conjunto de dados não existe ou não está disponível para a conta. Consulte o catálogo.
500	`a consulta não rodou`	A consulta analítica falhou. Tente menos colunas ou outro filtro.

Exemplo de chamada

cURL

curl "https://tenka.app.br/api/v1/analitico/tickets?formato=json&pagina=1" \
  -H "Authorization: Bearer $TENKA_API_KEY"

JavaScript

const response = await fetch("https://tenka.app.br/api/v1/analitico/tickets?formato=json&pagina=1", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + TENKA_API_KEY
  }
});
const data = await response.json();
if (!response.ok || data.erro) throw new Error(response.status + " " + data.erro);
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://tenka.app.br/api/v1/analitico/tickets?formato=json&pagina=1",
    headers={
        "Authorization": f"Bearer {os.environ['TENKA_API_KEY']}",
    },
    timeout=30,
)
data = response.json()
if not response.ok or "erro" in data:
    raise RuntimeError(f"{response.status_code} {data.get('erro')}")
print(data)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://tenka.app.br/api/v1/analitico/tickets?formato=json&pagina=1"))
    .header("Authorization", "Bearer " + System.getenv("TENKA_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

using System.Net.Http.Headers;
using System.Text;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TENKA_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Get, "https://tenka.app.br/api/v1/analitico/tickets?formato=json&pagina=1");
var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

PHP

<?php
$ch = curl_init("https://tenka.app.br/api/v1/analitico/tickets?formato=json&pagina=1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TENKA_API_KEY"),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($body, true);
echo $status . " " . $body;

Node (SDK)

// SDK gerado do contrato — baixe em https://tenka.app.br/api/v1/sdk/tenka.js
import { Tenka } from "./tenka.js";

const tenka = new Tenka(process.env.TENKA_API_KEY, "https://tenka.app.br/api/v1");
const data = await tenka.getAnaliticoDataset("tickets", { formato: "json", pagina: 1 });
console.log(data);

Exemplo de resposta

200 · application/json

{
  "dataset": "tickets",
  "colunas": [
    {
      "chave": "titulo",
      "rotulo": "Título",
      "tipo": "TEXTO"
    }
  ],
  "data": [
    {
      "titulo": "Erro ao emitir a nota"
    }
  ],
  "count": 1,
  "pagina": 1,
  "tamanho": 1000,
  "totalNaConsulta": 1,
  "temMais": false,
  "verValores": false,
  "regrasDeLinhaAplicadas": 0,
  "fonte": "ao-vivo",
  "truncado": false
}

Gerado do contrato OpenAPI v1.2.0, o mesmo que o openapi.json publica. openapi.json