API GraphQL

Cada conta tem um endereço GraphQL próprio, de leitura, sobre as suas entidades. Serve para ligar outra ferramenta aos mesmos dados sem os exportar.

Endereço

POST https://<a-sua-instalacao>/api/graphql/<slug-da-conta>

O slug é o identificador da conta na instalação.

Autenticação

O acesso exige uma sessão válida dessa conta — o mesmo cookie que a aplicação usa. Um pedido sem sessão, ou com sessão de outra conta, recebe 401.

Em ambiente de desenvolvimento, abrir o endereço no navegador com sessão iniciada dá o GraphiQL, útil para explorar o esquema.

Os dashboards públicos não passam por aqui

Um link público não dá acesso a este endereço. Os dados dos widgets de um dashboard público são servidos por outro caminho, restrito às entidades daquele ecrã. Publicar um dashboard nunca expõe o modelo da conta.

O esquema

O esquema é gerado a partir do modelo de dados da conta — uma entidade por tabela importada. Não tem mutações: por construção, só existem operações de leitura.

Para cada entidade há três operações:

Operação	O que devolve
get<Entidade>	Lista de registos, com filtro, ordenação e paginação
count<Entidade>	Total de registos com o mesmo filtro
aggregate<Entidade>	Agrupamento com métricas

Uma entidade chamada Vendas dá getVendas, countVendas e aggregateVendas.

Consultar

query {
  getVendas(
    where: { canal: { eq: "Online" } }
    order: [{ field: "data", direction: DESC }]
    take: 50
  ) {
    numero
    data
    valor
    canal
  }
}

Os argumentos:

Argumento	O que faz
where	Condições por campo
order	Lista de critérios de ordenação
take	Quantos registos devolver
skip	Quantos saltar (paginação)

countVendas aceita o mesmo where, o que faz dele o par natural do get para paginar.

Agregar

query {
  aggregateVendas(
    groupBy: ["canal"]
    metrics: [{ fn: SUM, field: "valor" }]
  ) {
    canal
    sumValor
  }
}

O nome da coluna resultante é a função em minúsculas seguida do campo em maiúscula inicial: SUM sobre valor dá sumValor.

Tipos

Os tipos vêm do modelo:

Tipo do campo	Tipo GraphQL
Texto	String
Número inteiro	Int
Número decimal	Float
Data	String (ISO-8601)
Sim/Não	Int

As datas viajam em ISO-8601. O tipo existe para os widgets saberem que a coluna é temporal, não para mudar a forma como é escrita.

Relações

O modelo não guarda relações entre entidades — ver O modelo de dados. Cada entidade é consultada isoladamente; para cruzar tabelas, ou se faz do lado de quem consome, ou se usa o construtor de consultas da aplicação.

Quando usar

Use a API para alimentar outra ferramenta com os mesmos números, para automatizar uma exportação periódica, ou para verificar um valor fora da aplicação.

Não use para construir uma segunda interface de dashboards por cima: os widgets já leem por um caminho mais restrito e mais rápido.

Uma alternativa mais simples

Para um assistente de IA, o servidor MCP é melhor caminho: autentica-se por OAuth, respeita as permissões do utilizador e já traz operações de alto nível para ler o modelo e construir dashboards.