Pular para o conteúdo principal

Como criar métricas agregadas para dashboards na API STILINGUE

  • Atualizado
  1. Resumo
  2. Compreendendo as limitações da requisição
  3. Como fazer a requisição principal
  4. Dicionário completo de parâmetros
  5. Estrutura visual e montagem dos componentes
  6. Exemplos de chamadas estruturadas
  7. Dicas, FAQ e Códigos de Erro

 

Resumo

A API de Dashboards devolve as métricas dos posts do seu painel já agregadas (somas, médias e contagens), por canal, sentimento, dia e outras dimensões, em um formato pronto para alimentar gráficos e dashboards.

A documentação da API é um conteúdo técnico com informações sobre como utilizar e realizar uma integração efetiva com outra API, o que permite mais autonomia na adoção da funcionalidade.

Serviços Personalizados: precisa de ajuda para montar dashboards a partir desses dados? Podemos te ajudar! Nosso time de especialistas está pronto para te atender. Entre em contato com o seu Gerente de contas STILINGUE para ter acesso a esse e vários outros serviços.

Para mais informações sobre a API STILINGUE (o que é, como funciona e como adquirir), confira o nosso guia.

Antes de começar

  • Você precisa possuir o token de autenticação do cliente.

  • O token possui 16 dígitos e atua como o identificador da conta e do painel consultados.

  • O token de autenticação desta requisição é o mesmo utilizado nas demais rotas da API STILINGUE, como Listening, Métricas Proprietárias e Smart Care.

  • O parâmetro date_range exige obrigatoriamente a configuração de hora e minuto para a consulta.

 

Compreendendo as limitações da requisição

  • Filtros de consulta: A API não possui filtros de recortes de tema, grupo, tag, sentimento, gênero ou canal. A consulta processa todo o painel dentro do período informado na requisição.

  • Período de avaliação: Configure obrigatoriamente o parâmetro date_range com os horários de início e fim da análise.

  • Conteúdo das publicações: A resposta técnica traz unicamente os valores agregados e os rótulos das dimensões, e não retorna os textos originais das publicações.

  • Dados de atendimento: Os campos focados em atendimento contam estritamente as linhas de dados, não representando os casos ou os tickets de atendimento.

  • Métodos aceitos: Utilize exclusivamente o método POST para realizar as consultas de dashboards.

  • Tempo limite de resposta: A API aguarda até 30 segundos para a resposta.

  • Tamanho do corpo da requisição: Configure requisições com peso máximo de até 16 KB.

  • Métricas por chamada: Solicite o máximo de até 10 métricas simultâneas.

  • Dimensões por chamada: Estabeleça o limite de até 3 dimensões.

  • Critérios de ordenação: Defina até 3 critérios simultâneos no campo sortFields.

 

Como fazer a requisição principal

Realize a consulta estruturando um POST com o token do cliente inserido diretamente no caminho da URL e o template do gráfico alocado no corpo da chamada.

  • Raiz da API: https://api.stilingue.com.br

  • Endpoint de acesso: /charts/posts/{TOKEN}

  • Método de envio: POST

  • Corpo (Header): JSON (Content-Type: application/json)

Parâmetros de query

  • date_range (Obrigatório): Determina o período no formato YYYYMMDDHHmm:YYYYMMDDHHmm, exigindo hora e minuto. O formato aplica a lógica do Exemplo: 202609010000:202609302359.

  • points_parser (Opcional): Determina o formato dos pontos devolvidos pela requisição. Os formatos aceitos contemplam points (versão padrão), series ou heatmap. O uso do padrão points atende plenamente à maioria das construções.

