Guia de integração de Relatórios Padrão (Standard Reports)

Microserviço: XDPeople.Soba.Report.WebAPI
Autenticação: Bearer Token (JWT) ou Chave de API via header X-API-KEY Saiba mais...

Visão Geral

Os Relatórios Padrão (Standard Reports) são relatórios pré-configurados existente no XDGC (Gestão Comercial) e disponibilizados pela api do XD Soba. Cada relatório possui:

📋 Configuração de colunas — define os campos disponíveis e os seus tipos de dados
⚙️ Parâmetros — filtros (datas, entidades, opções) que condicionam os dados retornados
📊 Dados tabulares — resultado da execução com os registos filtrados
🔍 Master-Detail (opcional) — registos principais com sub-registos associados

Quando Usar

✅ Obter relatórios de negócio já definidos (ex.: Documentos Emitidos Vendas, Detalhes de Emitidos Venda, etc.)
✅ Integrar dados de relatórios na sua aplicação ou fluxo de trabalho
✅ Exportar dados filtrados para análise

Fluxo de Implementação

A integração de um relatório padrão possui os seguintes passos:

Listar os relatórios disponíveis para obter o guid (identificador único)
Obter as informações do relatório escolhido (colunas, parâmetros, etc.)
Executar o relatório enviando os parâmetros preenchidos

Passo 1 — Listar Relatórios Disponíveis

Endpoint

GET /gateway/reports
Authorization: Bearer {token}
# ou
X-API-KEY: {api-key}

Resposta (200 OK)

Retorna um array de objetos com o identificador e nome de cada relatório:

[
  {
    "guid": "FC82430B-C7A4-40F0-A2EA-C9E06247BA75",
    "name": "Documentos Emitidos Venda"
  },
  {
    "guid": "1471F994-582B-4B61-A201-63483D99F902",
    "name": "Detalhes de Documentos Emitidos - Venda"
  }
]

Campo	Tipo	Descrição
`guid`	`string`	Identificador único do relatório (reportId)
`name`	`string`	Nome legível do relatório

Dica

Guarde o guid do relatório desejado — será necessário nos passos seguintes.

Passo 2 — Obter Informações do Relatório

Endpoint

GET /gateway/reports/{reportId}/info
Authorization: Bearer {token}
# ou
X-API-KEY: {api-key}

Parâmetro	Localização	Obrigatório	Descrição
`reportId`	path	✅ Sim	O `guid` obtido no Passo 1

Resposta (200 OK)

A resposta é um objeto que contém a configuração simplificada do relatório, incluindo as informações essenciais para compreender e executar a consulta.

{
  "reportId": "FC82430B-C7A4-40F0-A2EA-C9E06247BA75",
  "title": "Documentos Emitidos Venda",
  "keyExpr": "id",
  "parentIdExpr": null,
  "showMasterDetail": false,
  "masterDetailConfig": null,
  "columns": [ ... ],
  "parameters": [ ... ]
}

Campo	Tipo	Descrição
`reportId`	`string`	Identificador único do relatório
`title`	`string`	Nome do relatório
`keyExpr`	`string?`	Campo chave primária dos registos
`parentIdExpr`	`string?`	Campo de referência ao registo pai (para relatórios em árvore)
`showMasterDetail`	`boolean`	Indica se o relatório tem estrutura Master-Detail
`masterDetailConfig`	`object?`	Configuração dos sub-registos (se `showMasterDetail = true`), que contém a configuração das colunas em `columnsConfig`
`columns`	`array`	Configuração das colunas do relatório
`parameters`	`array`	Parâmetros/filtros do relatório

2.1 — Colunas (`columns`)

O array columns descreve a estrutura dos campos retornados nos resultados. A mesma estrutura é usada em masterDetailConfig.columnsConfig para os sub-registos.

O array columns descreve a estrutura dos campos retornados nos resultados:

{
  "dataField": "entityName",
  "displayName": "Cliente",
  "dataType": "string"
}

Campo	Tipo	Descrição
`dataField`	`string`	Nome do campo nos dados retornados
`displayName`	`string`	Nome descritivo do campo
`dataType`	`string`	Tipo de dados (`string`, `number`, `date`, `boolean`, etc.)

Dica

