Pular para o conteúdo principal

Guia de integração — Gráficos dinâmicos

Áreas da API: serviço de relatórios (/gateway/dynamic-chart-reports) — persistência, configuração e exportação; API principal (/gateway/dynamic-chart-report) — catálogo paginado e menu.
Autenticação: Bearer Token (JWT) ou Chave de API via header X-API-KEY.

Requisito de autenticação

Para seguir este guia com sucesso utilizando autenticação JWT, utilize o seguinte endpoint:

POST /gateway/auth/combined-login

Saiba mais…

Introdução​

Este guia descreve como integrar com os gráficos dinâmicos: configurações guardadas que associam um relatório dinâmico (fonte de dados tabular e parâmetros @p_…) a definições visuais (tipo de série, diagrama, paleta, eixos e legenda).

Não existe SQL própria do gráfico. A fonte de dados é sempre o relatório dinâmico referenciado por selectedDynamicReportGuid. Na execução, os dados obtêm-se com GET /gateway/dynamic-reports/{guid}/data?jsonParameters=…, tal como no Guia de relatórios dinâmicos.

Este documento está organizado para leitura por etapas e para consulta por ferramentas: pré-requisitos e ligação campos ↔ eixos, permissões, fluxos (criação, atualização, obtenção de dados), parâmetros do relatório subjacente, jsonParameters, enumerados visuais, referência de endpoints e DTOs, exemplos e erros. Ver Mapa do documento.

Quando utilizar​

  • Criar ou alterar um gráfico ligado a um relatório dinâmico existente.
  • Listar gráficos (lista completa no serviço de relatórios, catálogo paginado ou entradas de menu na API principal).
  • Obter configuração (…/config) para montar filtros e saber qual relatório e campos usar nos eixos.
  • Exportar o JSON interno do gráfico (cópia de segurança ou diagnóstico).

Mapa do documento​

  1. Pré-requisitos — relatório dinâmico válido e colunas alinhadas com o gráfico; secção Pré-requisitos.
  2. Campos e eixos — argument, value, serieMember; secção Ligação aos dados do relatório.
  3. Permissões — permissionType, grupos, utilizador; secção Permissões.
  4. Fluxos de implementação — criação, atualização, execução de dados; secção Fluxos de implementação.
  5. Parâmetros do relatório subjacente — reciclagem do modelo do relatório dinâmico; secção Parâmetros do relatório subjacente.
  6. jsonParameters — formato na cadeia de consulta; secção Parâmetro de query jsonParameters.
  7. Tipos visuais — séries, diagramas e paletas numéricas; secção Tipos visuais.
  8. Prefixos no gateway — Dois prefixos.
  9. Referência — Endpoints disponíveis, estrutura dos DTOs, exemplos JSON, tratamento de erros, recursos relacionados.

Pré-requisitos: relatório dinâmico​

Antes de criar um gráfico dinâmico:

  1. Ter um relatório dinâmico criado e guardado (GUID conhecido). O fluxo inclui validação da SQL, configuração de fields e parameters — ver Guia de relatórios dinâmicos.
  2. Confirmar que as colunas devolvidas pela SQL (propriedade name em cada campo do relatório) cobrem os nomes que vai usar em argument, value e, se aplicável, serieMember nas definições do gráfico.
  3. Garantir permissões para ler dados desse relatório no contexto autenticado (GET …/dynamic-reports/{guid}/config e GET …/dynamic-reports/{guid}/data).

Se selectedDynamicReportGuid apontar para um relatório inexistente ou inacessível, as operações de gravar ou de GET …/config podem falhar no servidor ao resolver o relatório subjacente.

Ligação aos dados do relatório​

Propriedade em settingsEntity / DynamicChartConfigFunçãoCorrespondência no relatório
argumentEixo de categorias (ex.: eixo X)name de uma coluna no resultado do relatório (ex.: alias na SQL).
valueMagnitude representada (ex.: eixo Y)name de uma coluna tipicamente numérica.
serieMemberAgrupamento em várias séries (opcional)name de uma coluna que distinga séries (texto ou categorização).

Os nomes devem coincidir exatamente com os identificadores das colunas configuradas no relatório dinâmico (não confundir com caption, que é apenas para apresentação).

Alteração do relatório subjacente

Se alterar a SQL ou os fields do relatório dinâmico, volte a validar que argument, value e serieMember continuam a existir no resultado; caso contrário o cliente de gráficos pode receber dados incompletos ou vazios sem erro explícito na camada do gráfico.

Permissões​

O modelo de permissionType, permissionGroupsId e userId segue a mesma linha dos relatórios dinâmicos (partilha de conceitos com o GC):

