Standard Reports Integration Guide

Microservice: XDPeople.Soba.Report.WebAPI
Authentication: Bearer Token (JWT) or API Key via X-API-KEY header Learn more...

Overview

Standard Reports are pre-configured reports existing in XDGC (Commercial Management) and provided by the XD Soba API. Each report includes:

📋 Column configuration — defines the available fields and their data types
⚙️ Parameters — filters (dates, entities, options) that determine the returned data
📊 Tabular data — execution result with filtered records
🔍 Master-Detail (optional) — main records with associated sub-records

When to Use

✅ Retrieve pre-defined business reports (e.g.: Issued Documents Sales, Details of Issued Sales, etc.)
✅ Integrate report data into your application or workflow
✅ Export filtered data for analysis

Implementation Flow

Integrating a standard report involves the following steps:

List available reports to obtain the guid (unique identifier)
Get the report info (columns, parameters, etc.)
Execute the report by sending the filled parameters

Step 1 — List Available Reports

Endpoint

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

Response (200 OK)

Returns an array of objects with the identifier and name of each report:

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

Field	Type	Description
`guid`	`string`	Unique identifier of the report (reportId)
`name`	`string`	Human-readable name of the report

Tip

Save the guid of the desired report — it will be needed in the following steps.

Step 2 — Get Report Info

Endpoint

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

Parameter	Location	Required	Description
`reportId`	path	✅ Yes	The `guid` obtained in Step 1

Response (200 OK)

The response is a object that contains the simplified report configuration, including the essential information to understand and execute the query.

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

Field	Type	Description
`reportId`	`string`	Unique identifier of the report
`title`	`string`	Report name
`keyExpr`	`string?`	Primary key field of the records
`parentIdExpr`	`string?`	Parent record reference field (for tree-structured reports)
`showMasterDetail`	`boolean`	Indicates whether the report has a Master-Detail structure
`masterDetailConfig`	`object?`	Sub-records configuration (if `showMasterDetail = true`)
`columns`	`array`	Report column configuration
`parameters`	`array`	Report parameters/filters

2.1 — Columns (`columns`)

The columns array describes the structure of the fields returned in the results:

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

Field	Type	Description
`dataField`	`string`	Field name in the returned data
`displayName`	`string`	Descriptive name of the field
`dataType`	`string`	Data type (`string`, `number`, `date`, `boolean`, etc.)

Tip

Use the dataType to correctly interpret the values returned in Step 3. For example, date fields return ISO 8601 strings, number fields return numeric values.

2.2 — Parameters (`parameters`)

The parameters array defines the filters the report accepts. It is essential to correctly interpret each parameter to build the execution JSON.

{
  "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
}

Parameter Fields

Field	Type	Description
`displayName`	`string`	Descriptive name of the parameter
`description`	`string?`	Detailed description of the parameter
`value`	`string?`	Default value (pre-calculated by the server)
`paramHolder`	`string`	Key to use in the execution JSON (e.g.: `@initialDate`)
`group`	`int`	Visual grouping of parameters (for UI)
`viewType`	`int`	Parameter type — see table below
`entityTypeValue`	`string?`	API path segment for fetching entity options
`valueList`	`any?`	Pre-defined options list (for ComboBox, ListBox, etc.)

`viewType` — Parameter Type (`ParameterViewType`)

Defines the nature of the expected value for the parameter:

Value	Name	Description
0	Default	Free text (default behaviour)
1	Dynamic	Dynamic — the expected format can be inferred from the default `value`
2	Lookup	Entity reference — fetched via `GET /gateway/{entityTypeValue}` (see entityTypeValue)
3	ComboBox	Value selection — see ComboBox rules
4	ListBox	Selection from a list
5	Query	Value fed by a query
6	Bool	Boolean value (true/false)
7	Date	Date
8	Number	Numeric value

How to determine the value format

The viewType directly indicates the expected data type for Bool (6), Date (7) and Number (8). For Default (0) and Dynamic (1), analyse the default value field to infer the expected format (e.g.: "2025-01-01" suggests a date, "" suggests free text, "0" suggests a number).

`entityTypeValue` — API Path Segment