Use o dataType para interpretar correctamente os valores retornados no Passo 3. Por exemplo, campos date retornam strings ISO 8601, campos number retornam valores numéricos.

2.2 — Parâmetros (`parameters`)

O array parameters define os filtros que o relatório aceita. É essencial interpretar correctamente cada parâmetro para construir o JSON de execução.

{
  "displayName": "Data Inicial",
  "description": "Data de início do período",
  "value": "2025-01-01",
  "paramHolder": "@initialDate",
  "viewType": 7,
  "group": 0,
  "entityTypeValue": null,
  "valueList": null
}

Campos dos Parâmetros

Campo	Tipo	Descrição
`displayName`	`string`	Nome descritivo do parâmetro
`description`	`string?`	Descrição detalhada do parâmetro
`value`	`any?`	Valor por defeito (pré-calculado pelo servidor)
`paramHolder`	`string`	Chave a usar no JSON de execução (ex.: `@initialDate`)
`group`	`int`	Agrupador visual de parâmetros (para UI)
`viewType`	`int`	Tipo do parâmetro — ver tabela abaixo
`entityTypeValue`	`string?`	Segmento do path da API para obter opções de entidade
`valueList`	`any?`	Lista de opções pré-definidas (para ComboBox, ListBox, etc.)

`viewType` — Tipo do Parâmetro (`ParameterViewType`)

Define a natureza do valor esperado para o parâmetro:

Valor	Nome	Descrição
0	Default	Texto livre (comportamento padrão)
1	Dynamic	Dinâmico — o formato esperado pode ser inferido pelo `value` por defeito
2	Lookup	Referência a uma entidade — obtida via `GET /gateway/{entityTypeValue}` (ver entityTypeValue)
3	ComboBox	Seleção de valor — ver regras do ComboBox
4	ListBox	Seleção a partir de uma lista
5	Query	Valor alimentado por query
6	Bool	Valor booleano (verdadeiro/falso)
7	Date	Data
8	Number	Valor numérico

Como determinar o formato do valor

O viewType indica diretamente o tipo de dado esperado nos casos Bool (6), Date (7) e Number (8). Para Default (0) e Dynamic (1), analise o campo value por defeito para inferir o formato esperado (ex.: "2025-01-01" sugere uma data, "" sugere texto livre, 0 sugere um número).

`entityTypeValue` — Segmento do Path da API

O campo entityTypeValue é usado pelos viewTypes Lookup (2) e ComboBox (3) para indicar de que entidade vêm as opções. O seu valor corresponde a um segmento do path da API. Para obter os registos da entidade, basta fazer uma chamada a:

GET /gateway/{entityTypeValue}

Por exemplo, se entityTypeValue = "item", a rota será GET /gateway/item (que retorna a lista de artigos).

Nota

Os endpoints de entidade (GET /gateway/{entityTypeValue}) podem suportar paginação com parâmetros como skip e pageSize. Consulte a documentação da respectiva entidade para os parâmetros disponíveis.

Alguns valores comuns de entityTypeValue:

Valor	Entidade	Rota
`customer`	Clientes	`GET /gateway/customer`
`supplier`	Fornecedores	`GET /gateway/supplier`
`item`	Artigos	`GET /gateway/item`
`warehouse`	Armazéns	`GET /gateway/warehouse`
`document-type`	Tipos de Documento	`GET /gateway/document-type`
`series`	Séries	`GET /gateway/series`
`entity`	Entidades (geral)	`GET /gateway/entity`

ComboBox — Regras de Fonte de Dados

Quando viewType = 3 (ComboBox), as opções válidas para o parâmetro são determinadas pela combinação dos campos entityTypeValue e valueList.

`entityTypeValue`	`valueList`	Comportamento
vazio/null	com dados	As opções válidas vêm apenas de `valueList`
com valor	vazio/null	As opções válidas vêm da rota `GET /gateway/{entityTypeValue}`
com valor	com dados	Mescla as duas fontes — os registos de `GET /gateway/{entityTypeValue}` são combinados com as opções de `valueList`

Exemplo Prático

Se um parâmetro tem entityTypeValue: "warehouse" e valueList: [{"key": "ALL", "value": "Todos os Armazéns"}]:

