Add

[POST] .../v1/widget/add

Adds one or more widgets to a dashboard. Use this method to create multiple widgets on a custom dashboard in one request after the dashboard exists. The request body is a required array; every item must include dashboard_id, non-default widget_type and name up to 100 characters and connected_integration_id is required only for widget_type Integration where the connected integration must be active and support the Widget handler. The method validates current request user dashboard ownership or dashboard all-edit permission, rejects system or fixed dashboards, validates non-zero firm_id and stock_id when provided, inserts all widget rows in one transaction, writes action log records, clears widget cache and returns row_affected with inserted ids. Business errors such as missing or empty array body, invalid item fields, denied access, system or fixed dashboard restrictions, unknown dashboard/company/stock/integration, inactive or unsupported integration, stock-company mismatch, database errors, transaction failures and action-log failures are returned as HTTP 200 ErrorResult.

Request Parameters

Name Type Required Description
column Int32 Optional Column position used when the widget is created. Numbering starts from 0; null is saved as 0.
connected_integration_id String Optional Connected integration ID. Required only when widget_type is Integration; ignored for other widget types.
dashboard_id Int64 Required Dashboard ID.
firm_id Int64 Optional Company ID. 0 means company is not specified.
height Int32 Optional Widget height used when the widget is created. null uses the database default.
name String Required Widget name, up to 100 characters.
row Int32 Optional Row position used when the widget is created.
stock_id Int64 Optional Stock ID. 0 means stock is not specified.
widget_type String Required Widget type. Allowed values: Default, PersonalTargets, GlobalTargets, Accounts, RetailOrders, OperatingCashes, RetailSaleStats, RetailPaymentStats, RetailSalesDynamics, RetailTop10Quantity, RetailTop10ItemsAmount, RetailCustomersComingBirthdays, RetailCustomersPreferredPurchasesTop10, PartnersDebtTop10, RetailCustomersAgeDistribution, RetailCustomersSexDistribution, TariffInfo, RetailCustomersDebtTop10, RetailSalesActivity, Integration.
width Int32 Optional Widget width used when the widget is created.

Request Example

[
  {
    "dashboard_id": 3,
    "widget_type": "RetailSaleStats",
    "name": "Retail sales",
    "row": 0,
    "column": 0,
    "width": 4,
    "height": 2,
    "firm_id": 10,
    "stock_id": 4
  },
  {
    "dashboard_id": 3,
    "widget_type": "Integration",
    "name": "Marketplace chart",
    "row": 0,
    "column": 4,
    "width": 4,
    "height": 2,
    "connected_integration_id": "f1c4b0e2-3a77-4a98-9f40-38ce97000001"
  }
]

Response Parameters

Name Type Description
ok Boolean Indicates whether the request completed successfully.
result Update Update operation result.

Response Example

{
  "ok": true,
  "result": {
    "row_affected": 2,
    "ids": [
      15,
      16
    ]
  }
}