Corpo da requisição (template do gráfico)

  • metricsMetadata (Obrigatório): Requer a inserção de uma lista contendo de 1 a 10 métricas. Cada métrica registrada se transforma em uma série na resposta.

  • grouping (Obrigatório): Requer a inserção de uma lista contendo de 1 a 3 dimensões. Posicione o parâmetro postedAt em primeiro lugar ao construir uma série temporal.

  • datePortion (Opcional): Estabelece a granularidade da série temporal. Torna-se um preenchimento obrigatório quando o campo grouping recebe um dado de data.

  • sorting (Opcional): Aponta a direção lógica da ordenação, aceitando os valores asc ou desc. Utilize este parâmetro em conjunto com o campo sortFields.

  • sortFields (Opcional): Requer uma lista contendo até 3 critérios de ordenação. Utilize este parâmetro em conjunto com o campo sorting.

Estrutura interna de metricsMetadata

  • label (Obrigatório): Representa o nome da métrica. Escreva o termo utilizando letras, números e underline, iniciando obrigatoriamente por uma letra. O sistema limita o nome a até 64 caracteres, exige que o termo seja único por métrica e devolve a palavra como o campo name na resposta final.

  • operators (Obrigatório): Representa uma lista exigindo pelo menos um operador válido.

  • fields (Depende): Representa uma lista recebendo um campo. A API bloqueia o uso deste item quando o operador count entra na requisição.

 

Dicionário completo de parâmetros

A API bloqueia e rejeita a entrada de campos desconhecidos em sua base. Aplique as opções corretas listadas abaixo nos campos fields (métricas) e grouping (dimensões).

Métricas numéricas (fields)

  • likes: Traz o resultado total de Curtidas.

  • comments: Traz o resultado total de Comentários.

  • shares: Traz o resultado total de Compartilhamentos.

  • views: Traz o resultado total de Visualizações gerais.

  • fbViews: Traz o resultado total de Visualizações focadas no Facebook.

  • impressions: Traz o resultado total de Impressões.

  • reach: Traz o resultado total de Alcance.

  • interactions: Traz o resultado total de Interações.

Dimensões (grouping)

  • channel: Agrupa os dados por Canal (Instagram, TikTok, YouTube).

  • polarity: Agrupa os dados por Sentimento (polaridade).

  • gender: Agrupa os dados por Gênero.

  • postType: Agrupa os dados por Tipo de publicação.

  • device: Agrupa os dados por Dispositivo utilizado.

  • postedAtWeekDay: Agrupa os dados indicando o Dia da semana da publicação.

  • postedAtHour: Agrupa os dados indicando a Hora do dia da publicação.

  • postedAt: Agrupa os dados indicando a Data e a hora exata da publicação. O sistema aplica esta dimensão em séries temporais e exige a declaração de granularidade via datePortion.

Cada dimensão possui uma variável com terminação em Id (como channelId ou polarityId) que agrupa o resultado pelo número de identificador em vez do nome da plataforma ou do sentimento. Nota: Não aplique métricas numéricas dentro de opções de dimensão.

Operadores (operators)

  • sum: Executa a Soma matemática.

  • avg: Executa o cálculo de Média.

  • max: Extrai o Maior valor encontrado.

  • min: Extrai o Menor valor encontrado.

  • first: Extrai o Primeiro valor registrado.

  • last: Extrai o Último valor registrado.

  • count: Executa a Contagem exata de linhas. O sistema bloqueia o uso de fields com este operador.

Granularidades de data (datePortion)

  • year: Recorta por Ano.

  • quarter: Recorta por Trimestre. O sistema proíbe o uso desta granularidade junto com o operador count.

  • month: Recorta por Mês.

  • week: Recorta por Semana.

  • dayOfMonth: Recorta por Dia do mês.

  • hour: Recorta por Hora exata.

  • minute: Recorta por Minuto exato.

 

Estrutura visual e montagem dos componentes

