QueryCurious - Porque ate dados merecem um pouco de sarcasmo

Descricao do Projeto

QueryCurious e o servico oficial que apresenta o data warehouse da Lifeapps Solucoes via OData. Ele entende filtros, agregacoes, ordenacao e paginacao, devolvendo as entidades que voce ja conhece: DimEmpresa, DimProduto e DimLoja. Tudo protegido por tenant: se o seu token diz que voce pertence a uma empresa, voce so enxerga os dados dela, mesmo que tente ser criativo no $filter.

Objetivo do Projeto

• Entregar dados analiticos prontos para uso sem exigir manutencao extra.
• Garantir isolamento e seguranca por tenant direto no token.
• Oferecer interfaces OData e MCP padronizadas para conexoes plug-and-play.

Fluxo de Autenticacao

O teste definitivo para quem diz que domina APIs:

1. Solicite um token JWT usando client credentials. Exemplo classico:

   curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=<XXX>" \
     -d "client_secret=<xxxx>" \
     https://sso.lifeappsecommerce.com.br/realms/lifeapps/protocol/openid-connect/token

2. Copie o valor de access_token devolvido.
3. Envie em todas as requisicoes:

   Authorization: Bearer <seu_access_token>

4. O servico extrai o claim empresa. Se ele faltar, voce recebe um aviso simpatico; se estiver presente, as consultas fluem.

Dica rapida: tokens expiram. Renove antes do dashboard reclamar.

Integracao MCP para agentes

O servidor remoto QueryCurious Lifeapps esta disponivel em /mcp para clientes compativeis com Model Context Protocol. Ele entrega o mesmo acesso analitico tenant-scoped da API OData, agora em formato natural para agentes de IA que precisam descobrir schemas, montar consultas e explicar resultados sem adivinhar o data warehouse inteiro.

Configuracao de cliente

Primeiro obtenha o token no Keycloak:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<mcp-client-id>" \
  -d "client_secret=<mcp-client-secret>" \
  https://sso.lifeapps.com.br/realms/lifeapps/protocol/openid-connect/token

Depois use a URL publica do ambiente e envie o token como Bearer:

{
  "mcpServers": {
    "querycurious-lifeapps": {
      "url": "https://querycurious.lifeapps.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${QUERYCURIOUS_MCP_TOKEN}"
      }
    }
  }
}

Renove o token fora do QueryCurious. Nao existe endpoint nem tool MCP para gerar JWT.

OData e MCP compartilham o mesmo billing. O contador nao liga para a interface, so para os megabytes entregues.

Billing sem terrorismo

Tutorial Definitivo de OData

Tudo o que voce precisa para transformar curiosidade em dashboards. Os EntitySets publicados sao:

• /odata/DimEmpresa
• /odata/DimProduto
• /odata/DimLoja

Resposta sempre em JSON, com ate 50 linhas por pagina e isolamento por tenant.

$select - dieta de colunas

Sem $select vem tudo. Use apenas o que importa.

GET /odata/DimEmpresa?$select=nome,erp

GET /odata/DimLoja?$select=nome,ativo&$filter=ativo eq true

Nomes invalidos resultam em 400. Com $apply, cite so colunas agrupadas ou aliases.

$filter - onde a logica brilha

Misture comparacoes, funcoes e operacoes sem perder o controle. Strings precisam de aspas simples, GUIDs devem ser validos, null e case-insensitive.

$orderby - colocando ordem no caos

GET /odata/DimProduto?$orderby=data_atualizacao desc

GET /odata/DimLoja?$orderby=ativo desc,nome asc

GET /odata/DimProduto?$filter=disponivel eq true&$orderby=descricao asc

asc e padrao. Depois de $apply, ordene apenas por colunas agrupadas ou aliases.

$top e $skip - paginacao civilizada

GET /odata/DimProduto?$top=20&$orderby=data_atualizacao desc

GET /odata/DimProduto?$skip=50&$top=50

$top maior que 50 rende 400. Combine com $skip para navegar sem drama.

$count - conhecendo o tamanho da festa

GET /odata/DimEmpresa?$filter=erp eq 'ERP-X'&$count=true

A resposta inclui @odata.count com o total antes da paginacao. $apply nao altera o contador.

$apply - agregacoes com estilo

GET /odata/DimProduto?$apply=
  groupby((disponivel),
    aggregate(multiplo_incremento with sum as TotalMultiplo))

GET /odata/DimProduto?$apply=
  groupby((disponivel),
    aggregate(id with countdistinct as ProdutosUnicos))

GET /odata/FatoPedido?$filter=year(datapedido) eq 2026 and month(datapedido) eq 6&
  $apply=groupby((),
    aggregate(dim_cliente with countdistinct as ClientesDistintos))

GET /odata/DimLoja?$filter=ativo eq true&
  $apply=groupby((ativo),
    aggregate(notaavaliacao with avg as AvgRating))

GET /odata/DimProduto?
  $filter=disponivel eq true and multiplo_incremento gt 0&
  $apply=groupby((disponivel),
    aggregate(multiplo_incremento with sum as TotalMultiplo))&
  $select=disponivel,TotalMultiplo&
  $orderby=TotalMultiplo desc&
  $top=10

Use parenteses duplos em groupby, filtre antes de agregar e, apos $apply, selecione apenas colunas agrupadas ou aliases.

Combos dignos de daily

GET /odata/DimEmpresa?
  $select=nome,erp&
  $filter=erp eq 'ERP-X' or contains(nome,'Beta')&
  $orderby=nome asc&
  $top=25&
  $skip=25&
  $count=true

GET /odata/DimProduto?
  $filter=disponivel eq true and multiplo_incremento gt 0&
  $apply=groupby((disponivel),
    aggregate(multiplo_incremento with sum as TotalMultiplo))&
  $select=disponivel,TotalMultiplo&
  $orderby=TotalMultiplo desc&
  $top=10

Erros mais comuns? Coluna inexistente (400), sintaxe torta em $filter (400), $apply sem groupby valido (400) e $top acima de 50 (400). Tudo em modo somente leitura: o maximo que voce trava e o proprio script.

Links uteis

Swagger e ReDoc pedem o token Bearer diretamente nos formularios. Para MCP, configure a URL remota no cliente e envie Authorization: Bearer ${QUERYCURIOUS_MCP_TOKEN}.