API DataObject

Get by Id

Chiamata per ottenere il dataobject tramite l'Id appartenente alla classe indicata.

GET/api/rest/{class_name}/{id}

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: list

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Classe del dataobject richiesto (es: Product)
`id`	Id del dataobject

Query Params

Nome	Tipo	Default	Descrizione
`fieldsToExpand`	`string`	`null`	I campi della classe richiesti separati da virgola, se vuoto sono restituiti tutti i campi. Per le relazioni è necessario separare il campo con il `.` es.: `color.name`
`relationsToExpand`	`string`	`null`	Le relazioni da espandere della classe separati da virgola (es.: `color` )

Body Response

{
  "data": {
    "id": 5432,
    "key": "678790b9ee946",
    "path": "/Catalog/Products/",
    "fullpath": "/Catalog/Products/678790b9ee946",
    "published": true,
    "modificationDate": "2025-09-08T13:38:20+00:00",
    "creationDate": "2025-01-15T10:40:58+00:00",
    "type": "object",
    "field_1": "value_1",
    "field_2": "value_2",
    "color": {
      "name": "Yellow"
    }
  },
  "errors": [],
  "hasErrors": false
}

Get list

Chiamata per ottenere una lista di dataobject appartenente alla classe indicata e con i parametri indicati.

GET/api/rest/{class_name}

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: list

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Nome della classe del data object da recuperare (es: `Product`, `Category`)

Query Params

Nome	Tipo	Default	Descrizione
`offset`	`int`	0	Indice di partenza per la paginazione dei risultati
`limit`	`int`	1000	Numero massimo di record da restituire
`query`	`string`	`null`	Filtro di ricerca in formato stringa (es: `modificationDate >= 1748611683`)
`sort`	`string`	`null`	Campo e direzione di ordinamento dei risultati in formato json (es: `{"modificationDate":"DESC"}`)
`showObject`	`bool`	`true`	Se `true`, include gli oggetti configurabili
`showVariant`	`bool`	`false`	Se `true`, include le varianti
`inheritanceAllowed`	`bool`	`true`	Se `true`, consente di ereditare i campi da oggetto configurabile
`fieldsToExpand`	`string`	`null`	I campi della classe richiesti separati da virgola, se vuoto sono restituiti tutti i campi. Per le relazioni è necessario separare il campo con il `.` es.: `color.name`
`relationsToExpand`	`string`	`null`	Le relazioni da espandere della classe separati da virgola (es.: `color` )

Body Response

{
  "data": [
    {
        "id": 5432,
        "key": "678790b9ee946",
        "path": "/Catalog/Products/",
        "fullpath": "/Catalog/Products/678790b9ee946",
        "published": true,
        "modificationDate": "2025-09-23T07:14:43+00:00",
        "modificationDateTimestamp": 1758611683,
        "creationDate": "2025-01-15T10:29:59+00:00",
        "creationDateTimestamp": 1736936999,
        "type": "object",
        "field_1": "value_1",
        "field_2": "value_2",
        "color": {
          "name": "Yellow"
        }
    },
    {
        "id": 5433,
        "key": "678790b9ee947",
        "path": "/Catalog/Products/",
        "fullpath": "/Catalog/Products/678790b9ee947",
        "published": true,
        "modificationDate": "2025-09-23T07:14:43+00:00",
        "modificationDateTimestamp": 1758611683,
        "creationDate": "2025-01-15T10:29:59+00:00",
        "creationDateTimestamp": 1736936999,
        "type": "object",
        "field_1": "value_1",
        "field_2": "value_2"
    }
  ],
  "errors": [],
  "hasErrors": false,
  "count": 2
}

Get by field

Chiamata per ottenere uno oppure una lista di dataobject appartenente alla classe indicata filtrata per l'attributo passato con path param.

GET/api/rest/{class_name}/{field_name}/byfield

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: list

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Nome della classe del data object da recuperare (es: `Product`, `Category`)
`field_name`	Nome della campo con cui filtrare i risultati (es: `sku`, `name`)

Query Params

Nome	Tipo	Default	Descrizione
`fieldValue`	`string`	-	Valore dell'attributo per filtrar i risultati
`showObject`	`bool`	`true`	Se `true`, include gli oggetti configurabili
`showVariant`	`bool`	`false`	Se `true`, include le varianti
`getAll`	`bool`	`false`	Se `true`, restituisce tutti i risultati altrimenti solo il primo
`fieldsToExpand`	`string`	`null`	I campi della classe richiesti separati da virgola, se vuoto sono restituiti tutti i campi. Per le relazioni è necessario separare il campo con il `.` es.: `color.name`
`relationsToExpand`	`string`	`null`	Le relazioni da espandere della classe separati da virgola (es.: `color` )

Body Response