A API entrega os dados de retorno em um corpo JSON apresentando a lista de pontos (points) e os valores precisos das dimensões (axes). A resposta devolve estes comportamentos específicos para a leitura do JSON:

  • points[].x: Exibe o valor da 1ª dimensão estipulada em grouping. O eixo converte este valor para um timestamp em milissegundos quando a requisição avalia séries temporais.

  • points[].y: Exibe o valor da 2ª dimensão estipulada em grouping, se aplicável.

  • points[].z: Exibe o valor matemático da métrica solicitada.

  • points[].name: Exibe o label original da métrica. O sistema designa que cada name vire uma série individual quando várias métricas entram no pedido.

  • axes[].label: Exibe o nome base da dimensão.

  • axes[].values: Exibe os valores finais que a dimensão identificou e assumiu no recorte de período.

Configure os gráficos da sua aplicação aplicando estas regras aos eixos:

  • Gráficos de Barras ou colunas: Exigem 1 dimensão configurada. O eixo x comporta a categoria e o eixo z comporta o valor da métrica. Gere uma série isolada por name quando precisar exibir várias métricas.

  • Gráficos de Barras agrupadas ou empilhadas: Exigem 2 dimensões configuradas. O eixo x comporta a categoria principal e o eixo y comporta a série.

  • Gráficos de Pizza ou rosca: Exigem 1 dimensão configurada e 1 métrica preenchida.

  • Gráficos de Linha ou área: Exigem o alinhamento de postedAt na primeira posição do grouping e o envio da variável datePortion. O eixo x carrega a linha do tempo.

  • Cards de Número único (KPI): Demandam a soma direta dos valores de z em uma requisição estruturada com 1 dimensão. O formato entrega resultados precisos ao trabalhar junto com sum e count.

  • Renderização de Tabelas: Demandam o uso dos pontos brutos, do jeito que o JSON entregou.

 

Exemplos de chamadas estruturadas

Exemplo 1: Quantidade de curtidas por canal (Maior para o menor)

Soma as curtidas de cada canal em setembro e ordena pelo valor da métrica.

curl -X POST 'https://api.stilingue.com.br/charts/posts/{TOKEN}?date_range=202609010000:202609302359' \
  -H 'Content-Type: application/json' \
  -d '{
    "metricsMetadata": [
      { "label": "total_curtidas", "operators": ["sum"], "fields": ["likes"] }
    ],
    "grouping": ["channel"],
    "sorting": "desc",
    "sortFields": ["total_curtidas"]
  }'

Resposta:

{
  "points": [
    { "x": "Instagram", "z": 1250430, "name": "total_curtidas" },
    { "x": "YouTube", "z": 310225, "name": "total_curtidas" },
    { "x": "Twitter", "z": 98410, "name": "total_curtidas" },
    { "x": "Facebook", "z": 41875, "name": "total_curtidas" },
    { "x": "TikTok", "z": 9320, "name": "total_curtidas" }
  ],
  "axes": [
    { "label": "channel", "values": ["Instagram", "YouTube", "Twitter", "Facebook", "TikTok"] }
  ]
}

Como ler: cada ponto é um canal (x) com o total de curtidas (z). A ordem já vem do maior para o menor, porque o sortFields usa o label da métrica. Serve para um gráfico de barras ou de pizza.

Exemplo 2: Interações por dia (Construindo série temporal)

Soma as interações de cada dia entre 1º e 3 de outubro. A dimensão de data (postedAt) vai primeiro no grouping e a granularidade vem em datePortion.

curl -X POST 'https://api.stilingue.com.br/charts/posts/{TOKEN}?date_range=202610010000:202610032359' \
  -H 'Content-Type: application/json' \
  -d '{
    "metricsMetadata": [
      { "label": "interacoes", "operators": ["sum"], "fields": ["interactions"] }
    ],
    "grouping": ["postedAt"],
    "datePortion": "dayOfMonth"
  }'

Resposta:

{
  "points": [
    { "x": 1790823600000, "z": 48210, "name": "interacoes" },
    { "x": 1790910000000, "z": 52975, "name": "interacoes" },
    { "x": 1790996400000, "z": 44130, "name": "interacoes" }
  ],
  "axes": [
    { "label": "postedAt", "values": [1790823600000, 1790910000000, 1790996400000] }
  ]
}