Valor permissionTypeSignificado habitualNotas
0Todos os utilizadoresSem restrição por utilizador ou grupo no modelo «gráfico».
1Utilizador atualAssociação ao utilizador autenticado; userId pode ser gerido pelo servidor.
2GruposPreencher permissionGroupsId com os IDs dos grupos autorizados.

No PUT, o serviço pode preservar o userId já guardado no servidor mesmo que o cliente envie outro valor — consulte o comportamento na sua versão e teste com GET …/dynamic-chart-reports/{guid} após atualizar.

Fluxos de implementação​

O comportamento recomendado segue dois percursos: criação de um gráfico novo e atualização de um já guardado. Em ambos, o relatório dinâmico referenciado deve permanecer válido.

Execução no tempo de execução (obter dados para o gráfico)​

Para desenhar o gráfico no cliente, o fluxo de dados é uma camada em cima do relatório dinâmico:

PassoRelatório dinâmico (tabular)Gráfico dinâmico (visualização)
Identificar recursoGUID do relatórioGUID do gráfico
Configuração para o ecrã (filtros + metadados)GET /gateway/dynamic-reports/{guid}/configGET /gateway/dynamic-chart-reports/{chartGuid}/config (inclui dynamicReportGuid e parameters do relatório subjacente)
Obter linhasGET /gateway/dynamic-reports/{guid}/data?jsonParameters=…Mesmo pedido, usando o dynamicReportGuid devolvido em config do gráfico e os mesmos jsonParameters
MapeamentoColunas → tabelaCada linha → argument, value, serieMember conforme config do gráfico

Ou seja: o gráfico não substitui o endpoint de dados do relatório; apenas indica qual relatório usar e como mapear colunas para a biblioteca de gráficos.

Criação de um gráfico novo​

Diagrama do fluxo de primeira gravação:

  1. Escolher selectedDynamicReportGuid e definir settingsEntity (argument, value, serieMember, tipo de série, diagrama, paleta, título, legendas).
  2. Opcional: validar colunas com GET /gateway/dynamic-reports/{selectedDynamicReportGuid}/config no relatório antes de gravar o gráfico.
  3. POST /gateway/dynamic-chart-reports com guid vazio (ou omitido, conforme cliente).
  4. Em HTTP 200, o corpo contém o GUID do gráfico criado (texto).
  5. Opcional: GET …/{guid}/config para obter parameters já preparados para o formulário de execução.

Atualização de um gráfico existente​

Para alterar um gráfico já guardado, é preciso o guid do gráfico e a configuração atual ou um delta coerente:

  1. GET /gateway/dynamic-chart-reports/{guid} — obtém DynamicChartDataDTO tal como está persistido (recomendado antes de um PUT para não sobrescrever campos por omissão).
  2. Ajustar nome, descrição, selectedDynamicReportGuid, permissões ou settingsEntity.
  3. PUT /gateway/dynamic-chart-reports com o guid correto no corpo.
  4. Resposta esperada: 204 No Content.

Se só tiver uma lista proveniente do catálogo da API principal:

Catálogo versus lista completa

GET /gateway/dynamic-chart-report devolve um catálogo paginado (integração tipo lista de escolha no gateway principal). GET /gateway/dynamic-chart-reports (serviço de relatórios) devolve todos os gráficos dinâmicos num único array — útil para ferramentas administrativas; pode ser mais pesado em instalações grandes.

Utilizador associado no PUT

Ao atualizar, o backend pode manter o userId já guardado para o gráfico; não assuma que o valor enviado no corpo substitui sempre o persistido sem validar com um GET subsequente.

Parâmetros do relatório subjacente​

GET /gateway/dynamic-chart-reports/{guid}/config devolve parameters como coleção de ReportParameterDetail: mesmo tipo de informação que o cliente usa para montar filtros antes de executar o relatório dinâmico.

  • As chaves em jsonParameters ao chamar GET /gateway/dynamic-reports/{dynamicReportGuid}/data devem alinhar com os paramHolder / marcadores @p_… desse relatório (ver Parâmetros: lógica de configuração e visualização no guia de relatórios dinâmicos).
  • O tipo de controlo no ecrã (ViewType, listas, Lookup, etc.) segue as mesmas regras documentadas para relatórios dinâmicos; o gráfico apenas encaminha o utilizador para preencher os filtros do relatório fonte.

Não existe operação dedicada «verify» para gráficos: alterações à SQL ou aos parâmetros do relatório tratam-se no fluxo do relatório dinâmico (verify-sqlquery, etc.).

Parâmetro de query jsonParameters​