{
  "data": [
    {
        "id": 5432,
        "key": "678790b9ee946",
        "path": "/Catalog/Products/",
        "fullpath": "/Catalog/Products/678790b9ee946",
        "published": true,
        "modificationDate": "2025-09-23T07:14:43+00:00",
        "modificationDateTimestamp": 1758611683,
        "creationDate": "2025-01-15T10:29:59+00:00",
        "creationDateTimestamp": 1736936999,
        "type": "object",
        "field_1": "value_1",
        "field_2": "value_2",
        "color": {
          "name": "Yellow"
        }
    },
    {
        "id": 5433,
        "key": "678790b9ee947",
        "path": "/Catalog/Products/",
        "fullpath": "/Catalog/Products/678790b9ee947",
        "published": true,
        "modificationDate": "2025-09-23T07:14:43+00:00",
        "modificationDateTimestamp": 1758611683,
        "creationDate": "2025-01-15T10:29:59+00:00",
        "creationDateTimestamp": 1736936999,
        "type": "object",
        "field_1": "value_1",
        "field_2": "value_2"
    }
  ],
  "errors": [],
  "hasErrors": false,
  "count": 2
}

Get items count

Chiamata per ottenere il numero totale degli oggetti di una data classe.

GET/api/rest/{class_name}/count

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: list

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Classe del dataobject richiesto (es: Product)

Body Response

{
  "data": {
    "result": 517
  },
  "errors": [],
  "hasErrors": false
}

Create

Chiamata per creare un nuovo dataobject appartenente alla classe indicata.

POST/api/rest/{class_name}

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: save

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Classe del dataobject richiesto (es: Product)

Query Params

Nome	Tipo	Default	Descrizione
`output`	`string`	`result`	Definisce l'output restituito dall’operazione (`result` = OK o KO, `full` = intero dataobject).
`relationStrategy`	`string`	`assign`	Strategia di risoluzione delle relazioni: `assign`, `create` o `upsert`. Vedi Relazioni.
`overwriteOnConflict`	`bool`	`false`	Se `true`, in caso di conflitto sul path sovrascrive l'elemento esistente.

Body Request

{
    "key": "67878e279a2fe",
    "path": "/Catalog/Products/",
    "sku": "67878e279a2fe",
    "made_in": "IT"
}

Body Response 200 OK

{
    "data": {
    "result": "OK"
},
    "errors": [],
    "hasErrors": false
}

Update

Chiamata per aggiornare un dataobject esistente tramite Id e classe.

PUT/api/rest/{class_name}/{id}

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: list, save

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Classe del dataobject richiesto (es: Product)
`id`	Id del dataobject

Query Params

Nome	Tipo	Default	Descrizione
`output`	`string`	`result`	Definisce l'output restituito dall’operazione (`result` = OK o KO, `full` = intero dataobject).
`relationStrategy`	`string`	`assign`	Strategia di risoluzione delle relazioni: `assign`, `create` o `upsert`. Vedi Relazioni.
`overwriteOnConflict`	`bool`	`false`	Se `true`, in caso di conflitto sul path sovrascrive l'elemento esistente.

Body Input

{
    "sku": "67878e279a2fe",
    "made_in": "FR"
}

Body Response

{
  "data": {
    "result": "OK"
  },
  "errors": [],
  "hasErrors": false
}

Upsert Bulk

Chiamata per creare o aggiornare dataobject appartenenti alla classe indicata e con i parametri indicati.

POST/api/rest/{class_name}/bulk

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: list, save

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Nome della classe del data object da recuperare (es: `Product`, `Category`)

Query Params

Nome	Tipo	Default	Descrizione
`upsert`	`bool`	`true`	Se `true`, aggiorna l’oggetto esistente o lo inserisce se non esiste.
`versioning`	`bool`	`false`	Se `true`, abilita il versioning dell’oggetto per mantenere uno storico delle modifiche.
`singleTransaction`	`bool`	`false`	Se `true`, esegue tutte le operazioni in un'unica transazione SQL.
`disableValidation`	`bool`	`false`	Se `true`, disabilita la validazione del salvataggio del dataobject.
`disableCache`	`bool`	`true`	Se `true`, forza il recupero dei dati senza utilizzare la cache.
`disableLog`	`bool`	`true`	Se `true`, disabilita la generazione di log per l’operazione.
`surrogate`	`string`	`null`	Nome campo univoco per aggiornamento del dataobject, è restituito nella risposta.
`commitSize`	`int`	100	Numero massimo di record da salvare per batch durante operazioni di scrittura massiva.
`garbageSize`	`int`	100	Dimensione massima del batch per operazioni di garbage collection.
`output`	`string`	`result`	Definisce l'output restituito dall’operazione (es. `result` = OK o KO, `full` = intero dataobject).
`relationStrategy`	`string`	`assign`	Strategia di risoluzione delle relazioni: `assign`, `create` o `upsert`. Vedi Relazioni.
`overwriteOnConflict`	`bool`	`false`	Se `true`, in caso di conflitto sul path sovrascrive l'elemento esistente.

Body Input