Como ler: há um ponto por dia. O x é um timestamp em milissegundos (Unix epoch) e deve ser convertido para data no seu gráfico. Não é preciso ordenar: a série já vem em ordem cronológica. Serve para gráficos de linha ou de área. Para outra granularidade, troque dayOfMonth por hour, week, month etc. 

Exemplo 3: Contagem de quantidade de posts por canal

O sistema não invoca os fields pois o operador selecionado foi o count, que efetua contagem de linhas diretas na base de resposta.

curl -X POST 'https://api.stilingue.com.br/charts/posts/{TOKEN}?date_range=202609010000:202609302359' \
  -H 'Content-Type: application/json' \
  -d '{
    "metricsMetadata": [
      { "label": "posts", "operators": ["count"] }
    ],
    "grouping": ["channel"],
    "sorting": "desc",
    "sortFields": ["posts"]
  }'

Resposta:

{
  "points": [
    { "x": "Instagram", "z": 8120, "name": "posts" },
    { "x": "Twitter", "z": 6540, "name": "posts" },
    { "x": "YouTube", "z": 1310, "name": "posts" },
    { "x": "Facebook", "z": 905, "name": "posts" }
  ],
  "axes": [
    { "label": "channel", "values": ["Instagram", "Twitter", "YouTube", "Facebook"] }
  ]
}

Como ler: z é a quantidade de posts de cada canal. Para somar e contar na mesma chamada, envie mais de uma métrica em metricsMetadata, cada uma com o seu label: o name de cada ponto indica a qual delas ele pertence.

 

Dicas, FAQ e Códigos de Erro

Siga estas boas práticas de uso para evitar travamentos ou rejeições da documentação técnica:

  • Aplique sempre descrições legíveis nos labels (como "total_curtidas"), pois o JSON exibe essa taxonomia nos names e na ordenação visual.

  • Ordene as listas priorizando o label construído na métrica, e proíba a ordenação pelo nome bruto do campo. O envio do nome de campo original em sortFields faz a API devolver um erro indicando que a dimensão não existe no agrupamento.

  • Reduza a janela de período caso um erro de tempo de requisição ocorra (acima dos 30 segundos) ou estabeleça uma granularidade mais ampla utilizando o parâmetro datePortion.

  • Recorra à Documentação da API de Listening para necessidades de filtragem por sentimento, grupos, temas ou tags complexas.

  • Evite construir gráficos que exponham rankings de trabalho individual. A ferramenta bloqueia cenários de medição de produtividade de operadores específicos.

  • Utilize a Documentação do STILINGUE Smart Care para resgatar campos técnicos atrelados a tempos de atendimento, métricas de SLA e avaliações de volume na operação.

Caso sofra um bloqueio durante o envio do POST, avalie a mensagem devolvida em tela conforme esta listagem oficial:

  • Código 200: Exibe que a consulta obteve sucesso imediato.

  • Código 400: Exibe que a chamada possui sintaxe inválida ou sofreu rejeição. O retorno enviará o campo details apontando rigorosamente o erro.

  • Código 401: Exibe que o token de autenticação enviado possui falha de escrita, não foi identificado ou encontra-se desativado no painel.

  • Código 405: Exibe a tentativa de envio sob outro método divergente do modelo POST.

  • Código 413: Exibe que o Payload transferido pesou além dos 16 KB máximos de suporte da API.

  • Código 429: Exibe bloqueio de proteção contra sobrecarga de requests. Aguarde uma janela de alguns segundos antes da próxima tentativa.

  • Código 502: Exibe falha interna na ferramenta STILINGUE ao digerir sua solicitação. Capture o código trace_id enviado pela devolutiva e encaminhe para o time de suporte.

  • Código 504: Exibe o tempo expirado na fila de espera da requisição por excesso de processamento de dados. Segmente o seu filtro em intervalos mais curtos de data.

 

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