Para obter as linhas usadas no gráfico, utilize GET /gateway/dynamic-reports/{dynamicReportGuid}/data com o parâmetro de consulta opcional jsonParameters: objeto JSON serializado em texto e codificado para URL, tal como em Relatórios Padrão e no guia de relatórios dinâmicos.

  • Chaves: iguais aos nomes dos parâmetros do relatório (@p_…).
  • Valores: formatados conforme o tipo (data, número, texto, etc.).
Importante

Envie jsonParameters como texto JSON codificado na cadeia de consulta. As bibliotecas HTTP habituais tratam da serialização e da codificação para URL automaticamente.

Tipos visuais (série, diagrama, paleta)​

Na API, selectedSeries, selectedDiagram e selectedPalette são inteiros. A ordem dos valores corresponde aos enumerados do servidor (também refletidos no schema OpenAPI do serviço de relatórios).

DiagramType (valores 0…5)​

ValorMembro
0SimpleDiagram2D
1XYDiagram2D
2RadarDiagram2D
3PolarDiagram2D
4SimpleDiagram3D
5XYDiagram3D

PaletteName (valores 0…8)​

ValorMembro
0Chameleon
1DXCharts
2InAFog
3NatureColors
4NorthernLights
5Office
6PastelKit
7TerracottaPie
8TheTrees

SeriesType (valores 0…29)​

ValorMembroValorMembro
0Pie15OverlappedRangeBar
1Donut16Line
2Area17StackedLine
3StackedArea18FullStackedLine
4FullStackedArea19StepLine
5Bubble20ScatterLine
6Point21Stock
7StepArea22CandleStick
8RangeArea23ManhattanBar
9SideBySideBar24RadarArea
10SideBySideStackedBar25RadarLine
11SideBySideFullStackedBar26RadarPoint
12StackedBar27PolarArea
13FullStackedBar28PolarLine
14SideBySideRangeBar29PolarPoint

Alguns tipos de série esperam tipos de diagrama compatíveis no cliente de visualização (metadados Description no código servidor associam séries a famílias de diagrama). Em caso de dúvida, experimente no produto ou consulte o schema Swagger/OpenAPI gerado.

Dois prefixos no gateway​

PrefixoOrigem típica no gatewayFinalidade
/gateway/dynamic-chart-reportsServiço de relatóriosCRUD, /{guid}/config, /{guid}/export.
/gateway/dynamic-chart-reportAPI principalGET catálogo paginado; GET …/menu para entradas de menu.

Não confunda dynamic-chart-report (singular, catálogo/menu) com dynamic-chart-reports (plural, recurso completo no microserviço de relatórios).

Endpoints disponíveis​

Catálogo paginado (API principal)​

URL: /gateway/dynamic-chart-report
Método: GET
Query (opcional): page, pageSize

Devolve listagem paginada de gráficos dinâmicos no modelo da API principal (EntityListingDTO). Útil para escolher um guid antes de GET /gateway/dynamic-chart-reports/{guid}.
Ver mais →

Entradas visíveis no menu (API principal)​

URL: /gateway/dynamic-chart-report/menu
Método: GET

Lista de gráficos marcados para aparecer no menu (integração com ribbon/menu do produto).
Ver mais →

Operações sob /gateway/dynamic-chart-reports​

Todos os pedidos seguintes utilizam esse prefixo e exigem autenticação.

Listar todos os gráficos (serviço de relatórios)​

URL: /gateway/dynamic-chart-reports
Método: GET

Resposta (200): array de DynamicChartDataDTO (lista completa, sem paginação neste recurso).
Ver mais →

Criar gráfico dinâmico​

URL: /gateway/dynamic-chart-reports
Método: POST
Corpo: DynamicChartDataDTO

Resposta (200): corpo com o GUID do gráfico criado (texto).
Ver mais →

Atualizar gráfico dinâmico​

URL: /gateway/dynamic-chart-reports
Método: PUT
Corpo: DynamicChartDataDTO (incluir guid)

Resposta: 204 No Content em caso de sucesso.
Ver mais →

Obter gráfico guardado​

URL: /gateway/dynamic-chart-reports/{guid}
Método: GET

Resposta (200): DynamicChartDataDTO completo.
Ver mais →

Eliminar gráfico dinâmico​

URL: /gateway/dynamic-chart-reports/{guid}
Método: DELETE

Resposta: 204 No Content em caso de sucesso.
Ver mais →

Obter configuração para apresentação​

URL: /gateway/dynamic-chart-reports/{guid}/config
Método: GET

Resposta (200): DynamicChartConfig — definições visuais, dynamicReportGuid e parameters do relatório subjacente.
Ver mais →

Exportar dados internos do gráfico​

URL: /gateway/dynamic-chart-reports/{guid}/export
Método: GET