[
    {
        "key": "67878e279a2fe",
        "path": "/Catalog/Products/",
        "sku": "67878e279a2fe",
        "made_in": "IT"
    },
    {
        "key": "67878e279a2fe-1",
        "path": "/Catalog/Products/",
        "sku": "67878e279a2fe-1",
        "made_in": "IT"
    }
 ]

Body Response 200 OK

{
    "data": {
    "result": [
{
    "id": 7422,
    "fullpath": "/Catalog/Products/67878e279a2fe",
    "inputItemIndex": 0,
    "result": "OK"
}
    ]
},
    "errors": [],
    "hasErrors": false,
    "count": 1
}

Aggiunta di elementi a una fieldcollection

Se almeno un elemento ha fieldcollection_position, la fieldcollection non viene sostituita: i nuovi item si aggiungono a quelli esistenti.

con fieldcollection_position valida (da 0) → insert in quella posizione
senza, oppure posizione non valida → append in fondo

Se nessuno ha fieldcollection_position, la collection viene sostituita (comportamento precedente).

POST /api/rest/Product/bulk

[
  {
    "id": 123,
    "images": {
      "ImageInfo": [
        {
          "fieldcollection_position": 2,
          "image": {
            "path": "/ProductsImages/",
            "filename": "product-1.jpg",
            "url": "https://example.com/product-1.jpg"
          }
        },
        {
          "image": {
            "path": "/ProductsImages/",
            "filename": "product-2.jpg",
            "url": "https://example.com/product-2.jpg"
          }
        }
      ]
    }
  }
]

Il primo item va in posizione 2, il secondo in fondo. L'ordine di elaborazione è quello del payload.

Delete by Id

Chiamata per l'eliminazione di dataobject tramite l'Id appartenente alla classe indicata.

DELETE/api/rest/{class_name}/{id}

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: {class_name}
Permesso per l'accesso al workspace dello specifico path: delete

Headers: Autenticazione

Path Params

Nome	Descrizione
`class_name`	Classe del dataobject richiesto (es: Product)
`id`	Id del dataobject

Body Response 200 OK

{
    "data": {
    "result": "OK"
},
    "errors": [],
    "hasErrors": false
}

Relazioni

Durante le operazioni di scrittura (Create, Update, Upsert Bulk) i campi relazione possono essere risolti tramite la query param relationStrategy.

Valore	Descrizione
`assign`	(default) Associa un elemento già esistente, senza crearne o modificarne uno nuovo.
`create`	Crea un nuovo DataObject correlato e lo associa. Fallisce se al path indicato esiste già un elemento.
`upsert`	Se al path indicato esiste già un DataObject lo aggiorna, altrimenti lo crea, e lo associa.

informazioni

Le strategie create e upsert sono supportate solo per DataObject. Asset e Document sono gestibili esclusivamente con assign. La strategia viene propagata anche alle relazioni annidate dell'oggetto correlato.

Payload con `assign`

È possibile riferire l'elemento correlato in uno dei seguenti modi:

Per full path

{
  "color": {
    "object_fullpath": "/Attributes/Colors/Yellow"
  }
}

Per Asset o Document usare rispettivamente asset_fullpath e document_fullpath.

Per campo univoco ({ClassName}_{fieldName})

{
  "color": {
    "Color_code": "YLW"
  }
}

Payload con `create` / `upsert`

Il campo object_fullpath è obbligatorio: da esso vengono ricavati key e path del DataObject correlato. Gli altri campi del payload vengono usati per valorizzare (o aggiornare, in caso di upsert) l'oggetto correlato.

Se la relazione ammette più classi, è necessario indicare classname. Se ne ammette una sola, viene inferita automaticamente.

Many-to-one

{
  "key": "67878e279a2fe",
  "path": "/Catalog/Products/",
  "sku": "67878e279a2fe",
  "color": {
    "object_fullpath": "/Attributes/Colors/Yellow",
    "classname": "Color",
    "name": "Yellow",
    "code": "YLW"
  }
}

Many-to-many

{
  "key": "67878e279a2fe",
  "path": "/Catalog/Products/",
  "sku": "67878e279a2fe",
  "categories": [
    {
      "object_fullpath": "/Catalog/Categories/Shoes",
      "classname": "Category",
      "name": "Shoes"
    },
    {
      "object_fullpath": "/Catalog/Categories/Sale",
      "classname": "Category",
      "name": "Sale"
    }
  ]
}

Advanced many-to-many (con colonne metadata)

{
  "materials": [
    {
      "object_fullpath": "/Attributes/Materials/Cotton",
      "classname": "Material",
      "name": "Cotton",
      "columns": {
        "percentage": 80
      }
    }
  ]
}

Get by Id​

Get list​

Get by field​

Get items count​

Create​

Update​

Upsert Bulk​

Aggiunta di elementi a una fieldcollection​

Delete by Id​

Relazioni​

Payload con assign​

Payload con create / upsert​

Get by Id

Get list

Get by field

Get items count

Create

Update

Upsert Bulk

Aggiunta di elementi a una fieldcollection

Delete by Id

Relazioni

Payload con `assign`

Payload con `create` / `upsert`