Chamar GET /gateway/warehouse para obter a lista de armazéns
Os valores aceites incluem a opção "Todos os Armazéns" (do valueList) mais todos os armazéns retornados pela API

`valueList` — Lista de Opções Estáticas

O campo valueList contém opções pré-definidas para parâmetros do tipo ComboBox (viewType = 3) ou ListBox (viewType = 4). O valor selecionado deve ser enviado no JSON de execução.

2.3 — Master-Detail (Opcional)

Se showMasterDetail = true, o relatório contém registos principais com sub-registos associados. A configuração dos sub-registos está em masterDetailConfig:

{
  "masterDetailConfig": {
    "description": "Movimentos",
    "keyExpr": "movementId",
    "columnsConfig": [
      {
        "dataField": "date",
        "displayName": "Data",
        "dataType": "date"
      }
    ]
  }
}

Campo	Tipo	Descrição
`description`	`string`	Descrição dos sub-registos
`keyExpr`	`string`	Campo chave dos sub-registos
`columnsConfig`	`array`	Configuração de colunas do detalhe (mesma estrutura de `columns`)

Passo 3 — Executar o Relatório

Endpoint

GET /gateway/reports/{reportId}?jsonParameters={jsonEncoded}
Authorization: Bearer {token}
# ou
X-API-KEY: {api-key}

Parâmetro	Localização	Obrigatório	Descrição
`reportId`	path	✅ Sim	O `guid` do relatório
`jsonParameters`	query	✅ Sim	Objeto JSON serializado com os valores dos parâmetros

Como Construir o `jsonParameters`

Para cada parâmetro retornado no Passo 2, use o valor de paramHolder como chave do JSON
Defina o valor conforme o viewType do parâmetro (data, string, número, booleano, ou chave de opção do valueList)
Todos os parâmetros devem ser sempre enviados no JSON de execução

Exemplo JSON (antes de URL-encode):

{
  "@initialDate": "2025-07-24",
  "@finalDate": "2025-09-24",
  "@initialCustomer": "",
  "@finalCustomer": "ZZZZZZZZZZZZZZZZZZZZZZZZZ"
}

Exemplo da chamada completa:

GET /gateway/reports/FC82430B-C7A4-40F0-A2EA-C9E06247BA75?jsonParameters=%7B%22%40initialDate%22%3A%222025-07-24%22%2C%22%40finalDate%22%3A%222025-09-24%22%2C%22%40initialCustomer%22%3A%22%22%2C%22%40finalCustomer%22%3A%22ZZZZZZZZZZZZZZZZZZZZZZZZZ%22%7D
Authorization: Bearer {token}
# ou
X-API-KEY: {api-key}

Importante

O valor de jsonParameters deve ser enviado como JSON serializado e codificado para URL (URL-encoded). A maioria das bibliotecas HTTP modernas tratam automaticamente da codificação de query parameters — basta passar o objeto JSON serializado e a biblioteca encarrega-se do resto.

Resposta (200 OK)

{
  "count": 2,
  "value": [
    {
      "id": 1,
      "entityName": "Cliente A",
      "date": "2025-08-01",
      "amount": 1500.00
    },
    {
      "id": 2,
      "entityName": "Cliente B",
      "date": "2025-08-15",
      "amount": 750.50
    }
  ],
  "summaryData": {
    "icon": "chart",
    "header": "Resumo",
    "isFullWidth": false,
    "sections": [
      {
        "title": "Totais",
        "items": [
          {
            "label": "Total",
            "format": "currency",
            "value": 2250.50,
            "addSuffix": true
          }
        ]
      }
    ]
  },
  "additionalData": null
}

Campo	Tipo	Descrição
`count`	`int`	Número total de registos retornados
`value`	`array`	Array de objectos — cada objecto é uma linha do relatório
`summaryData`	`object?`	Dados de resumo/totalização (presente em alguns relatórios)
`additionalData`	`any?`	Dados adicionais específicos do relatório

Nota

Os campos de cada objecto em value correspondem aos dataField definidos nas columns das informações (Passo 2). Use o dataType das colunas para interpretar correctamente cada campo.

Exemplo Completo — Passo a Passo

Neste exemplo vamos consumir o relatório "Documentos Emitidos Venda" do zero.