Resposta (200): cadeia JSON indentada com o estado interno persistido do gráfico (útil para cópia de segurança ou diagnóstico). Não substitui o fluxo GET …/dynamic-reports/…/data para alimentar o gráfico em tempo de execução.
Ver mais →

Estrutura dos DTOs principais​

A composição segue o modelo metadados do gráfico + definições visuais + referência ao relatório. Os valores numéricos dos tipos visuais estão em Tipos visuais.

DynamicChartDataDTO​

Corpo em POST / PUT e resposta em GET por GUID.

PropriedadeTipoObrigatório (criação típica)Descrição
guidstringAtualizaçãoVazio ou omitido na criação; obrigatório no PUT e nas rotas com {guid} no path.
namestringSimNome curto (máx. 25 caracteres).
descriptionstringSimDescrição (máx. 250 caracteres).
addToRibbonbooleanNãoExpor no ribbon/menu do produto quando aplicável.
selectedDynamicReportGuidstringSimGUID do relatório dinâmico fonte de dados.
permissionTypeintNãoVer Permissões.
userIdint?NãoContexto de permissão; ver nota sobre PUT.
permissionGroupsIdint[]CondicionalObrigatório quando permissionType indica grupos.
settingsEntityDynamicChartSettingsDTOSimLigação de campos e opções visuais.

DynamicChartSettingsDTO​

PropriedadeTipoDescrição
chartTitlestringTítulo do gráfico.
argumentstringCampo dos dados (eixo de categorias).
valuestringCampo dos dados (valores).
serieMemberstringCampo para múltiplas séries (opcional).
selectedSeriesintÍndice SeriesType.
selectedDiagramintÍndice DiagramType.
selectedPaletteintÍndice PaletteName.
animatebooleanAnimação.
showLegendbooleanLegenda principal.
showSeriesLegendbooleanLegenda por série.

DynamicChartConfig​

Resposta de GET …/{guid}/config.

PropriedadeDescrição
Definições espelhadaschartTitle, argument, value, serieMember, séries, diagrama, paleta, animação e legendas (espelho do persistido).
dynamicReportGuidGUID do relatório para GET …/dynamic-reports/{guid}/data.
parametersColeção ReportParameterDetail para construir o formulário de execução.

Exemplos JSON​

Corpo de criação (POST /gateway/dynamic-chart-reports)​

{
  "guid": "",
  "name": "VendasMensais",
  "description": "Barras por mês e categoria",
  "addToRibbon": true,
  "selectedDynamicReportGuid": "fbdc2005-e157-4deb-9d49-a1a0557e4eef",
  "permissionType": 0,
  "userId": null,
  "permissionGroupsId": [],
  "settingsEntity": {
    "chartTitle": "Vendas por mês",
    "argument": "Mes",
    "value": "TotalVendas",
    "serieMember": "Categoria",
    "selectedSeries": 9,
    "selectedDiagram": 1,
    "selectedPalette": 4,
    "animate": true,
    "showLegend": true,
    "showSeriesLegend": true
  }
}

Mes, TotalVendas e Categoria devem corresponder a name de colunas do relatório dinâmico referenciado. Os inteiros dos tipos visuais devem corresponder às tabelas em Tipos visuais.

Corpo de atualização (PUT /gateway/dynamic-chart-reports)​

Utilize o mesmo formato de DynamicChartDataDTO, com guid preenchido com o identificador devolvido na criação. É boa prática basear o corpo num GET prévio e alterar apenas os campos pretendidos.

Tratamento de erros​

As operações devolvem Problem Details ou erros alinhados com o padrão da API quando falham (autenticação, recurso não encontrado, falha de persistência, relatório subjacente inválido ao construir config, etc.).

O cliente de integração deve:

  1. Verificar o código de estado HTTP (4xx / 5xx).
  2. Ler o corpo (título, detalhe, tipo) e corrigir pedido, permissões ou dados.

Este guia não fixa códigos numéricos internos de mensagens localizadas: siga o texto devolvido e a página OpenAPI da operação.

Conclusão​

Integrar gráficos dinâmicos resume-se a: (1) garantir um relatório dinâmico adequado; (2) gravar o gráfico em POST /gateway/dynamic-chart-reports (ou atualizar com PUT); (3) usar GET …/{guid}/config para saber dynamicReportGuid e parameters; (4) obter linhas com GET /gateway/dynamic-reports/{guid}/data e jsonParameters, e mapear colunas para argument / value / serieMember. Para listagens no gateway principal, use GET /gateway/dynamic-chart-report (paginação) ou …/menu.

Recomenda-se testar em ambiente de qualidade alterações ao relatório subjacente, permissões e combinações série/diagrama antes de produção.

Recursos relacionados​

Última atualização: 12 de maio de 2026