ReportBuilder

ReportBuilder methods are used to read builder metadata, validate report drafts, create queued builder report requests, and retrieve prepared builder results.

• ReportBuilder/GetDomains
• ReportBuilder/GetSchema
• ReportBuilder/Validate
• ReportBuilder/AddRequest
• ReportBuilder/GetPrepared

Filter metadata uses the shared FilterField properties: field, datatype, filter_type, multiple, operators, and required. Report-specific labels, option_source, applies_to_sources, and order extend that contract. Use the selected domain's GetSchema response as the catalog of allowed fields and operators.

Drafts and report requests use the shared Filter array with Field, Operator, and string Value. For In, pass comma-separated values; dates use Unix seconds, and datatype int supports 64-bit integers. Omit an optional filter to select all available values. Standard filters reject empty values. Duplicate fields, unsupported operators, and field-reference placeholders are rejected for all filters. Validate also determines filters required by the chosen report structure.

Custom fields

GetSchema includes available custom fields from the current account when additional fields are enabled by the tariff. Select them through the ordinary structure and filters properties; clients do not supply field definitions.

Finance and Crm do not expose custom fields. An account without additional fields can still use ordinary builder reports. Definition-loading failures return an error.

Use the stable code returned by GetSchema, such as retail_card.custom.123; the number identifies the field definition. Use schema compatibility and Validate availability to determine where a field applies. Custom field titles are account-defined text; display title when title_key is absent.

Custom filters accept one value (multiple=false). All four types support Equal, NotEqual, Exists and NotExists; int and decimal also support Greater, Less, GreaterOrEqual and LessOrEqual. The schema remains the source of allowed operators.

• string preserves spaces, case, empty strings and commas. A comma is part of the value, not a list separator.
• int accepts signed 64-bit integers, including zero and negative values.
• decimal uses a dot as the decimal separator, without thousands separators or exponent notation.
• bool uses true or false.
• Exists and NotExists do not require Value and ignore it when supplied. For other operators, null or omitted Value is invalid; an empty string is valid only for string fields.

These filters can be saved in templates. Reports use current custom-field definitions and values at execution time; saved filters are checked against the current field types.

The maximum size of report request parameters is set by server configuration. AddRequest returns error 1008 if the limit is exceeded.

Company and warehouse checks apply to domains whose schemas declare firm_id and stock_id. Crm and WorkTime do not require firm_id.

Building the filter and option panel

1. Load GetSchema once per selected domain. Use filter metadata to choose inputs and option value_type, allowed_values, default_value, min_value and max_value to build option controls.
2. Send the current structure, filters and options to Validate after edits. An incomplete draft is supported: missing required filters produce valid=false together with panel metadata.
3. Join availability.filters by schema.filters.field and availability.options by schema.options.code. Show controls with enabled=true, mark required=true, and use reason_code to explain disabled controls. A filter can affect a metric even when its corresponding entity is not displayed as a column.
4. Use applies_to_sources and applies_to_metrics from the resolved control state to explain partial applicability in mixed-source reports. The backend applies each filter only to its advertised sources.
5. Use effective_parameters to inspect normalized active inputs. Compilation and execution use the same resolution. Inactive values are discarded with inactive_filter_ignored or inactive_option_ignored warnings. Invalid filter syntax is still reported; omit unset or inactive filters from requests.
6. Submit AddRequest only when valid=true. Company and warehouse permissions remain enforced before queuing. Ignore stale Validate responses when newer edits have already been sent.

Option scope=execution means the backend applies the value. For scope=presentation, read the effective options from the decompressed prepared report: show_group_totals controls aggregate values on group rows, while expand_first_level controls initial expansion. Keep group labels and child rows accessible when hiding group totals. Options with execution_status=unsupported are hidden.

For example, stock_balance.current_quantity requires firm_id and date, while currency_id, price_type_id and cost_type are hidden. Adding stock_balance.stock_cost_amount enables cost_type and makes currency_id required. Adding stock_balance.retail_price requires price_type_id. ABC/XYZ thresholds and recommendation settings appear only in applicable drafts.

Known support limits are explicit in metadata: period_interval, tabular calculation options, and the Sales domain currency_id filter are unsupported. Period grouping comes from structure fields. Finance currency_id labels amount columns without converting amounts; Partner currency_id selects balance currency and labels trading amounts without conversion.