1. Listar relatórios disponíveis

GET /gateway/reports
Authorization: Bearer eyJhbGciOi...
# ou
X-API-KEY: {api-key}

Resposta:

[
  {
    "guid": "FC82430B-C7A4-40F0-A2EA-C9E06247BA75",
    "name": "Documentos Emitidos Venda"
  },
  {
    "guid": "1471F994-582B-4B61-A201-63483D99F902",
    "name": "Detalhes de Documentos Emitidos - Venda"
  }
]

Guardamos o guid: FC82430B-C7A4-40F0-A2EA-C9E06247BA75

2. Obter informações

GET /gateway/reports/FC82430B-C7A4-40F0-A2EA-C9E06247BA75/info
Authorization: Bearer eyJhbGciOi...
# ou
X-API-KEY: {api-key}

Resposta:

{
  "reportId": "FC82430B-C7A4-40F0-A2EA-C9E06247BA75",
  "title": "Documentos Emitidos Venda",
  "keyExpr": "id",
  "parentIdExpr": null,
  "showMasterDetail": false,
  "masterDetailConfig": null,
  "columns": [
    {
      "dataField": "entityName",
      "displayName": "Cliente",
      "dataType": "string"
    },
    {
      "dataField": "date",
      "displayName": "Data",
      "dataType": "date"
    },
    {
      "dataField": "amount",
      "displayName": "Valor",
      "dataType": "number"
    }
  ],
  "parameters": [
    {
      "displayName": "Data Inicial",
      "description": "Data de início do período",
      "value": "2025-01-01",
      "paramHolder": "@initialDate",
      "viewType": 7,
      "entityTypeValue": null,
      "required": true,
      "valueList": null
    },
    {
      "caption": "Data Final",
      "description": "Data de fim do período",
      "value": "2025-12-31",
      "paramHolder": "@finalDate",
      "viewType": 7,
      "entityTypeValue": null,
      "required": true,
      "valueList": null
    },
    {
      "caption": "Cliente Inicial",
      "description": null,
      "value": "",
      "paramHolder": "@initialCustomer",
      "viewType": 0,
      "entityTypeValue": null,
      "required": false,
      "valueList": null
    },
    {
      "caption": "Cliente Final",
      "description": null,
      "value": "ZZZZZZZZZZZZZZZZZZZZZZZZZ",
      "paramHolder": "@finalCustomer",
      "viewType": 0,
      "entityTypeValue": null,
      "required": false,
      "valueList": null
    }
  ]
}

A partir destas informações sabemos:

Existem 3 colunas (Cliente, Data, Valor)
Existem 4 parâmetros com os paramHolder: @initialDate, @finalDate, @initialCustomer, @finalCustomer
Os campos value já contém valores por defeito pré-calculados pelo servidor

3. Construir e executar

Construímos o JSON com os paramHolder como chaves:

{
  "@initialDate": "2025-07-01",
  "@finalDate": "2025-09-30",
  "@initialCustomer": "",
  "@finalCustomer": "ZZZZZZZZZZZZZZZZZZZZZZZZZ"
}

Aplicamos URL-encode e executamos:

GET /gateway/reports/FC82430B-C7A4-40F0-A2EA-C9E06247BA75?jsonParameters=%7B%22%40initialDate%22%3A%222025-07-01%22%2C%22%40finalDate%22%3A%222025-09-30%22%2C%22%40initialCustomer%22%3A%22%22%2C%22%40finalCustomer%22%3A%22ZZZZZZZZZZZZZZZZZZZZZZZZZ%22%7D
Authorization: Bearer eyJhbGciOi...
# ou
X-API-KEY: {api-key}

Resposta:

{
  "count": 2,
  "value": [
    {
      "id": 1,
      "entityName": "Cliente A",
      "date": "2025-08-01",
      "amount": 1500.00
    },
    {
      "id": 2,
      "entityName": "Cliente B",
      "date": "2025-08-15",
      "amount": 750.50
    }
  ],
  "summaryData": {
    "icon": null,
    "header": "Resumo",
    "isFullWidth": false,
    "sections": [
      {
        "title": "Totais",
        "items": [
          { "label": "Total", "format": "currency", "value": 2250.50, "addSuffix": true }
        ]
      }
    ]
  },
  "additionalData": null
}