The entityTypeValue field is used by Lookup (2) and ComboBox (3) viewTypes to indicate which entity provides the options. Its value corresponds to a path segment of the API. To retrieve the entity records, simply call:

GET /gateway/{entityTypeValue}

For example, if entityTypeValue = "item", the route will be GET /gateway/item (which returns the list of items).

Note

Entity endpoints (GET /gateway/{entityTypeValue}) may support pagination with parameters such as skip and pageSize. Refer to the respective entity documentation for available parameters.

Some common entityTypeValue values:

Value	Entity	Route
`customer`	Customers	`GET /gateway/customer`
`supplier`	Suppliers	`GET /gateway/supplier`
`item`	Items	`GET /gateway/item`
`warehouse`	Warehouses	`GET /gateway/warehouse`
`document-type`	Document Types	`GET /gateway/document-type`
`series`	Series	`GET /gateway/series`
`entity`	Entities (general)	`GET /gateway/entity`

ComboBox — Data Source Rules

When viewType = 3 (ComboBox), the valid options for the parameter are determined by the combination of the entityTypeValue and valueList fields.

`entityTypeValue`	`valueList`	Behaviour
empty/null	with data	Valid options come only from `valueList`
with value	empty/null	Valid options come from the `GET /gateway/{entityTypeValue}` route
with value	with data	Merges both sources — records from `GET /gateway/{entityTypeValue}` are combined with `valueList` options

Practical Example

If a parameter has entityTypeValue: "warehouse" and valueList: [{"key": "ALL", "value": "All Warehouses"}]:

Call GET /gateway/warehouse to get the list of warehouses
The accepted values include the "All Warehouses" option (from valueList) plus all warehouses returned by the API

`valueList` — Static Options List

The valueList field contains pre-defined options for ComboBox (viewType = 3) or ListBox (viewType = 4) type parameters. The selected value must be sent in the execution JSON.

2.3 — Master-Detail (Optional)

If showMasterDetail = true, the report contains main records with associated sub-records. The sub-records configuration is in masterDetailConfig:

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

Field	Type	Description
`description`	`string`	Description of the sub-records
`keyExpr`	`string`	Key field of the sub-records
`columnsConfig`	`array`	Detail column configuration (same structure as `columns`)

Step 3 — Execute the Report

Endpoint

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

Parameter	Location	Required	Description
`reportId`	path	✅ Yes	The report `guid`
`jsonParameters`	query	✅ Yes	Serialized JSON object with the parameter values

How to Build `jsonParameters`

For each parameter returned in Step 2, use the paramHolder value as the JSON key
Set the value according to the parameter's viewType (date, string, number, boolean, or option key from valueList)
All parameters must always be sent in the execution JSON

Example JSON (before URL-encode):

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

Full request example:

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}
# or
X-API-KEY: {api-key}

Important

The jsonParameters value must be sent as serialized JSON and URL-encoded. Most modern HTTP libraries handle serialization and URL-encoding of query parameters automatically — simply pass the JSON object and the library will handle the rest.

Response (200 OK)

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

Field	Type	Description
`count`	`int`	Total number of records returned
`value`	`array`	Array of objects — each object is a report row
`summaryData`	`object?`	Summary/totalization data (present in some reports)
`additionalData`	`any?`	Additional report-specific data

Note

The fields of each object in value correspond to the dataField values defined in the columns from the report info (Step 2). Use the column dataType to correctly interpret each field.

Complete Example — Step by Step

In this example we will consume the "Documentos Emitidos Venda" (Issued Sales Documents) report from scratch.

1. List available reports

GET /gateway/reports
Authorization: Bearer eyJhbGciOi...

Response:

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

We save the guid: FC82430B-C7A4-40F0-A2EA-C9E06247BA75

2. Get report info

GET /gateway/reports/FC82430B-C7A4-40F0-A2EA-C9E06247BA75/info
Authorization: Bearer eyJhbGciOi...

Response:

{
  "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
    },
    {
      "displayName": "Data Final",
      "description": "Data de fim do período",
      "value": "2025-12-31",
      "paramHolder": "@finalDate",
      "viewType": 7,
      "entityTypeValue": null,
      "required": true,
      "valueList": null
    },
    {
      "displayName": "Cliente Inicial",
      "description": null,
      "value": "",
      "paramHolder": "@initialCustomer",
      "viewType": 0,
      "entityTypeValue": null,
      "required": false,
      "valueList": null
    },
    {
      "displayName": "Cliente Final",
      "description": null,
      "value": "ZZZZZZZZZZZZZZZZZZZZZZZZZ",
      "paramHolder": "@finalCustomer",
      "viewType": 0,
      "entityTypeValue": null,
      "required": false,
      "valueList": null
    }
  ]
}

From this report info we know:

There are 3 columns (Cliente, Data, Valor)
There are 4 parameters with the paramHolder values: @initialDate, @finalDate, @initialCustomer, @finalCustomer
The value fields already contain default values pre-calculated by the server

3. Build and execute

We build the JSON using the paramHolder values as keys:

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

We apply URL-encode and execute:

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...

Response:

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

Error Handling

Code	Description	When it Occurs
`200`	OK	Successful operation
`401`	Unauthorized	JWT token missing, invalid or expired
`500`	Internal Server Error	Internal error (invalid parameters, non-existent report, etc.)

Error Structure (401)

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

Best Practices

✅ Recommended

Cache the report list (GET /gateway/reports) — it does not change frequently
Cache the report info (GET /gateway/reports/{id}/info) per session — avoids repeated calls
Use default parameter values (value) as initial values — they come pre-calculated by the server
Respect the required field — do not omit required parameters
Use viewType to determine the expected format of each parameter
Use the column dataType to correctly interpret returned values
Check showMasterDetail — if true, the response may contain sub-records

❌ Avoid

Executing the report without first consulting the report info
Ignoring the paramHolder field — it is the exact key the backend expects in the JSON
Forgetting to serialize the parameters JSON (JSON.stringify)
Assuming fixed fields — always use the returned report info to interpret results
Ignoring the dataType of columns — it is necessary to correctly interpret values

Quick Endpoint Reference

Action	Method	Endpoint	Description
List reports	GET	`/gateway/reports`	Lists all available reports
Get report info	GET	`/gateway/reports/{reportId}/info`	Column and parameter information
Execute report	GET	`/gateway/reports/{reportId}`	Returns filtered data

Next Steps

API Reference — Complete OpenAPI documentation for the Report API
Endpoint: List Reports — Endpoint details
Endpoint: Info — Endpoint details
Endpoint: Execute Report — Endpoint details

Last Updated: February 27, 2026

Overview​

When to Use​

Implementation Flow​

Step 1 — List Available Reports​

Endpoint​

Response (200 OK)​

Step 2 — Get Report Info​

Endpoint​

Response (200 OK)​

2.1 — Columns (columns)​

2.2 — Parameters (parameters)​

Parameter Fields​

viewType — Parameter Type (ParameterViewType)​

entityTypeValue — API Path Segment​

ComboBox — Data Source Rules​

valueList — Static Options List​

2.3 — Master-Detail (Optional)​

Step 3 — Execute the Report​

Endpoint​

How to Build jsonParameters​

Response (200 OK)​

Complete Example — Step by Step​

1. List available reports​

2. Get report info​

3. Build and execute​

Error Handling​

Error Structure (401)​

Best Practices​

✅ Recommended​

❌ Avoid​

Quick Endpoint Reference​

Next Steps​

Overview

When to Use

Implementation Flow

Step 1 — List Available Reports

Endpoint

Response (200 OK)

Step 2 — Get Report Info

Endpoint

Response (200 OK)

2.1 — Columns (`columns`)

2.2 — Parameters (`parameters`)

Parameter Fields

`viewType` — Parameter Type (`ParameterViewType`)

`entityTypeValue` — API Path Segment

ComboBox — Data Source Rules

`valueList` — Static Options List

2.3 — Master-Detail (Optional)

Step 3 — Execute the Report

Endpoint

How to Build `jsonParameters`

Response (200 OK)

Complete Example — Step by Step

1. List available reports

2. Get report info

3. Build and execute

Error Handling

Error Structure (401)

Best Practices

✅ Recommended

❌ Avoid

Quick Endpoint Reference

Next Steps