Gestão de Erros

Código	Descrição	Quando Ocorre
`200`	OK	Operação bem-sucedida
`401`	Unauthorized	Token JWT ausente, inválido ou expirado
`500`	Internal Server Error	Erro interno (parâmetros inválidos, relatório inexistente, etc.)

Estrutura de Erro (401)

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Token is invalid or expired.",
  "instance": "/gateway/reports"
}

Boas Práticas

✅ Recomendado

Cachear a lista de relatórios (GET /gateway/reports) — não muda frequentemente
Cachear as informações (GET /gateway/reports/{id}/info) por sessão — evita chamadas repetidas
Usar os valores por defeito dos parâmetros (value) como valores iniciais — já vêm pré-calculados pelo servidor
Usar o viewType para determinar o formato esperado de cada parâmetro
Usar o dataType das colunas para interpretar correctamente os valores retornados
Verificar showMasterDetail — se true, a resposta pode conter sub-registos

❌ Evitar

Executar o relatório sem consultar primeiro as informações
Ignorar o campo paramHolder — é a chave exacta que o backend espera no JSON
Esquecer de serializar o JSON dos parâmetros (JSON.stringify)
Assumir campos fixos — usar sempre as informações retornadas para interpretar os resultados
Ignorar o dataType das colunas — é necessário para interpretar correctamente os valores

Referência Rápida de Endpoints

Ação	Método	Endpoint	Descrição
Listar relatórios	GET	`/gateway/reports`	Lista todos os relatórios disponíveis
Obter informações	GET	`/gateway/reports/{reportId}/info`	Colunas e parâmetros do relatório
Executar relatório	GET	`/gateway/reports/{reportId}`	Retorna os dados filtrados

Próximos Passos

Referência da API — Documentação OpenAPI completa da Report API
Endpoint: Listar Relatórios — Detalhes do endpoint
Endpoint: Info — Detalhes do endpoint
Endpoint: Executar Relatório — Detalhes do endpoint

Última Atualização: 25 de Fevereiro de 2026

Visão Geral​

Quando Usar​

Fluxo de Implementação​

Passo 1 — Listar Relatórios Disponíveis​

Endpoint​

Resposta (200 OK)​

Passo 2 — Obter Informações do Relatório​

Endpoint​

Resposta (200 OK)​

2.1 — Colunas (columns)​

2.2 — Parâmetros (parameters)​

Campos dos Parâmetros​

viewType — Tipo do Parâmetro (ParameterViewType)​

entityTypeValue — Segmento do Path da API​

ComboBox — Regras de Fonte de Dados​

valueList — Lista de Opções Estáticas​

2.3 — Master-Detail (Opcional)​

Passo 3 — Executar o Relatório​

Endpoint​

Como Construir o jsonParameters​

Resposta (200 OK)​

Exemplo Completo — Passo a Passo​

1. Listar relatórios disponíveis​

2. Obter informações​

3. Construir e executar​

Gestão de Erros​

Estrutura de Erro (401)​

Boas Práticas​

✅ Recomendado​

❌ Evitar​

Referência Rápida de Endpoints​

Próximos Passos​

Visão Geral

Quando Usar

Fluxo de Implementação

Passo 1 — Listar Relatórios Disponíveis

Endpoint

Resposta (200 OK)

Passo 2 — Obter Informações do Relatório

Endpoint

Resposta (200 OK)

2.1 — Colunas (`columns`)

2.2 — Parâmetros (`parameters`)

Campos dos Parâmetros

`viewType` — Tipo do Parâmetro (`ParameterViewType`)

`entityTypeValue` — Segmento do Path da API

ComboBox — Regras de Fonte de Dados

`valueList` — Lista de Opções Estáticas

2.3 — Master-Detail (Opcional)

Passo 3 — Executar o Relatório

Endpoint

Como Construir o `jsonParameters`

Resposta (200 OK)

Exemplo Completo — Passo a Passo

1. Listar relatórios disponíveis

2. Obter informações

3. Construir e executar

Gestão de Erros

Estrutura de Erro (401)

Boas Práticas

✅ Recomendado

❌ Evitar

Referência Rápida de Endpoints

Próximos Passos